IADsPropertyList

The IADsPropertyList interface is used to modify, read, and update a list of property entries in the property cache of an object. It serves to enumerate, modify, and purge the contained property entries. Use the enumeration method of this interface to identify initialized properties. This is different from using the schema to determine all possible attributes that a directory object can have and which properties have been set.

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 in the persistent store of 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()

  • Deletes all properties from the list and releases the property caches.

  • 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, counting from the current cursor position, in the property list.

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 - Specifies the name of the requested property.
  • type - Specifies the data type to be used in interpreting the requested property. 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.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 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

The index parameter is an object that contains the index or name of the property to be retrieved.

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.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 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()

Deletes all properties from the list and releases the property caches.

void PurgePropertyList()

Remarks

When this method is called, all the items are removed from the cache. Thus, 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.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;

        // 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

The item parameter represents new property values to be put in the property cache. The object passed to this method must expose the IADsPropertyEntry interface.

Remarks

The IADsPropertyEntry::ControlCode property should be set to the desired modify, add, or delete operation by using the proper ADS_PROPERTY_OPERATION_ENUM value. After PutPropertyItem is called, call IADs::SetInfo to persist any changes in the directory. The property values are not committed until the method is called.

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 store
$user.SetInfo()
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 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 store
        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.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.Cache;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

internal class Program
{
    private 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

The data parameter specifies the property entry to be reset. You can specify the item to be removed by name (as a string) or by index (as an Integer).

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 store
$user.SetInfo()

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

$user.ResetPropertyItem("description")

# The property count should have been reduced by one
Write-Host "Number of Properties = "$user.PropertyCount
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 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 store
        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 have been reduced by one
        Console.WriteLine("Number of Properties = {0}", propertyList.PropertyCount);
    }
}

Skip()

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

void Skip(int count)

Parameters

The count parameter specifies the number of elements 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 System.Runtime.InteropServices;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.Cache;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

internal class Program
{
    private 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