IAdmUser

The IAdmUser interface extends the IADsUser interface with certain Adaxes-specific functionality. In particular, the IAdmUser interface allows 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

Methods

  • Method

  • Description

  • GetRequestsForApproval()

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

  • GetApprovals()

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

  • CreateHomeDirectory()

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

  • MoveHomeDirectory()

  • Relocates the user's home directory to a new location.

  • DeleteHomeDirectory()

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

  • ShareHomeDirectory()

  • Shares the user home directory.

  • DeleteShare()

  • Removes sharing from the user's home directory.

  • GetActionLog()

  • Returns an object representing the Action Log of the user.

Details

GetRequestsForApproval()

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

object GetRequestsForApproval(ADM_APPROVALSTATE_ENUM requestState)

Parameters

The requestState parameter specifies whether the method returns approved, denied, cancelled, or still 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 itself is an array of arrays of bytes.

Using the GUIDs, you can bind to approval request objects. 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 = string.Format("Adaxes://<GUID={0}>", requestGuid);
            IAdmApprovalRequest request = (IAdmApprovalRequest) service.OpenObject(
                requestPath, null, null, 0);

            // Output information about the request
            Console.WriteLine("Operation: " + request.DescriptionOfOperationToApprove);
            Console.WriteLine("Requested on " + request.CreationDate.ToShortDateString());
            Console.WriteLine(string.Empty);
        }
    }
}

GetApprovals()

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

object GetApprovals(ADM_APPROVALSTATE_ENUM requestState)

Parameters

The requestState parameter specifies whether the method returns approved, denied, cancelled, or still 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 itself is an array of arrays of bytes.

Using the GUIDs, you can bind to approval request objects. 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 = string.Format("Adaxes://<GUID={0}>", 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 path specified.

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

Parameters

  • directoryPath - Specifies the UNC path to the user home directory.
  • driveLetter - Specifies the drive letter to map the user's home directory to. The drive letter must be specified following the DriveLetter: format, where DriveLetter is the letter of the drive to map. The DriveLetter must be a single uppercase letter, and the colon character (:) is required. This parameter can be set to null, provided that a local path is specified in the directoryPath parameter.
  • accessPermissions - Specifies the user access permissions that need 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 to a new location 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 - Specifies the UNC path to the new location of the user's home directory.
  • nameOfShare - Specifies 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, provided, however, that the current user's home directory is 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

The homeDirectoryDeleteCondition parameter 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 home directory.

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

Parameters

  • nameOfShare - Specifies the name of the user's home directory share.
  • shareComment - Specifies 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 - Specifies the maximum number of concurrent connections that the shared directory can accommodate. When set to -1, the number of concurrent connections is unlimited.
  • permissionsForEveryone - Specifies access permissions for Everyone that will be applied to the user's home directory.
  • permissionsForUser - Specifies 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()

Removes sharing from 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