ADsOpenObject 函式 (adshlp.h)

發行項
02/26/2024

ADsOpenObject 函式會使用明確的使用者名稱和密碼認證系結至 ADSI 物件。ADsOpenObject 是 IADsOpenDSObject 的包裝函式，相當於 IADsOpenDSObject：：OpenDsObject 方法。

語法

HRESULT ADsOpenObject(
  [in]  LPCWSTR lpszPathName,
  [in]  LPCWSTR lpszUserName,
  [in]  LPCWSTR lpszPassword,
  [in]  DWORD   dwReserved,
  [in]  REFIID  riid,
  [out] void    **ppObject
);

參數

[in] lpszPathName

類型： LPCWSTR

Null 終止的 Unicode 字串，指定 ADSI 物件的 ADsPath。如需此參數係結字串的詳細資訊和程式代碼範例，請參閱 LDAP ADsPath 和 WinNT ADsPath。

[in] lpszUserName

類型： LPCWSTR

以 Null 結尾的 Unicode 字串，指定要提供給要用於認證的目錄服務的用戶名稱。此字串的格式應一律為 “<domain\><user name>”，以避免模棱兩可。例如，如果 DomainA 和 DomainB 具有信任關係，而且兩個網域都有名稱為 “user1” 的使用者，則無法預測哪些網域 ADsOpenObject 將用來驗證 “user1”。

[in] lpszPassword

類型： LPCWSTR

以 Null 終止的 Unicode 字串，指定要提供給要用於認證的目錄服務的密碼。

[in] dwReserved

類型： DWORD

用來定義系結選項的提供者特定驗證旗標。如需詳細資訊，請參閱 ADS_AUTHENTICATION_ENUM。

[in] riid

類型： REFIID

這個物件上所要求介面的介面標識碼。

[out] ppObject

類型： VOID**

指向所要求介面之指標的指標。

傳回值

類型： HRESULT

這個方法支持標準 HRESULT 傳回值，包括下列專案。

如需詳細資訊，請參閱 ADSI 錯誤碼。

備註

此函式不應該只用來驗證用戶認證。

C/C++ 用戶端會呼叫 ADsOpenObject 協助程式函式，以使用提供作為適當目錄服務認證的使用者名稱和密碼，系結至 ADSI 物件。如果 lpszUsername 和 lpszPassword 為 NULL 且已設定 ADS_SECURE_AUTHENTICATION，ADSI 會使用呼叫線程的安全性內容系結至物件，這是應用程式執行所在的使用者帳戶的安全性內容，或是呼叫線程仿真的用戶端用戶帳戶。

傳遞至 ADsOpenObject 函式的認證只會與系結至的特定物件搭配使用，且不會影響呼叫線程的安全性內容。這表示在下列範例中， 對 ADsOpenObject 的呼叫會使用與 ADsGetObject 呼叫不同的認證。

HRESULT hr;
IADs *padsRoot1;
IADs *padsRoot2;

hr = ADsOpenObject(L"LDAP://rootDSE",
    pwszUsername,
    pwszPassword,
    ADS_SECURE_AUTHENTICATION,
    IID_IADs,
    (LPVOID*)&padsRoot1);

hr = ADsGetObject(L"LDAP://rootDSE",
    IID_IADs,
    (LPVOID*)&padsRoot2);

若要使用 WinNT：提供者，您可以傳入 lpszUsername 作為下列其中一個字符串：

用戶帳戶的名稱，也就是「jeffsmith」。。
Windows 樣式用戶名稱，也就是 “Fabrikam\jeffsmith”。

使用 Active Directory 的 LDAP 提供者，您可以傳入 lpszUsername 作為下列其中一個字符串：

用戶帳戶的名稱，例如「jeffsmith」。。若要單獨使用使用者名稱，您必須只在 dwReserved 參數中設定ADS_SECURE_AUTHENTICATION旗標。
舊版 Windows 的用戶路徑，例如 “Fabrikam\jeffsmith”。
辨別名稱，例如 “CN=Jeff Smith，OU=Sales，DC=Fabrikam，DC=com”。若要使用 DN，dwReserved 參數必須是零，或者必須包含 ADS_USE_SSL 旗標。
用戶主體名稱 (UPN) ，例如 “jeffsmith@Fabrikam.com”。若要使用UPN，請為目標用戶物件的 userPrincipalName 屬性指派適當的UPN值。

如果使用 LDAP 提供者成功完成特定目錄要求需要 Kerberos 驗證， lpszPathName 系結字串必須使用無伺服器 ADsPath，例如 “LDAP：//CN=Jeff Smith，CN=admin，DC=Fabrikam，DC=com”，或者必須使用具有完整 DNS 伺服器名稱的 ADsPath，例如 “LDAP://central3.corp.Fabrikam.com/CN=Jeff Smith，CN=admin，DC=Fabrikam，DC=com”。例如，使用一般 NETBIOS 名稱或簡短 DNS 名稱系結至伺服器，例如使用簡短名稱「central3」而非「central3.corp.Fabrikam.com」，可能會或可能不會產生 Kerberos 驗證。

下列程式代碼範例示範如何使用要求的使用者認證系結至目錄服務物件。

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

// Insert code to securely retrieve the user name and password.

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

規格需求

需求	值
最低支援的用戶端	Windows Vista
最低支援的伺服器	Windows Server 2008
目標平台	Windows
標頭	adshlp.h
程式庫	Activeds.lib
Dll	Activeds.dll