IAdmUser

The IAdmUser interface extends the IADsUser interface with Adaxes-specific functionality. This interface enables you to:

  • Retrieve a list of approval requests that are either initiated by a specific user, or assigned to the user.
  • Create, move, delete, and share user home directories.
  • Fetch the action log of a user. The action log is a list of records describing the actions that were performed in the directory by a specific user.

Inheritance: IADsUser

Derived: IAdmUser2

Methods

Details

GetRequestsForApproval()

Returns an array of GUIDs of approval requests initiated by the user.

object GetRequestsForApproval(ADM_APPROVALSTATE_ENUM requestState)

Parameters

  • requestState – the request state which controls whether the method returns approved, denied, cancelled, or pending approval requests.

Return value

The method returns an array of approval request GUIDs. Each GUID is represented as an array of 16 bytes (Byte[]), and the return value is an array of byte arrays (Byte[][]).

You can bind to approval request objects by their GUIDs. For more information on how to bind to directory objects, see Binding to ADSI objects. Each approval request is represented by the IAdmApprovalRequest interface.

Examples

The following code sample outputs information about pending approval requests initiated by a user.

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

# Get all pending approval requests initiated by the user.
$approvalRequestGuids = $user.GetRequestsForApproval("ADM_APPROVALSTATE_PENDING")

foreach ($requestGuidBytes in $approvalRequestGuids)
{
    # Bind to the approval request.
    $requestGuid = [Guid]$requestGuidBytes
    $requestPath = "Adaxes://<Guid=$requestGuid>"
    $request = $service.OpenObject($requestPath, $null, $null, 0)

    # Output information about the request.
    Write-Host "Operation:" $request.DescriptionOfOperationToApprove
    Write-Host "Requested on" $request.CreationDate.ToShortDateString()
    Write-Host
}
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.ApprovalRequests;
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 the target user.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmUser user = (IAdmUser)service.OpenObject(userPath, null, null, 0);

        // Get all pending approval requests initiated by the user
        object[] approvalRequestGuids = (object[])user.GetRequestsForApproval(
            ADM_APPROVALSTATE_ENUM.ADM_APPROVALSTATE_PENDING);

        foreach (Byte[] requestGuidBytes in approvalRequestGuids)
        {
            // Bind to the approval request.
            string requestGuid = new Guid(requestGuidBytes).ToString("B");
            string requestPath = $"Adaxes://<GUID={requestGuid}>";
            IAdmApprovalRequest request = (IAdmApprovalRequest)service.OpenObject(
                requestPath, null, null, 0);

            // Output information about the request.
            Console.WriteLine("Operation: {0}", request.DescriptionOfOperationToApprove);
            Console.WriteLine("Requested on {0}", request.CreationDate.ToShortDateString());
            Console.WriteLine();
        }
    }
}

GetApprovals()

Returns an array of GUIDs of all the approval requests that are approved, denied, cancelled, or awaiting approval by this user.

object GetApprovals(ADM_APPROVALSTATE_ENUM requestState)

Parameters

  • requestState – the request state which controls whether the method returns approved, denied, cancelled, or pending approval requests.

Return value

The method returns an array of approval request GUIDs. Each GUID is represented as an array of 16 bytes (Byte[]), and the return value is an array of byte arrays (Byte[][]).

You can bind to approval request objects by their GUIDs. For more information on how to bind to directory objects, see Binding to ADSI objects. Each approval request is represented by the IAdmApprovalRequest interface.

Examples

The following code sample outputs information about all approval requests that were denied by a user.

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

# Get all approval requests that were denied by the user.
$approvalRequestGuids = $user.GetApprovals("ADM_APPROVALSTATE_DENIED")

foreach ($requestGuidBytes in $approvalRequestGuids)
{
    # Bind to the approval request.
    $requestGuid = [Guid]$requestGuidBytes
    $requestPath = "Adaxes://<Guid=$requestGuid>"
    $request = $service.OpenObject($requestPath, $null, $null, 0)

    # Output information about the approval request.
    Write-Host "Target object:" $request.TargetObject.Name
    Write-Host "Operation:" $request.DescriptionOfOperationToApprove
    Write-Host "Reason for denial:" $request.DenialOrCancelingReason
    Write-Host
}
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.ApprovalRequests;
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 the target user.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmUser user = (IAdmUser)service.OpenObject(userPath, null, null, 0);

        // Get all approval requests that were denied by the user.
        object[] approvalRequestGuids = (object[])user.GetApprovals(
            ADM_APPROVALSTATE_ENUM.ADM_APPROVALSTATE_DENIED);

        foreach (Byte[] requestGuidBytes in approvalRequestGuids)
        {
            // Bind to the approval request.
            string requestGuid = new Guid(requestGuidBytes).ToString("B");
            string requestPath = $"Adaxes://<GUID={requestGuid}>";
            IAdmApprovalRequest request = (IAdmApprovalRequest)service.OpenObject(
                requestPath, null, null, 0);

            // Output information about the approval request
            Console.WriteLine("Target object: {0}", request.TargetObject.Name);
            Console.WriteLine("Operation: {0}", request.DescriptionOfOperationToApprove);
            Console.WriteLine("Reason for denial: {0}", request.DenialOrCancelingReason);
            Console.WriteLine();
        }
    }
}

CreateHomeDirectory()

Creates a home folder for the user and updates the HomeDirectory property of the user account with the specified path.

void CreateHomeDirectory(string directoryPath,
                         string driveLetter,
                         ADM_USERACCESSPERMISSION_ENUM accessPermissions,
                         bool inheritPermissionsFromParent,
                         bool setUserAsOwner)`

Parameters

  • directoryPath – the UNC path to the user home directory.
  • driveLetter – the drive letter to map the user's home directory to. The drive letter must be a single uppercase letter, followed by a colon (:). This parameter can be set to null, provided that a local path is specified in the directoryPath parameter.
  • accessPermissions – the access permissions that should to be applied to the user home directory.
  • inheritPermissionsFromParent – specifies whether the user's home directory inherits permission entries from its parent directory.
  • setUserAsOwner – specifies whether the user is the owner of the home directory.

Examples

The following code sample creates a home directory for a user.

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

# Home folder path.
$homeDirectoryPath = "\\Server\share\UserHomeDirectories\jsmith"
# Home drive letter.
$driveLetter = "Z:"
# Folder permissions for the user.
$accessPermissions = "ADM_USERACCESSPERMISSION_FULL"
# Inherit permissions from the parent folder.
$inheritPermissionsFromParent = $true
# Set the user as the owner of the folder.
$setUserAsOwner = $true

# Create a home directory.
$user.CreateHomeDirectory($homeDirectoryPath, $driveLetter, $accessPermissions,
    $inheritPermissionsFromParent, $setUserAsOwner)
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 the user.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmUser user = (IAdmUser)service.OpenObject(userPath, null, null, 0);

        // Home folder path.
        string homeDirectoryPath = @"\\Server\share\UserHomeDirectories\jsmith";
        // Drive letter.
        string driveLetter = "Z:";
        // Folder permissions for the user.
        ADM_USERACCESSPERMISSION_ENUM accessPermissions =
            ADM_USERACCESSPERMISSION_ENUM.ADM_USERACCESSPERMISSION_FULL;
        // Inherit permissions from the parent folder.
        bool inheritPermissionsFromParent = true;
        // Set the user as the owner of the folder.
        bool setUserAsOwner = true;

        // Create a home directory.
        user.CreateHomeDirectory(homeDirectoryPath, driveLetter, accessPermissions,
            inheritPermissionsFromParent, setUserAsOwner);
    }
}

MoveHomeDirectory()

Relocates the user's home directory together with all of the contents of that directory, and updates the HomeDirectory property of the user account with the new path. The method also allows to re-share the user's home directory at the new location.

void MoveHomeDirectory(string destinationFolderPath, string nameOfShare)

Parameters

  • destinationFolderPath – the UNC path to the new location of the user's home directory.
  • nameOfShare – the name of the user's home directory share. The user's home folder will be shared under this name after being moved to the new location, but only if the current user's home directory is already shared. You can set this parameter to null – then the user's home directory will not be shared at the new location.

Examples

The following code sample moves a user's home folder to another location.

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

# New path to the home folder.
$destinationFolderPath = "\\Server\share\UsersHomeDirectories\jsmith"

# New name for the home folder share.
$nameOfShare = "jsmith"

# Move the home folder.
$user.MoveHomeDirectory($destinationFolderPath, $nameOfShare)
C#
using System;
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 the user.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmUser user = (IAdmUser)service.OpenObject(userPath, null, null, 0);

        // New path to the home folder.
        string destinationFolderPath = @"\\Server\share\UsersHomeDirectories\jsmith";

        // New name for the home folder share.
        string nameOfShare = "jsmith";

        // Move the home folder.
        user.MoveHomeDirectory(destinationFolderPath, nameOfShare);
    }
}

DeleteHomeDirectory()

Deletes the user's home directory and clears the HomeDirectory property of the user account.

void DeleteHomeDirectory(ADM_USERHOMEDIRECTORYDELETECONDITION_ENUM homeDirectoryDeleteCondition)

Parameters

  • homeDirectoryDeleteCondition – specifies whether the user home directory should be deleted when non-empty. When set to ADM_USERHOMEDIRECTORYDELETECONDITION_IFEMPTY, the method will try to delete the home directory only if it is empty, and when set to ADM_USERHOMEDIRECTORYDELETECONDITION_NONE, the method will try to delete the home directory in any case, even if it is not empty.

Examples

The following code sample deletes a user's home 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 the user.
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Delete the home directory.
$user.DeleteHomeDirectory("ADM_USERHOMEDIRECTORYDELETECONDITION_NONE")
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 the user.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmUser user = (IAdmUser)service.OpenObject(userPath, null, null, 0);

        // Delete the home directory.
        user.DeleteHomeDirectory(
            ADM_USERHOMEDIRECTORYDELETECONDITION_ENUM.ADM_USERHOMEDIRECTORYDELETECONDITION_NONE);
    }
}

ShareHomeDirectory()

Shares the user's home directory.

void ShareHomeDirectory(string nameOfShare,
                        string shareComment,
                        int concurrentConnectionsLimit,
                        ADM_USERACCESSPERMISSION_ENUM permissionsForEveryone,
                        ADM_USERACCESSPERMISSION_ENUM permissionsForUser)

Parameters

  • nameOfShare – the name of the user's home directory share.
  • shareComment – an optional comment to the user's home directory share. The comment can contain additional and user-specific information for users browsing the network (e.g. Jane Doe's (Accounting Dept.) Home Folder).
  • concurrentConnectionsLimit – the maximum number of concurrent connections that the shared directory can accommodate. When set to -1, the number of concurrent connections is unlimited.
  • permissionsForEveryone – access permissions for Everyone that will be applied to the user's home directory.
  • permissionsForUser – access permissions for this user account that will be applied to the home directory.

Examples

The following code sample shares a user's home 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 the user.
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Share name.
$shareName = "jsmith"
# Share comment.
$shareComment = "John Smith's (Accounting Dept.) Home Folder."
# Maximum number of concurrent connections allowed for the shared folder
$concurrentConnectionsLimit = 10
# Permissions for the user.
$permissionsForUser = "ADM_USERACCESSPERMISSION_FULL"
# Permissions for Everyone.
$permissionsForEveryone = "ADM_USERACCESSPERMISSION_READ"

# Share the home directory.
$user.ShareHomeDirectory($shareName, $shareComment,
    $concurrentConnectionsLimit, $permissionsForEveryone, $permissionsForUser)
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 the user.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmUser user = (IAdmUser)service.OpenObject(userPath, null, null, 0);

        // Share name.
        string shareName = "jsmith";
        // Share comment.
        string shareComment = "John Smith's (Accounting Dept.) Home Folder.";
        // Maximum number of concurrent connections allowed for the shared folder
        int concurrentConnectionsLimit = 10;
        // Permissions for the user.
        ADM_USERACCESSPERMISSION_ENUM permissionsForUser =
            ADM_USERACCESSPERMISSION_ENUM.ADM_USERACCESSPERMISSION_FULL;
        // Permissions for Everyone.
        ADM_USERACCESSPERMISSION_ENUM permissionsForEveryone =
            ADM_USERACCESSPERMISSION_ENUM.ADM_USERACCESSPERMISSION_READ;

        // Share the home directory.
        user.ShareHomeDirectory(shareName, shareComment, concurrentConnectionsLimit,
            permissionsForEveryone, permissionsForUser);
    }
}

DeleteShare()

Stops sharing the user's home directory.

void DeleteShare()

GetActionLog()

Returns an object representing the action log of the user. The log contains a list of records that describe the actions that were performed by the user. For more details, see Accessing log records.

IAdmActionLog GetActionLog()

Examples

The following code sample outputs all operations performed by a user.

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

# Get action log.
$actionLog = $user.GetActionLog()
$log = $actionLog.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:" $record.TargetObjectName
        Write-Host "Target object type:" $record.TargetObjectType
        Write-Host "Operation:" $record.Description
        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.Logging;
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 the target user.
        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com";
        IAdmUser user = (IAdmUser)service.OpenObject(userPath, null, null, 0);

        // Get action log.
        IAdmActionLog actionLog = user.GetActionLog();
        IAdmLog log = actionLog.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)
            {
                IAdmLogRecord record2 = (IAdmLogRecord)record;
                Console.WriteLine("Target object: {0}", record2.TargetObjectName);
                Console.WriteLine("Target object type: {0}", record2.TargetObjectType);
                Console.WriteLine("Operation: {0}", record.Description);
                Console.WriteLine("Start time: {0}", record.StartTime);
                Console.WriteLine("Completion time: {0}", record.CompletionTime);
                Console.WriteLine();
            }
        }
    }
}

Requirements

Minimum required version: 2009.1

See also

© Softerra 2022. All rights reserved.
Send feedback