IAdmService

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

  • Bind to directory objects and Adaxes-specific objects.
  • Retrieve various information from an Adaxes service, such 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, service status, version, etc.
  • Check whether the service is running and responding to client requests.
  • Retrieve the list of domains managed by the service.
  • Get the list of client sessions.
  • Access the notice board and retrieve messages and notifications published by the service.

Inheritance: IUnknown

Methods

Properties

  • Property

  • Description

  • Backend

  • Gets the information about the AD LDS instance 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 aggregated directory schema used by the Adaxes service.

  • SiteName

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

  • Status

  • Gets the status of the Adaxes service.

  • Version

  • Gets the Adaxes service version.

Details

EnsureAvailable()

Checks whether the Adaxes service is reachable and responding 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 use the returned interface to access each managed domain.

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 – a host name. The method will return only the client sessions initiated from the specified host. If set to null, the method returns all client sessions.
  • username – the username of the account whose credentials to use to get the data. When set to null, the credentials of the currently logged on user are used.
  • password – 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 Active Directory objects, Entra ID objects, and Adaxes configuration objects (e.g. business rules, security roles, 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 – the 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 operations on the bound object and do not affect the security context of the calling thread.

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.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");

        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")

# Get all Adaxes services installed in the target domain.
$ns = New-Object("Softerra.Adaxes.Adsi.AdmNamespace")
$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)
    {
        // Get all Adaxes services installed in the target domain.
        AdmNamespace ns = new AdmNamespace();
        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 where the host running the Adaxes service belongs.

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

Status

Gets the status of the Adaxes service.

Version

Gets the Adaxes service version.

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

Requirements

Minimum required version: 2009.1

See also

© Softerra 2022. All rights reserved.
Send feedback