IAdmService

The IAdmService interface represents an Adaxes service. You can use this interface to:

  • Bind to directory objects and Adaxes-specific objects.
  • Retrieve such information on an Adaxes service as the ID of the configuration set it belongs to, the backend server it uses, the DNS name of the host where the service is installed, the service status, version, etc.
  • Check whether the service is running and responses to client requests.
  • Retrieve the list of domains managed by the service.
  • Get the list of client sessions.
  • Access the service notice board and retrieve messages and notifications that an Adaxes service publishes.

Inheritance: IUnknown

Methods

Properties

  • Property

  • Description

  • Backend

  • Gets the IAdmServiceBackend interface that provides information on the directory server that is used to store Adaxes configuration data.

  • ConfigurationSetId

  • Gets the globally unique identifier (GUID) of the configuration set the Adaxes service belongs to.

  • DnsHostName

  • Gets the DNS name of the host where the Adaxes service resides.

  • Schema

  • Gets the IAdmServiceSchema interface that represents the aggregated directory schema used by the Adaxes service.

  • SiteName

  • Gets the name of the Active Directory site that the host running the Adaxes service belongs to.

  • Status

  • Gets the status of the Adaxes service.

  • Version

  • Gets a string representing the dotted version of the service.

Details

EnsureAvailable()

Checks whether the Adaxes service is reachable and responses to client requests. If the Adaxes service is unavailable, the method throws an exception.

void EnsureAvailable()

IsServiceAvailableAsync()

Asynchronously checks whether the Adaxes service is available.

bool IsServiceAvailableAsync()

Remarks

If the method can provide any information on the service availability, it returns true when the service is available, and false when it is not. Otherwise, the method throws a COMException with the E_PENDING HRESULT.

EnsureVersionsCompatible()

Determines whether the versions of the Adaxes service and the client are compatible.

void EnsureVersionsCompatible()

Remarks

If the versions are incompatible, the method throws an IncompatibleVersionException exception. You need to catch and process this exception in your code in order to check for the client and service compatibility.

GetManagedDomains()

Returns the IADsCollection interface that represents a list of domains managed by the Adaxes service. You can further use the retrieved interface to access each of the managed domains separately.

IADsCollection GetManagedDomains()

Return value

The IADsCollection interface returned by the method contains a collection of IAdmManagedDomainInfo interfaces, each representing a domain managed by Adaxes.

Examples

The following code sample outputs the status of all domains managed by the Adaxes service installed on the computer where the script is run.

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

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

# Get all domains managed by the service
$managedDomains = $service.GetManagedDomains()

foreach ($domain in $managedDomains)
{
    # Output the domain name
    Write-Host "Domain name: " $domain.Name
    
    # Output the current domain status
    Write-Host "Domain status: " -NoNewline
    Switch ($domain.Status)
    {
        "ADM_MANAGEDDOMAINSTATUS_INACTIVE"
        {
            Write-Host "The domain is not operational because it is initializing or an internal error has occurred."
        }
        "ADM_MANAGEDDOMAINSTATUS_UNREGISTERED"
        {
            Write-host "The domain is not accessible by the Adaxes service as appropriate credentials were not provided."
        }
        "ADM_MANAGEDDOMAINSTATUS_OPERATING"
        {
            Write-Host "The domain is fully operational and accessible by the Adaxes service."
        }
    }
}
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");

        // Get all domains managed by the service
        IADsCollection managedDomains = service.GetManagedDomains();

        foreach (IAdmManagedDomainInfo domain in managedDomains)
        {
            // Output the domain name
            Console.WriteLine("Domain name: {0}", domain.Name);

            // Output the current domain status
            Console.Write("Domain status: ");
            switch (domain.Status)
            {
                case ADM_MANAGEDDOMAINSTATUS_ENUM.ADM_MANAGEDDOMAINSTATUS_INACTIVE:
                    Console.WriteLine("The domain is not operational because it is " +
                                    "initializing or an internal error has occurred.");
                    break;
                case ADM_MANAGEDDOMAINSTATUS_ENUM.ADM_MANAGEDDOMAINSTATUS_UNREGISTERED:
                    Console.WriteLine("The domain is not accessible by the Adaxes service " +
                                    "as appropriate credentials were not provided.");
                    break;
                case ADM_MANAGEDDOMAINSTATUS_ENUM.ADM_MANAGEDDOMAINSTATUS_OPERATING:
                    Console.WriteLine("The domain is fully operational and " +
                                    "accessible by the Adaxes service.");
                    break;
            }
        }
    }
}

GetSessions()

Returns the IAdmServiceSessions interface that represents a collection of client sessions maintained by the Adaxes service.

IAdmServiceSessions GetSessions(string dnsHostname, 
                                string username, 
                                string password)

Parameters

  • dnsHostname - If specified, the method returns only the client sessions initiated from the specified host. If set to null, the method returns all client sessions.
  • username - Specifies the username of the account to be used to get the data. When set to null, the credentials of the currently logged on user are used.
  • password - Specifies the password of the account specified in the username parameter.

GetNoticeBoard()

Returns the IAdmServiceNoticeBoard interface that represents the notice board of the Adaxes service. The notice board can be used to retrieve various messages and notifications published by the Adaxes service instance.

IAdmServiceNoticeBoard GetNoticeBoard()

OpenObject()

Binds to a directory object. 'Directory object' here means both directory objects and Adaxes configuration objects (e.g. business rules, security roles, scheduled tasks, etc.). For more details on how to bind to directory objects, see Binding to ADSI Objects.

object OpenObject(string path, 
                  string username,
                  string password, 
                  int authenticationOptions)

Parameters

  • path - The ADS path of the directory object you want to bind to.
  • username - The username of the account that will be used for authentication. When set to null, the account of the currently logged on user is used.
  • password - The password of the account specified in the username parameter.
  • authenticationOptions - Authentication flags used to determine the binding options. For more information, see ADS_AUTHENTICATION_ENUM.

Remarks

After you've bound to an object, you can use the appropriate ADSI interfaces to perform operations on the object. The interfaces you can use depend on the type of the directory object. All object types support the IADs and IAdmTop interfaces. User objects support the IADsUser interface, group objects support the IADsGroup interface. Container objects, such as organizational units, support the IADsContainer interface that allows you to enumerate and manage their child objects. For more information, see Interfaces supported by directory objects.

The method maintains the authenticated and encrypted user credentials in the cache. Cached credentials can be used in subsequent operations for binding to any other directory objects. The ADSI client applications should not cache the credentials supplied by the user. Instead, they should rely on ADSI infrastructure to perform caching.

The credentials passed to the method are used only with the particular object bound to and do not affect the security context of the calling thread.

With the Adaxes ADSI provider, you can pass in username as one of the following strings:

  • User Principal Name (UPN), such as johnsmith@Domain.com.
  • Pre-Windows 2000 username, such as DOMAIN\johnsmith (only in Active Directory).

Examples

The following code sample binds to a user and outputs their username and description.

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

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

$userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com" # DN
# $userPath = "Adaxes://mydomain.com/<GUID=90495758-7E98-47B6-AA98-5B49129EF1DB>" # GUID
# $userPath = "Adaxes://mydomain.com/<SID=S-1-5-21-573937-2149998-410785>" # SID

# Bind to the user with the credentials of the currently logged on user
$user = $service.OpenObject($userPath, $null, $null, 0)

# Get username and description
Write-Host "Username: " $user.Get("userPrincipalName")
Write-Host "User description: " $user.Get("description")
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 ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        const string userPath = "Adaxes://CN=John Smith,CN=Users,DC=domain,DC=com"; // DN
        // const string userPath = "Adaxes://mydomain.com/<GUID=90495758-7E98-47B6-AA98-5B49129EF1DB>"; // GUID
        // const string userPath = "Adaxes://mydomain.com/<SID=S-1-5-21-573937-2149998-410785>"; // SID

        // Bind to the user with the credentials of the currently logged on user
        IADs user = (IADs) service.OpenObject(userPath, null, null, 0);

        // Get username and description
        Console.WriteLine("Username: {0}", user.Get("userPrincipalName"));
        Console.WriteLine("User description: {0}", user.Get("description"));
    }
}

Backend

Gets the IAdmServiceBackend interface that provides information on the directory server that is used to store Adaxes configuration data. The server consists of an AD LDS instance installed on the same computer.

Examples

The following code sample enumerates host names and port numbers of all Adaxes configuration data servers installed in a domain.

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

# Create an instance of the AdmNamespace class
$ns = New-Object("Softerra.Adaxes.Adsi.AdmNamespace")

# Get all Adaxes services installed in the target domain
$services = $ns.GetServicesForDomain("domain.com", $null, $null)

# Enumerate host name and port number of each configuration data server
foreach ($service in $services)
{
    $serviceBackend = $service.Backend
    
    Write-Host "Adaxes services installed in domain domain.com:"
    Write-Host $serviceBackend.DnsHostName":"$serviceBackend.PortNumber
}
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Create an instance of the AdmNamespace class
        AdmNamespace ns = new AdmNamespace();

        // Get all Adaxes services installed in the target domain
        IAdmServices services = ns.GetServicesForDomain("domain.com", null, null);

        // Enumerate host name and port number of each configuration data server
        foreach (IAdmService service in services)
        {
            IAdmServiceBackend backend = service.Backend;

            Console.WriteLine("Host name and port number: {0}:{1}",
            backend.DnsHostName, backend.PortNumber);
        }
    }
}

ConfigurationSetId

Gets the globally unique identifier (GUID) of the configuration set the Adaxes service belongs to.

  • Type:
  • string
  • Access:
  • Read-only

DnsHostName

Gets the DNS name of the host where the Adaxes service resides.

  • Type:
  • string
  • Access:
  • Read-only

Schema

Gets the IAdmServiceSchema interface that represents the aggregated directory schema used by the Adaxes service.

SiteName

Gets the name of the Active Directory site that the host running the Adaxes service belongs to.

  • Type:
  • string
  • Access:
  • Read-only

Status

Gets the status of the Adaxes service.

Version

Gets a string representing the dotted version of the service.

  • Type:
  • string
  • Access:
  • Read-only

Requirements

Minimum required version: 2009.1

See also

© Softerra 2022. All rights reserved.
Send feedback