IADsPropertyList

The IADsPropertyList interface is used to modify, read, and update a list of property entries in the property cache of an object. It allows you to enumerate, modify, and purge the contained property entries.

Call methods of this interface to examine and manipulate the property list on the client. Before calling the methods of this interface, you need to call IADs::GetInfo or IADs::GetInfoEx explicitly to load the assigned property values of the object into the cache. After calling the methods of this interface, call IADs::SetInfo to save the changes to the directory.

Inheritance: IDispatch

Methods

  • Method

  • Description

  • GetPropertyItem()

  • Gets the value of a property by name.

  • Item()

  • Gets a property that is specified by name or by index.

  • Next()

  • Gets the next item in the property list.

  • PurgePropertyList()

  • Removes all properties from the list and releases the property cache.

  • PutPropertyItem()

  • Updates the values for an item in the property list.

  • Reset()

  • Moves back to the start of the list.

  • ResetPropertyItem()

  • Removes the specified item from the list.

  • Skip()

  • Skips a specified number of items in the property list, counting from the current cursor position.

Properties

  • Property

  • Description

  • PropertyCount

  • Gets the number of properties in the property list.

Details

GetPropertyItem()

Gets the value of a property by name.

object GetPropertyItem(string propItemName, ADSTYPEENUM type)

Parameters

  • propItemName – the name of the requested property.
  • type – the data type to use in interpreting the requested property value. If the type is unknown, this parameter can be set to ADSTYPE_UNKNOWN.

Return value

The method returns a property entry that exposes the IADsPropertyEntry interface.

Examples

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

$propertyEntry = $user.GetPropertyItem("otherHomePhone", "ADSTYPE_CASE_IGNORE_STRING")

foreach ($value in $propertyEntry.Values)
{
    # Use the CaseIgnoreString property because the ADSTYPE_CASE_IGNORE_STRING
    # type was requested in GetPropertyItem.
    Write-Host $value.CaseIgnoreString
}
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 object.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(userPath, null, null, 0);
        user.GetInfo();

        IADsPropertyList propertyList = (IADsPropertyList)user;

        IADsPropertyEntry propertyEntry =
            (IADsPropertyEntry)propertyList.GetPropertyItem("otherHomePhone",
            ADSTYPEENUM.ADSTYPE_CASE_IGNORE_STRING);

        foreach (IADsPropertyValue value in (Array)propertyEntry.Values)
        {
            // Use the CaseIgnoreString property because the ADSTYPE_CASE_IGNORE_STRING
            // type was requested in GetPropertyItem.
            Console.WriteLine(value.CaseIgnoreString);
        }
    }
}

Item()

Gets a property that is specified by name or by index.

object Item(object index)

Parameters

  • index – an object that contains either the index or the name of the property to retrieve.

Return value

The method returns a property entry that exposes the IADsPropertyEntry interface.

Examples

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.
$ouPath = "Adaxes://OU=My OU,DC=domain,DC=com"
$ou = $service.OpenObject($ouPath, $null, $null, 0)
$ou.GetInfo()

$propertyEntry = $ou.Item("name")

Write-Host "Property name:" $propertyEntry.Name `
    "Property AdsType:" $propertyEntry.ADsType
C#
using System;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.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 object.
        const string ouPath = "Adaxes://OU=My OU,DC=domain,DC=com";
        IADs ou = (IADs)service.OpenObject(ouPath, null, null, 0);
        ou.GetInfo();

        IADsPropertyList propertyList = (IADsPropertyList)ou;

        IADsPropertyEntry propertyEntry = (IADsPropertyEntry)propertyList.Item("name");

        Console.WriteLine("Property name: {0}, Property AdsType: {1}",
            propertyEntry.Name, propertyEntry.ADsType);
    }
}

Next()

Gets the next item in the property list.

object Next()

Return value

The method returns a property entry that exposes the IADsPropertyEntry interface.

Examples

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.
$domainPath = "Adaxes://DC=domain,DC=com"
$domain = $service.OpenObject($domainPath, $null, $null, 0)
$domain.GetInfo()

$propertyCount = $domain.PropertyCount

for ($i = 0; $i -lt $propertyCount; $i++)
{
    $propertyEntry  = $domain.Next()
    Write-Host "Property name:" $propertyEntry.Name `
        "Property AdsType:" $propertyEntry.ADsType
}
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 object.
        const string domainPath = "Adaxes://DC=domain,DC=com";
        IADs domain = (IADs)service.OpenObject(domainPath, null, null, 0);
        domain.GetInfo();

        IADsPropertyList propertyList = (IADsPropertyList)domain;
        int propertyCount = propertyList.PropertyCount;

        for (int i=0; i < propertyCount; i++)
        {
            IADsPropertyEntry propertyEntry = (IADsPropertyEntry)propertyList.Next();
            Console.WriteLine("Property name: {0}, Property AdsType: {1}",
                propertyEntry.Name, propertyEntry.ADsType);
        }
    }
}

PurgePropertyList()

Removes all properties from the list and releases the property cache.

void PurgePropertyList()

Remarks

When this method is called, all the items are removed from the cache. Therefore, calling GetPropertyItem after that will generate an error.

Be aware that PurgePropertyList only affects the contents of the cache and does not affect the properties on the actual object in the directory. Calling IADs::SetInfo after calling PurgePropertyList does not delete the properties of the directory object.

Examples

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.
$ouPath = "Adaxes://OU=My OU,DC=domain,DC=com"
$ou = $service.OpenObject($ouPath, $null, $null, 0)
$ou.GetInfo()

# Output the number of items in the property list
# before calling the PurgePropertyList method.
Write-Host $ou.PropertyCount

# Clear the property list.
$ou.PurgePropertyList()

# Output the number of items in the property list
# after calling the PurgePropertyList method.
Write-Host $ou.PropertyCount
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 object.
        const string ouPath = "Adaxes://OU=My OU,DC=domain,DC=com";
        IADs ou = (IADs)service.OpenObject(ouPath, null, null, 0);
        ou.GetInfo();

        IADsPropertyList propertyList = (IADsPropertyList)ou;

        // Output the number of items in the property list
        // before calling the PurgePropertyList method.
        Console.WriteLine(propertyList.PropertyCount);

        // Clear the property list.
        propertyList.PurgePropertyList();

        // Output the number of items in the property list
        // after calling the PurgePropertyList method.
        Console.WriteLine(propertyList.PropertyCount);
    }
}

PutPropertyItem()

Updates the values for an item in the property list.

void PutPropertyItem(object item)

Parameters

  • item – new property values to put into the cache. The object passed to this method must expose the IADsPropertyEntry interface.

Remarks

The IADsPropertyEntry::ControlCode property should be set to the desired operation by using the proper ADS_PROPERTY_OPERATION_ENUM value.

After PutPropertyItem is called, call IADs::SetInfo to save changes to the directory. The property values are not committed until the method is called.

Examples

The following code samples updates the user's description in the property list and saves the changes 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 object.
$userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject($userPath, $null, $null, 0)
$user.GetInfo()

# Create a property value.
$propertyValue = New-Object "Softerra.Adaxes.Adsi.AdsPropertyValue"
$propertyValue.CaseIgnoreString = "My Description"
$propertyValue.ADsType = "ADSTYPE_CASE_IGNORE_STRING"

# Create a property entry.
$propertyEntry = New-Object "Softerra.Adaxes.Adsi.AdsPropertyEntry"
$propertyEntry.Name = "description"
$propertyEntry.Values =
    @([Softerra.Adaxes.Interop.Adsi.Cache.IADsPropertyValue]$propertyValue)
$propertyEntry.ControlCode = "ADS_PROPERTY_UPDATE"
$propertyEntry.ADsType = "ADSTYPE_CASE_IGNORE_STRING"

# Add the property entry to the property list.
$user.PutPropertyItem($propertyEntry)

# Commit changes to the directory.
$user.SetInfo()
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 object.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(userPath, null, null, 0);
        user.GetInfo();
        IADsPropertyList propertyList = (IADsPropertyList)user;

        // Create a property value.
        IADsPropertyValue propertyValue = new AdsPropertyValue();
        propertyValue.CaseIgnoreString = "My Description";
        propertyValue.ADsType = ADSTYPEENUM.ADSTYPE_CASE_IGNORE_STRING;

        // Create a property entry.
        IADsPropertyEntry propertyEntry = new AdsPropertyEntry();
        propertyEntry.Name = "description";
        object[] values = {propertyValue};
        propertyEntry.Values = values;
        propertyEntry.ControlCode = ADS_PROPERTY_OPERATION_ENUM.ADS_PROPERTY_UPDATE;
        propertyEntry.ADsType = ADSTYPEENUM.ADSTYPE_CASE_IGNORE_STRING;

        // Add the property entry to the property list.
        propertyList.PutPropertyItem(propertyEntry);

        // Commit changes to the directory.
        user = (IADs)propertyList;
        user.SetInfo();

    }
}

Reset()

Moves back to the start of the list.

void Reset()

Examples

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.
$domainPath = "Adaxes://DC=domain,DC=com"
$domain = $service.OpenObject($domainPath, $null, $null, 0)
$domain.GetInfo()

$propertyCount = $domain.PropertyCount

Write-Host "Walking up the property list before item reset:"
for ($i = 0; $i -ne $propertyCount; $i++)
{
    $propertyEntry  = $domain.Next()
    Write-Host "Property name:" $propertyEntry.Name
}

# Move the cursor to the beginning of the list.
$domain.Reset()

Write-Host "Walking up the property list after item reset:"
for ($i = 0; $i -ne $propertyCount; $i++)
{
    $propertyEntry  = $propertyList.Next()
    Write-Host "Property name:" $propertyEntry.Name
}
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 object.
        const string domainPath = "Adaxes://DC=domain,DC=com";
        IADs domain = (IADs) service.OpenObject(domainPath, null, null, 0);
        domain.GetInfo();

        IADsPropertyList propertyList = (IADsPropertyList)domain;

        Console.WriteLine("Walking up the property list before item reset:");
        int propertyCount = propertyList.PropertyCount;

        for (int i = 0; i < propertyCount; i++)
        {
            IADsPropertyEntry propertyEntry = (IADsPropertyEntry)propertyList.Next();
            Console.WriteLine("Property name: {0}", propertyEntry.Name);
        }

        // Move the cursor to the beginning of the list.
        propertyList.Reset();

        Console.WriteLine("Walking up the property list after item reset:");
        for (int i = 0; i < propertyCount; i++)
        {
            IADsPropertyEntry propertyEntry = (IADsPropertyEntry)propertyList.Next();
            Console.WriteLine("Property name: {0}", propertyEntry.Name);
        }
    }
}

ResetPropertyItem()

Removes the specified item from the list.

void ResetPropertyItem(object data)

Parameters

  • data – the property entry to reset. You can specify an item by name (as a string) or by index (as an int).

Remarks

This method only affects the contents of the cache and does not affect the properties on the actual object in the directory. Calling IADs::SetInfo after calling ResetPropertyItem does not delete the properties of the directory object.

Examples

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

# Create a property value.
$propertyValue = New-Object "Softerra.Adaxes.Adsi.AdsPropertyValue"
$propertyValue.CaseIgnoreString = "My Description"
$propertyValue.ADsType = "ADSTYPE_CASE_IGNORE_STRING"

# Create a property entry.
$propertyEntry = New-Object "Softerra.Adaxes.Adsi.AdsPropertyEntry"
$propertyEntry.Name = "description"
$propertyEntry.Values =
    @([Softerra.Adaxes.Interop.Adsi.Cache.IADsPropertyValue]$propertyValue)
$propertyEntry.ControlCode = "ADS_PROPERTY_UPDATE"
$propertyEntry.ADsType = "ADSTYPE_CASE_IGNORE_STRING"

# Add the property entry to the property list.
$user.PutPropertyItem($propertyEntry)

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

$user.GetInfo()
Write-Host "Number of Properties =" $user.PropertyCount

$user.ResetPropertyItem("description")

# The property count should be reduced by one.
Write-Host "Number of Properties =" $user.PropertyCount
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 object.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IADs user = (IADs)service.OpenObject(userPath, null, null, 0);
        user.GetInfo();
        IADsPropertyList propertyList = (IADsPropertyList)user;

        // Create a property value.
        IADsPropertyValue propertyValue = new AdsPropertyValue();
        propertyValue.CaseIgnoreString = "My Description";
        propertyValue.ADsType = ADSTYPEENUM.ADSTYPE_CASE_IGNORE_STRING;

        // Create a property entry.
        IADsPropertyEntry propertyEntry = new AdsPropertyEntry();
        propertyEntry.Name = "description";
        object[] values = { propertyValue };
        propertyEntry.Values = values;
        propertyEntry.ControlCode = ADS_PROPERTY_OPERATION_ENUM.ADS_PROPERTY_UPDATE;
        propertyEntry.ADsType = ADSTYPEENUM.ADSTYPE_CASE_IGNORE_STRING;

        // Add the property entry to the property list.
        propertyList.PutPropertyItem(propertyEntry);

        // Commit changes to the directory.
        user = (IADs)propertyList;
        user.SetInfo();

        user.GetInfo();
        propertyList = (IADsPropertyList)user;
        Console.WriteLine("Number of Properties = {0}", propertyList.PropertyCount);

        propertyList.ResetPropertyItem("description");

        // The property count should be reduced by one.
        Console.WriteLine("Number of Properties = {0}", propertyList.PropertyCount);
    }
}

Skip()

Skips the specified number of items in the property list, counting from the current cursor position.

void Skip(int count)

Parameters

  • count – the number of items to skip.

Examples

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.
$domainPath = "Adaxes://DC=domain,DC=com"
$domain = $service.OpenObject($domainPath, $null, $null, 0)
$domain.GetInfo()

$propertyCount = $domain.PropertyCount

Write-Host "Walking up the property list without skipping:"
for ($i = 0; $i -ne $propertyCount; $i++)
{
    $propertyEntry  = $domain.Next()
    Write-Host "Property name:"$propertyEntry.Name
}

# Move the cursor to the beginning of the list.
$domain.Reset()

Write-Host "Iterate the property list, skipping every other element:"
for ($i = 0; $i -ne $propertyCount; $i+=2)
{
    $domain.Skip(1)
    try
    {
        $propertyEntry = $domain.Next()
        Write-Host "Property name:"$propertyEntry.Name
    }
    catch [System.Runtime.InteropServices.COMException]
    {
        break;
    }
}
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using System.Runtime.InteropServices;
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 object.
        const string domainPath = "Adaxes://DC=domain,DC=com";
        IADs domain = (IADs)service.OpenObject(domainPath, null, null, 0);
        domain.GetInfo();

        IADsPropertyList propertyList = (IADsPropertyList)domain;

        Console.WriteLine("Walking up the property list without skipping:");
        int propertyCount = propertyList.PropertyCount;

        for (int i = 0; i < propertyCount; i++)
        {
            IADsPropertyEntry propertyEntry = (IADsPropertyEntry)propertyList.Next();
            Console.WriteLine("Property name: {0}", propertyEntry.Name);
        }

        // Move the cursor to the beginning of the list.
        propertyList.Reset();

        Console.WriteLine("Parsing the property list, skipping every other element:");
        for (int i = 0; i < propertyCount; i += 2)
        {
            propertyList.Skip(1);
            try
            {
                IADsPropertyEntry propertyEntry = (IADsPropertyEntry)propertyList.Next();
                Console.WriteLine("Property name: {0}", propertyEntry.Name);
            }
            catch (COMException)
            {
                break;
            }
        }
    }
}

PropertyCount

Gets the number of properties in the property list.

  • Type:
  • int
  • Access:
  • Read-only

Requirements

Minimum required version: 2009.1

See also

© Softerra 2022. All rights reserved.
Send feedback