Active Directory Service Interface

Active Directory Service Interface (ADSI) 是一組植基於 COM 技術上的應用程式開發介面，程式開發人員可以利用這些介面來連接並存取 Active Directory，並執行查詢，更新或刪除等管理功能，ADSI同時可支援以LDAP（輕量級目錄存取協定）為主的目錄服務（例如Novell Directory Service），以及以 Windows NT 網域為主所組成的 WinNT 網域目錄。

介面結構

ADSI 由 COM 以及原生函式庫所組成，並封裝在 activeds.dll 檔案中，部份則被封裝在 advaip32.dll 中，以 COM 原生介面方式呈現，以提供給 C/C++ 程式語言透過 COM 介面來取用，不過由於所有的原生介面均支援 COM Automation，因此 Visual Basic 或是 .NET Framework 的語言也可以利用 COM Interop 能力存取 ADSI 中的介面。

原生介面 (Native interfaces)

activeds.dll 中封裝了幾個 ADSI 中最核心的介面：

IADs：作為所有 Active Directory 物件最頂層的介面，擁有最基礎的功能，
IADsContainer：作為所有可收納 Active Directory 物件的收納器 (Container) 最頂層的介面，具有收納器的基礎功能。
IADsOpenDSObject：連接 Active Directory 之用（它只有 OpenDSObject() 一個方法），同時它會快取住用來連接的安全資訊內容。
IADsNamespace：由目錄服務提供者 (directory service provider) 提供，用來識別目錄結構的命名空間之用。

activeds.dll 亦提供了幾個依物件不同而實作的介面，像是：

IADsComputer：提供目錄服務中的電腦 (computer) 物件。
IADsDomain：提供目錄服務中的網域 (domain) 物件。
IADsUser：提供目錄服務中的使用者 (user) 物件。
IADsGroup：提供目錄服務中的使用者群組 (group) 物件。
IADsOU：提供目錄服務中的組織單元 (organization unit) 物件。
IADsCollection：提供目錄服務物件集合。

在使用 ADSI 之時，有時會需要一些工具型功能，像是 DOMAIN\user 和 User Principal Name 間的轉換，或是取得系統資訊等，ADSI 也提供了這類的介面：

IADsNameTranslate：在目錄服務中在不同的名稱間轉換。
IADsWinNTSystemInfo：在目錄服務中取得 Windows NT Directory Service 系統資訊。
IADsADSystemInfo：在目錄服務中取得 LDAP Directory Service 系統資訊。
IADsPathname：剖析 X.500 名稱與路徑。

這些介面多是使用 C/C++ 程式語言來存取，若是使用 VB 或是 Scripting Language 時，則可以使用另外的方法來存取。

' Get user object from Active Directory.
Dim mach As IADsContainer
Dim usr as IADsUser

On Error GoTo Cleanup
Set mach = GetObject("WinNT://MyMachine,Computer")
Set usr = mach.Create("user","jeffsmith")
usr.SetInfo

Cleanup:
    If(Err.Number<>0) Then
        MsgBox("An error has occurred. " & Err.Number)
    End If
    Set mach = Nothing
    Set usr = Nothing

// binding Active Directory using C++ and native interface.
IADs *pObject;
HRESULT hr;

// Initialize COM.
CoInitialize(NULL);

hr = ADsGetObject(L"LDAP://CN=jeffsmith,DC=fabrikam,DC=com", 
        IID_IADs,
        (void**) &pObject);
if(SUCCEEDED(hr))
{
    // Use the object.

    // Release the object.
    pObject->Release()
}

// Uninitialize COM.
CoUninitialize();

函式

ADSI 除了介面以外，也將部份功能使用函式方式顯露，以簡化呼叫原生介面需要處理的工作，較重要且經常被使用的有：

ADsOpenDSObject()，封裝取得 IADs 或 IADsContainer 等物件的工作。
ADsGetObject()，封裝利用已開啟的 Active Directory Session 取得物件的工作。
ADsGetLastError()，取得在 ADSI 作業中，最後一個引發的錯誤。
AllocADsMem(), FreeADsMem(), AllocADsStr(), FreeADsStr()，配置與釋放 ADSI 使用的資源。
ADsBuildEnumerator(), ADsEnumerateNext(), ADsFreeEnumerator()：處理 ADSI 物件的列舉工作。

下列的例子，是使用 ADsOpenDSObject() 取得 IADs 物件的範例程式碼：

IADs *pObject;
LPWSTR szUsername = NULL;
LPWSTR szPassword = NULL
HRESULT hr;

// Insert code to securely retrieve the username and password.

hr = ADsOpenObject(L"LDAP://CN=Jeff,DC=Fabrikam,DC=com",
                   "jeffsmith",
                   "etercespot",
                   ADS_SECURE_AUTHENTICATION, 
                   IID_IADs,
                   (void**) &pObject);

.NET Framework 原生介面

在 .NET Framework 中，另外提供了一個 .NET 專用的 ADSI 介面程式庫 System.DirectoryService.dll，程式開發人員可以加入此程式庫的參考來取得 ADSI 的功能，在這個原生類別庫中，封裝了兩個類別，作為存取 Active Directory 的入口之用。

DirectoryEntry

此類別封裝了 IADs 以及 IADsContainer 等原生介面，用來存取 Active Directory 的物件資料，以及 Schema 封裝的資訊等等。

DirectorySearcher

此類別封裝了 IDirectorySearch 介面，作為搜尋 Active Directory 的主要工具，並使用 SearchResult 物件封裝搜尋結果，讓 .NET 開發人員可以簡化處理搜尋結果的工作。

參考資料