IADs

The IADs interface can be used to manage properties of a directory object and obtain basic information about the object, such as the ADS path, object type, and relative distinguished name (RDN).

Examples of directory objects include users, computers, groups, organizational units, and Adaxes-specific objects, such as security roles, property patterns, business units, and scheduled tasks.

Using the IADs interface, you can:

Get the object name (RDN), type, and ADS path.
Get the ADS path of the container or organizational unit where the object is located.
Retrieve the object schema definition.
Load the object properties into the property cache and commit changes to the directory.
Access and modify the object properties in the property cache.

Inheritance: IDispatch

Methods

Method
Description
Get()
Gets the value of a property by name.
GetEx()
Gets the value of a single or multi-valued property by name.
GetInfo()
Loads the values of the supported properties of the directory object into the property cache.
GetInfoEx()
Loads specific property values of the directory object into the property cache.
Put()
Sets a value of a property by name.
PutEx()
Sets a value of a single or multi-valued property by name.
SetInfo()
Saves the cached property values of the object to the directory.

Properties

Property
Description
ADsPath
Gets the ADS path that uniquely identifies this directory object.
Class
Gets the name of the object schema class.
GUID
Gets the globally unique identifier (GUID) of the object as stored in the directory.
Name
Gets the object's relative distinguished name (RDN).
Parent
Gets the ADS path of the parent container or organizational unit of the object.
Schema
Gets the ADS path string to the schema class object for the directory object.

Details

Get()

Gets the value of a property by name. The property can be single-valued or multi-valued. The property value is represented either as an object if there is one value, or an object[] array if there are several. It is important to point out that a multi-valued property with one value counts as a single value, so an object will be returned.

If the multi-valued property is of a binary type, the method returns an array of bytes (Byte[]).

object Get(string name)

Parameters

name – the property name.

Remarks

This method requires you to handle return values differently, depending on whether the property has one or several values.

You can also use GetEx to retrieve property values. That method always returns property values as an object[] array. It saves you the effort of validating the data types when unsure whether the returned data has single or multiple values.

When a property is uninitialized, calling Get method loads the property value from the directory and saves it to the property cache. Any subsequent calls to Get retrieve property values from the cache.

Examples

The following code sample shows how to use Get to retrieve object properties.

PowerShell

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object("Softerra.Adaxes.Adsi.AdmNamespace")
$service = $ns.GetServiceDirectly("localhost")

# Bind to an object.
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Get a single-valued property.
$homePhoneNumber = $user.Get("homePhone")
Write-Host "Home phone number: $homePhoneNumber"

# Get a multi-valued property.
$otherNumbers = $user.Get("otherHomePhone")
foreach($homeNum in $otherNumbers)
{
    Write-Host "Other phone numbers: $homeNum"
}

C#

using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to an object.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(userPath, null, null, 0);

        // Get a single-valued property.
        string homePhoneNumber = (string)user.Get("homePhone");
        Console.WriteLine($"Home phone number: {homePhoneNumber}");

        // Get a multi-valued property.
        Array otherNumbers = (Array)user.Get("otherHomePhone");
        foreach (string homeNum in otherNumbers)
        {
            Console.WriteLine($"Other phone numbers: {homeNum}");
        }
    }
}

GetEx()

Gets the value of a property by name. The property can be single-valued or multi-valued. Unlike the Get method, the property values are always returned as an object[] array. A single-valued property is represented as an array with a single element.

object GetEx(string name)

Parameters

name – the property name.

Remarks

The Get and GetEx methods return different data structures for a property with a single value. For example, if the property is a string, Get returns a string object, whereas GetEx returns a string[] array with a single element. If you are not sure whether a multi-valued property will return one or multiple values, use GetEx.

When a property is uninitialized, calling GetEx method loads the property value from the directory and saves it to the property cache. Any subsequent calls to GetEx retrieve property values from the cache.

Examples

The following code sample shows how to use GetEx to retrieve object properties.

PowerShell

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object("Softerra.Adaxes.Adsi.AdmNamespace")
$service = $ns.GetServiceDirectly("localhost")

# Bind to an object.
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Get a single-valued property.
$homePhoneNumber = $user.GetEx("homePhone")
Write-Host "Home phone number: $homePhoneNumber"

# Get a multi-valued property.
$otherNumbers = $user.GetEx("otherHomePhone")
foreach($homeNum in $otherNumbers)
{
    Write-Host "Other phone numbers: $homeNum"
}

C#

using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to an object.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(userPath, null, null, 0);

        // Get a single-valued property.
        object[] homePhoneNumber = (object[])user.GetEx("homePhone");
        foreach (string homePhone in homePhoneNumber)
        {
            Console.WriteLine($"Home phone number: {homePhone}");
        }

        // Get a multi-valued property.
        Array otherNumbers = (Array)user.GetEx("otherHomePhone");
        foreach (string homeNum in otherNumbers)
        {
            Console.WriteLine($"Other phone numbers: {homeNum}");
        }
    }
}

GetInfo()

Loads the values of the supported properties of the directory object into the property cache.

void GetInfo()

Remarks

This method is used to initialize or refresh the property cache by loading the values of the supported properties from the directory. A call of GetInfo loads or reloads the entire property cache, overwriting the already cached values.

Since a call of GetInfo overwrites all the values in the property cache, any changes made to the cache will be lost if SetInfo was not invoked before GetInfo.

For a container or organizational unit, GetInfo caches only the property values of the container object, but not of the child objects.

It is important to emphasize the differences between the Get and GetInfo methods. The former returns values of a given property from the property cache whereas the latter loads all the supported properties into the property cache from the directory.

For increased performance, call GetInfoEx to refresh only specific properties. Also, GetInfoEx must be called instead of GetInfo if the object's operational property values have to be accessed.

Examples

The following code sample shows how to use the GetInfo method.

PowerShell

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object("Softerra.Adaxes.Adsi.AdmNamespace")
$service = $ns.GetServiceDirectly("localhost")

# Bind to an object.
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Get the homePhone property. Let's assume the value is 550-440-330.
Write-Host "Home phone number:" $user.Get("homePhone")

# Put without saving changes (SetInfo).
$user.Put("homePhone","550-440-331")

# Get the value of 550-440-331 from the cache.
Write-Host "New home phone number:" $user.Get("homePhone")

# Refresh the cache, get the data. The value will be 550-440-330.
$user.GetInfo()
Write-Host "Home phone number:" $user.Get("homePhone")

C#

using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to an object.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(userPath, null, null, 0);

        // Get the homePhone property. Let's assume the value is 550-440-330.
        string homePhoneNumber = (string)user.Get("homePhone");
        Console.WriteLine($"Home phone number: {homePhoneNumber}");

        // Put without saving changes (SetInfo).
        user.Put("homePhone", "550-440-331");

        // Get the value of 550-440-331 from the cache.
        Console.WriteLine($"New home phone number: {user.Get("homePhone")}");

        // Refresh the cache, get the data. The value will be 550-440-330.
        user.GetInfo();
        Console.WriteLine($"Home phone number: {user.Get("homePhone")}"); 
    }
}

GetInfoEx()

Loads specific property values of the directory object into the property cache.

void GetInfoEx(string[] properties, int reserved)

Parameters

properties – an array of string items that represent the names of properties to load. Each property name must match one in this object's schema class definition.
reserved – must be set to zero.

Remarks

Since a call of GetInfoEx overwrites all cached values of the specified properties, any changes made to the cache will be lost if SetInfo was not invoked before GetInfoEx.

For a container or organizational unit, GetInfoEx caches only the property values of the container, but not of the child objects.

Examples

The following code sample shows how to use the GetInfoEx method.

PowerShell

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object("Softerra.Adaxes.Adsi.AdmNamespace")
$service = $ns.GetServiceDirectly("localhost")

# Bind to an object.
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Retrieve givenName and sn from the directory.
$user.GetinfoEx(@("givenName","sn"), $null)
Write-Host $user.Get("givenName")
Write-Host $user.Get("sn")

# homePhone is not in the cache, so GetInfo is called implicitly.
Write-Host $user.Get("homePhone")

C#

using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to an object.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(
            userPath, null, null, 0);

        // Retrieve givenName and sn from the directory.
        string[] attributes = { "givenName", "sn" };
        user.GetInfoEx(attributes, 0);
        Console.WriteLine(user.Get("givenName"));
        Console.WriteLine(user.Get("sn"));

        // homePhone is not in the cache, so GetInfo is called implicitly.
        Console.WriteLine(user.Get("homePhone"));
    }
}

Put()

Sets a value for a given property. The value is set in the property cache of the directory object.

void Put(string name, object value)

Parameters

name – the property name.
value – the new property values.

Remarks

This method updates the property values only in the property cache. To propagate the changes to the directory, call SetInfo on the object after calling Put.

To manipulate the property values beyond a simple assignment, use PutEx. For example, to append or remove a value from an existing array of property values.

Examples

The following code sample shows how to use the Put method.

PowerShell

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object("Softerra.Adaxes.Adsi.AdmNamespace")
$service = $ns.GetServiceDirectly("localhost")

# Bind to an object.
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Put givenName and sn property in the cache.
$user.Put("givenName","Jo")
$user.Put("sn","Snow")

# Commit to the directory.
$user.SetInfo()

C#

using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to object.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(userPath, null, null, 0);

        // Put givenName and sn property in the cache.
        user.Put("givenName","Jo");
        user.Put("sn", "Snow");

        // Commit to the directory.
        user.SetInfo();
    }
}

PutEx()

Sets a value for a single or multi-valued property by name. For properties that allow multiple values, you can append additional values to an existing set of values, modify the values in the set, remove specified values from the set, or delete values from the set. The changes are applied in the property cache of the directory object.

void PutEx(ADS_PROPERTY_OPERATION_ENUM controlCode,
           string name, 
           object[] value)

Parameters

controlCode – a control code that indicates the modification mode: Append, Replace, Remove, and Delete.
name – the property name.
value – an object[] array that contains property values. A single-valued property is represented as an array with a single element. If the controlCode parameter is set to ADS_PROPERTY_CLEAR, the value of the property specified by the value parameter is irrelevant.

Remarks

This method is used to set values on multi-valued properties. Since PutEx only makes changes to property values in the property cache, you must call SetInfo to commit changes to the directory.

PutEx enables you to append values to an existing set of values of a multi-valued property using the ADS_PROPERTY_APPEND control code. Duplicate values are not accepted for multi-valued properties. If you call PutEx to append a duplicate value to a multi-valued property of a directory object, the PutEx call will succeed, but the duplicate value will be ignored.

Similarly, if you use PutEx to delete one or more values from a multi-valued property of a directory object, the operation will not throw an error, even if all of the specified values do not exist.

Examples

The following code sample shows how to use the PutEx method.

PowerShell

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object("Softerra.Adaxes.Adsi.AdmNamespace")
$service = $ns.GetServiceDirectly("localhost")

# Bind to an object.
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Let's assume otherHomePhone has the values 550-440-330 and 550-440-331.

# Adding a value.
$user.PutEx("ADS_PROPERTY_APPEND", "otherhomePhone", @("550-440-332"))
$user.SetInfo() # Now the values are 550-440-330, 550-440-331, 550-440-332. 

# Deleting two values.
$user.PutEx("ADS_PROPERTY_DELETE", "otherhomePhone", @("550-440-330","550-440-331"))
$user.SetInfo() # Now the values are 550-440-332.

# Changing the remaining value.
$user.PutEx("ADS_PROPERTY_UPDATE", "otherhomePhone", @("550-440-333","550-440-334"))
$user.SetInfo() # Now the values are 550-440-333, 550-440-334.

# Deleting the value.
$user.PutEx("ADS_PROPERTY_CLEAR", "otherhomePhone", $null)
$user.SetInfo() # Now the property has no value.

C#

using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.Cache;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to an object
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(userPath, null, null, 0);
            
        // Let's assume otherHomePhone has the values 550-440-330 and 550-440-331.
    
        // Adding a value.
        object[] values = { "550-440-332" };
        user.PutEx(ADS_PROPERTY_OPERATION_ENUM.ADS_PROPERTY_APPEND,
            "otherhomePhone", values);
        user.SetInfo(); // Now the values are 550-440-330, 550-440-331, 550-440-332.

        // Deleting two values.
        values = new object[] { "550-440-330", "550-440-331" };
        user.PutEx(ADS_PROPERTY_OPERATION_ENUM.ADS_PROPERTY_DELETE,
            "otherhomePhone", values);
        user.SetInfo(); // Now the values are 550-440-332.

        // Changing the remaining value.
        values = new object[] { "550-440-333", "550-440-334" };
        user.PutEx(ADS_PROPERTY_OPERATION_ENUM.ADS_PROPERTY_UPDATE,
            "otherhomePhone", values);
        user.SetInfo(); // Now the values are 550-440-333, 550-440-334.

        // Deleting the value.
        user.PutEx(ADS_PROPERTY_OPERATION_ENUM.ADS_PROPERTY_CLEAR,
            "otherhomePhone", null);
        user.SetInfo(); // Now the property has no value.
    }
}

SetInfo()

Saves the cached property values of the object to the directory.

void SetInfo()

Remarks

It is important to emphasize the differences between the Put and SetInfo methods. The former modifies the values of a given property in the property cache, whereas the latter propagates the changes from the property cache into the directory. Therefore, any property value changes made by Put will be lost if GetInfo (or GetInfoEx) is invoked before SetInfo is called.

Minimize the usage of SetInfo because it sends data across the network.

To only save the values of specific properties, use IAdmTop::SetInfoEx.

Examples

The following code sample uses the SetInfo method to save the property value of a user to the directory.

PowerShell

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object("Softerra.Adaxes.Adsi.AdmNamespace")
$service = $ns.GetServiceDirectly("localhost")

# Bind to an object.
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Update values in the cache.
$user.Put("sn", "Bond")
$user.Put("givenName", "James")
$user.Put("streetAddress", "30 Wellington Square")
$user.Put("l", "London")

# Commit changes to the directory.
$user.SetInfo()

C#

using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to object.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(userPath, null, null, 0);

        // Update values in the cache.
        user.Put("sn", "Bond");
        user.Put("givenName", "James");
        user.Put("streetAddress", "30 Wellington Square");
        user.Put("l", "London");

        // Commit changes to the directory.
        user.SetInfo();
    }
}

ADsPath

Gets the object's ADS path that uniquely identifies it. The object can always be retrieved using this path.

Type:
string
Access:
Read-only

Class

Gets the name of the object's schema class.

Type:
string
Access:
Read-only

GUID

Gets the globally unique identifier (GUID) of the object as stored in the directory. The IADs interface converts the GUID from an octet string, as stored on a directory server, into a string format.

Type:
string
Access:
Read-only

Remarks

The GUID value returned from property is a string of hexadecimals. Use this GUID to bind to the directory object directly.

Adaxes://servername/<GUID=xxx>

Where xxx is the value returned from the property.

Name

Gets the object's relative name (RDN). This name distinguishes this object from its siblings. Example: CN=John Smith.

Type:
string
Access:
Read-only

Parent

Gets the ADS path of the parent container or organizational unit of the object.

Type:
string
Access:
Read-only

Schema

Gets the ADS path string to the schema class object for the directory object.

Type:
string
Access:
Read-only

Requirements

Minimum required version: 2009.1

Send feedback

IADs

Methods

Method

Description

Properties

Property

Description

Details

Get()

Parameters

Remarks

Examples

GetEx()

Parameters

Remarks

Examples

GetInfo()

Remarks

Examples

GetInfoEx()

Parameters

Remarks

Examples

Put()

Parameters

Remarks

Examples

PutEx()

Parameters

Remarks

Examples

SetInfo()

Remarks

Examples

ADsPath

Class

GUID

Remarks

Name

Parent

Schema

Requirements