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's name (RDN), type, and ADS path.
Get the ADS path of the container or organizational unit where the object is located.
Retrieve the object's schema definition.
Load object's properties to the property cache and commit changes to the directory.
Access and modify object's 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 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 for a given property by name.
PutEx()
Sets a value for a single or multi-valued property by name.
SetInfo()
Saves the cached property values of the ADSI object to the directory store.

Properties

Property
Description
ADsPath
Gets the object's ADS path that uniquely identifies this directory object from all others.
Class
Gets the name of the object's schema class.
GUID
Gets the globally unique identifier (GUID) of the object as stored in the directory.
Name
Gets the object's relative name (RDN).
Parent
Gets the ADS path string for 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 as either an object for a single-valued property or an object[] array for a property that allows multiple values.

object Get(string name)

Parameters

The name parameter specifies the property name.

Return value

An object that represents the value of the property. For a multi-valued property, the method returns an object[] array, unless the property is a binary type. In the latter case, the method returns an array of bytes (Byte[]).

Remarks

This method requires that you handle the single- and multi-valued property values differently. Thus, if you know that the requested property is either single- or multi-valued, use the Get method to retrieve the property value.

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

You can also use GetEx to retrieve property values. The method returns property values as an object[] array, regardless of whether the property is single-valued or multi-valued. This saves you the effort of validating the data types when unsure that the returned data has single or multiple values.

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 object
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Get single-valued property
$homePhoneNumber = $user.Get("homePhone")
Write-Host "Home Phone Number: $homePhoneNumber"

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

C#

using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.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);

        //Get single-valued property
        string homePhoneNumber = (string)user.Get("homePhone");
        Console.WriteLine(homePhoneNumber);

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

GetEx()

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

object GetEx(string name)

Parameters

The name parameter specifies the property name.

Return value

An object[] array of property values.

Remarks

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

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

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 object
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

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

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

C#

using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.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);

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

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

GetInfo()

Loads 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 values of the supported properties from the directory. A call of GetInfo loads or reloads the entire property cache, overwriting all the cached property values.

Since a call of GetInfo overwrites all the values in the property cache, any change 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 those 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 store.

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 object
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Get homePhone property. Assume value is 550-440-330.
Write-Host "Home Phone Number:" $user.Get("homePhone")

# Put with no commit(SetInfo)
$user.Put("homePhone","550-440-331")

# Value=550-440-331 from the cache
Write-Host "New Home Phone Number:" $user.Get("homePhone")

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

C#

using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.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);

        // Get homePhone property. Assume value is 550-440-330.
        string homePhoneNumber = (string)user.Get("homePhone");
        Console.WriteLine(homePhoneNumber);

        // Put with no commit(SetInfo)
        user.Put("homePhone", "550-440-331");

        // Value=550-440-331 from the cache
        Console.WriteLine(user.Get("homePhone"));

        // Refresh the cache, get the data, value will be 550-440-330
        user.GetInfo();
        Console.WriteLine(user.Get("homePhone")); 
    }
}

GetInfoEx()

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

void GetInfoEx(string[] properties, int reserved)

Parameters

properties - Array of string entries that list the properties to load into the property cache. Each property name must match one in this object's schema class definition.
reserved - Reserved for future use. Must be set to zero.

Remarks

This method overwrites any previously cached values of the specified properties with those in the directory. Therefore, any changes made to the cache will be lost if SetInfo was not invoked before the call to GetInfoEx.

Use GetInfoEx to refresh values of specific properties in the property cache of a directory object. Use GetInfo to refresh all the property values.

For a container or organizational unit, GetInfoEx caches only the property values of the container, but not those 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 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.
# Cache should have givenName and sn values.
$user.GetinfoEx(@("givenName","sn"), $null)
Write-Host $user.Get("givenName")
Write-Host $user.Get("sn")

# If the "homePhone" property is not in the cache (in the next line)
# GetInfo is called implicitly.
Write-Host $user.Get("homePhone")

C#

using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.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);

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

        // If the "homePhone" property is not in the cache (in the next line)
        // GetInfo is called implicitly.
        Console.WriteLine(user.Get("homePhone"));
    }
}

Put()

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

void Put(string name, object value)

Parameters

name - Specifies the property name.
value - Specifies the new values of the property.

Remarks

The assignment of the new property values, performed by this method, takes place in the property cache only. 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 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 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.Interop.Adsi;
using Softerra.Adaxes.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 performed by this method take place in the property cache of the directory object.

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

Parameters

controlCode - Control code that indicates the mode of modification: Append, Replace, Remove, and Delete.
name - Specifies the property name.
value - Contains an object[] array that contains the new value or values of the property. 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 usually used to set values on multi-valued properties. Since PutEx only makes changes to property values contained in the property cache, you must call SetInfo in order to commit changes to the directory.

PutEx enables you to append values to an existing set of values in 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 succeeds, but the duplicate value is ignored.

Similarly, if you use PutEx to delete one or more values from a multi-valued property of a directory object, the operation succeeds, that is, it will not produce an error, even if any or all of the specified values are not set on the property.

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 object
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Assume the otherHomePhone has the values 550-440-330, 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.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
using Softerra.Adaxes.Interop.Adsi.Cache;
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);
            
        // Assume the otherHomePhone has the values 550-440-330, 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 ADSI object to the directory store.

void SetInfo()

Remarks

It is important to emphasize the differences between the Put and SetInfo methods. The former sets (or modifies) 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.

Because SetInfo sends data across networks, minimize the usage of this method. This reduces the number of trips a client makes to the server.

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

Examples

The following code sample uses the SetInfo method to save the property value of a user to the underlying 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 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","Jo")
$user.Put("givenName","Snow")
$user.Put("streetAddress","1 Tanka Place")
$user.Put("l","Sammamish")
$user.Put("st","Washington")

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

C#

using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.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", "Jo");
        user.Put("givenName", "Snow");
        user.Put("streetAddress", "1 Tanka Place");
        user.Put("l", "Sammamish");
        user.Put("st", "Washington");

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

ADsPath

Gets the object's ADS path that uniquely identifies this directory object from all others. 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 returned from the GUID property is a string of hexadecimals. Use the GUID to bind to the directory object directly.

Adaxes://servername/<GUID=xxx>

Where xxx is the value returned from the GUID 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 string for 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

Return value

Remarks

Examples

GetEx()

Parameters

Return value

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