IAdmTop

The IAdmTop interface represents the base interface for accessing any ADSI object defining the properties and methods common for any such object. Any ADSI object in Adaxes implements this interface.

You can use the IAdmTop interface to:

  • Obtain a snapshot (i.e. a serialized instance of any object) from the directory loading only the properties that you need and manage such properties locally via the IAdmObjectSnapshot interface.
  • Retrieve a modification log of any object.
  • Update the ADS path of an object when such a path becomes invalid.
  • Retrieve such information on an object as the list of its ancestors or a list of the groups the object is an indirect or direct member of.
  • Get the user object that was used to bind to a specific object in
    the directory.

Inheritance: IADs

Methods

  • Method

  • Description

  • GetModificationLog()

  • Returns the object modification log.

  • GetSnapshot()

  • Loads the properties specified in the properties parameter from the directory and returns a snapshot of the current object.

  • SetInfoEx()

  • Persists the changes of the specified properties to the directory.

  • UpdateAdsPath()

  • Updates the ADS path of the object if the path is invalid.

Properties

  • Property

  • Description

  • DirectMemberOf

  • Gets an array of group GUIDs that this object is a direct member of.

  • MemberOf

  • Gets an array of GUIDs of all the groups that this object is a direct or indirect member of.

  • Ancestors

  • Gets an array of GUIDs of the ancestors of this object.

  • BoundAs

  • Gets the user whose credentials were used to bind to this object.

Details

GetModificationLog()

Returns the object modification log. The log is represented by the IAdmModificationLog interface, which allows you to retrieve log entries of any changes that were performed on the current IAdmTop object.

IAdmModificationLog GetModificationLog()

Remarks

Note that log records for this object will only be available when the IAdmModificationLog::Enabled property is set to TRUE.

Examples

The following code sample outputs all operations performed on a user account.

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

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

# Bind to the target user
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $admService.OpenObject("Adaxes://$userDN", $NULL, $NULL, 0)

# Get modification log
$modificationLog = $user.GetModificationLog()

# Get all log records
$log = $modificationLog.Log
$pageCount = $log.PageCount

for ($i = 0; $i -lt $pageCount; $i++)
{
    # Get the current page of log records
    $logRecords = $log.GetPage($i)

    # Output information contained in each record
    foreach ($record in $logRecords)
    {
        Write-Host "Target object name: " $record.TargetObjectName
        Write-Host "Description of operation: " $record.Description
        Write-Host "Target object type: " $record.TargetObjectType
        Write-Host "Initiator name: " $record.Initiator.Name
        Write-Host "Start time: " $record.StartTime.DateTime
        Write-Host "Completion time: " $record.CompletionTime.DateTime
        Write-Host
    }
}
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.Logging;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

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

        // Bind to the target user
        const String userPath = "Adaxes://CN=John Smith,DC=domain,DC=com";
        IAdmTop user = (IAdmTop) admService.OpenObject(userPath, null, null, 0);

        // Get modification log
        IAdmModificationLog modificationLog = user.GetModificationLog();

        // Get all log records
        IAdmLog log = modificationLog.Log;
        int pageCount = log.PageCount;

        for (int i = 0; i < pageCount; i++)
        {
            // Get the current page of log records
            IAdmLogRecords logRecords = log.GetPage(i);

            // Output information contained in each record
            foreach (IAdmLogRecord record in logRecords)
            {
                IAdmLogRecord2 record2 = (IAdmLogRecord2)record;
                Console.WriteLine("Target object name: {0}", record2.TargetObjectName);
                Console.WriteLine("Description of operation: {0}", record.Description);
                Console.WriteLine("Target object type: {0}", record2.TargetObjectType);
                Console.WriteLine("Initiator name: {0}", record.Initiator.Name);
                Console.WriteLine("Start time: {0}", record.StartTime);
                Console.WriteLine("Completion time: {0}", record.CompletionTime);
                Console.WriteLine();
            }
        }
    }
}

GetSnapshot()

Loads the properties specified in the properties parameter from the directory and returns a snapshot of the current object. A snapshot is a serialized object that is not bound to the directory and contains the properties specified (provided that they exist in the directory). You can further use the retrieved IAdmObjectSnapshot interface to manage the loaded object properties locally.

IAdmObjectSnapshot GetSnapshot(String[] properties)

Parameters

The properties parameter contains an array of String entries representing the names of the properties that will be loaded.

SetInfoEx()

Persists the changes of the specified properties to the directory.

void SetInfoEx(String[] properties)

Parameters

The properties parameter contains an array of String entries listing the property names to persist.

UpdateAdsPath()

Updates the ADS path of the object if the path is invalid. An ADS path becomes invalid when an object is renamed or moved, for example.

void UpdateAdsPath()

Examples

The following code sample moves a user to another Organizational Unit and outputs the updated ADS path.

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

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

# Bind to the target Organizational Unit
$targetOUDN = "OU=TargetOU,DC=domain,DC=com"
$targetOU = $admService.OpenObject("Adaxes://$targetOUDN",`
    $NULL, $NULL, 0)

# Bind to the user
$userDN = "CN=John Smith,OU=SourceOU,DC=domain,DC=com"
$user = $admService.OpenObject("Adaxes://$userDN",`
    $NULL, $NULL, 0)

# Move the user to the Organizational Unit
$targetOU.MoveHere($user.AdsPath, $NULL) | Out-Null

# ADS path of the user before update
Write-Host "Old user AdsPath: " $user.AdsPath

# Update ADS path
$user.UpdateAdsPath()

# Resulting ADS path
Write-Host "New user AdsPath: " $user.AdsPath
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 adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        // Bind to the target Organizational Unit
        const String targetOUPath = "Adaxes://CN=TargetOU,DC=domain,DC=com";
        IADsContainer targetOU = (IADsContainer) admService.OpenObject(
            targetOUPath, null, null, 0);

        // Bind to the user
        const String userDN = "CN=John Smith,OU=SourceOU,DC=domain,DC=com";
        IAdmTop user = (IAdmTop) admService.OpenObject("Adaxes://" + userDN, null, null, 0);

        // Move the user to the Organizational Unit
        targetOU.MoveHere(user.ADsPath, null);

        // ADS path of the user before update
        Console.WriteLine("Old user AdsPath: {0}", user.ADsPath);

        // Update ADS path
        user.UpdateAdsPath();

        // Resulting ADS path
        Console.WriteLine("New user AdsPath: {0}", user.ADsPath);
    }
}

DirectMemberOf

Gets an array of group GUIDs that this object is a direct member of. Each GUID is stored in the form of an array of byte (Byte[]), and the parameter itself is an array of arrays of byte (Byte[][]).

  • Type:
  • Object
  • Access:
  • Read-only

Examples

The following code sample outputs all groups a user is a direct member of.

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

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

# Bind to the target user
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $admService.OpenObject("Adaxes://$userDN", $NULL, $NULL, 0)

# Get GUIDs of all groups the user is a direct member of
$groupGuidsBytes = $user.DirectMemberOf

Write-Host "Group names:"
foreach ($groupGuidBytes in $groupGuidsBytes)
{
    # Bind to the group
    $guid = [Guid]$groupGuidBytes
    $guidPath = "Adaxes://<Guid=$guid>"
    $group = $admService.OpenObject($guidPath, $NULL, $NULL, 0)

    # Get the group name
    Write-Host "`t" $group.Get("name")
}
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 adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        // Bind to the target user
        const String userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmTop user = (IAdmTop) admService.OpenObject(userPath, null, null, 0);

        // Get GUIDs of all groups the user is a direct member of
        Object[] groupGuidsBytes = (Object[]) user.DirectMemberOf;

        Console.WriteLine("Group names:");
        foreach (Byte[] groupGuidBytes in groupGuidsBytes)
        {
            // Bind to the group
            String guid = new Guid(groupGuidBytes).ToString("B");
            String guidPath = String.Format("Adaxes://<GUID={0}>", guid);
            IADs group = (IADs) admService.OpenObject(guidPath, null, null, 0);

            // Output the group name
            Console.WriteLine("\t{0}", group.Get("name"));
        }
    }
}

MemberOf

Gets an array of GUIDs of all the groups that this object is a direct or indirect member of. Each GUID is stored in the form of an array of byte (Byte[]), and the parameter itself is an array of arrays of byte (Byte[][]).

  • Type:
  • Object
  • Access:
  • Read-only

Examples

The following code sample outputs all groups a user is a member of (including direct and indirect membership).

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

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

# Bind to the target user
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $admService.OpenObject("Adaxes://$userDN", $NULL, $NULL, 0)

# Get GUIDs of all groups the user is a member of (via direct and indirect membership)
$groupGuidsBytes = $user.MemberOf

Write-Host "Group names:"
foreach ($groupGuidBytes in $groupGuidsBytes)
{
    # Bind to the group
    $guid = [Guid]$groupGuidBytes
    $guidPath = "Adaxes://<Guid=$guid>"
    $group = $admService.OpenObject($guidPath, $NULL, $NULL, 0)

    # Output the group name
    Write-Host "`t" $group.Get("name")
}
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 adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        // Bind to the target user
        const String userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmTop user = (IAdmTop) admService.OpenObject(userPath, null, null, 0);

        // Get GUIDs of all groups the user is a member of (via direct and indirect membership)
        Object[] groupGuidsBytes = (Object[]) user.MemberOf;

        Console.WriteLine("Group names:");
        foreach (Byte[] groupGuidBytes in groupGuidsBytes)
        {
            // Bind to the group
            String guid = new Guid(groupGuidBytes).ToString("B");
            String guidPath = String.Format("Adaxes://<GUID={0}>", guid);
            IADs group = (IADs) admService.OpenObject(guidPath, null, null, 0);

            // Output the group name
            Console.WriteLine("\t{0}", group.Get("name"));
        }
    }
}

Ancestors

Gets an array of GUIDs of the ancestors of this object. The GUIDs are ordered in the array in such a manner that the GUID of the first parent object is the first element and the GUID of the top ancestor is the last one. Each GUID is stored in the form of an array of byte (Byte[]), and the parameter itself is an array of arrays of byte (Byte[][]).

  • Type:
  • Object
  • Access:
  • Read-only

Examples

The following code sample checks whether a user is a descendant of a specific Organizational Unit.

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

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

# Bind to the user
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $admService.OpenObject("Adaxes://$userDN", $NULL, $NULL, 0)

# Bind to the Organizational Unit
$containerDN = "OU=New York,DC=domain,DC=com"
$container = $admService.OpenObject("Adaxes://$containerDN", $NULL, $NULL, 0)

# Get the GUID and the name of the Organizational Unit
$containerName = $container.Get("name")
$containerGuid = [Guid]$container.Get("objectGuid")

foreach ($ancestorGuid in $user.Ancestors)
{
    if ([Guid]$ancestorGuid -ne $containerGuid)
    {
        continue
    }

    Write-Host "User is a descendant of '$containerName'"
    return
}

Write-Host "User is not a descendant of '$containerName'"
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 adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        // Bind to the user
        const String userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmTop user = (IAdmTop) admService.OpenObject(userPath, null, null, 0);

        // Get GUIDs of all ancestors of the user
        Object[] ancestorGuidsByte = (Object[]) user.Ancestors;

        // Bind to the Organizational Unit
        const String containerPath = "Adaxes://OU=New York,DC=domain,DC=com";
        IADs container = (IADs) admService.OpenObject(containerPath, null, null, 0);

        // Get the GUID and the name of the Organizational Unit
        String containerName = (String) container.Get("name");
        byte[] containerGuidBytes = (byte[]) container.Get("objectGuid");
        Guid containerGuid = new Guid(containerGuidBytes);

        foreach (byte[] ancestorGuidBytes in ancestorGuidsByte)
        {
            Guid ancestorGuid = new Guid(ancestorGuidBytes);
            if (ancestorGuid != containerGuid)
            {
                continue;
            }

            Console.WriteLine("User is a descendant of '{0}'", containerName);
            return;
        }

        Console.WriteLine("User is not a descendant of '{0}'", containerName);
    }
}

BoundAs

Gets the user whose credentials were used to bind to this object.

  • Type:
  • IADs
  • Access:
  • Read-only

Requirements

Minimum required version: 2009.1

See also

© Softerra 2021. All rights reserved.
Send feedback