IADsOpenDSObject：：OpenDSObject 方法 (iads.h)

發行項
02/28/2024

IADsOpenDSObject：：OpenDSObject 方法會使用指定的認證系結至 ADSI 物件，並擷取指定物件的 IDispatch 指標。

重要不建議您將這個方法與 WinNT 提供者搭配使用。如需詳細資訊，請參閱知識庫文章218497 Active Directory 服務介面 WinNT 提供者的使用者驗證問題。

語法

HRESULT OpenDSObject(
  [in]  BSTR      lpszDNName,
  [in]  BSTR      lpszUserName,
  [in]  BSTR      lpszPassword,
  [in]  long      lnReserved,
  [out] IDispatch **ppOleDsObj
);

參數

[in] lpszDNName

Null 終止的 Unicode 字串，指定 ADSI 物件的 ADsPath。如需此參數之系結字串的詳細資訊和範例，請參閱 LDAP ADsPath。搭配包含特定伺服器名稱的 ADsPath 使用 LDAP 提供者時， lnReserved 參數應該包含 ADS_SERVER_BIND 旗標。

[in] lpszUserName

Null 終止的 Unicode 字串，指定要用來保護命名空間伺服器之許可權的用戶名稱。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in] lpszPassword

Null 終止的 Unicode 字串，指定要用來從命名空間伺服器取得許可權的密碼。

[in] lnReserved

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

[out] ppOleDsObj

指向所要求物件上 IDispatch 介面指標的指標。

傳回值

這個方法支持標準傳回值，包括使用這些認證成功擷取 IDispatch 介面時S_OK。

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

備註

這個方法不應該只用來驗證用戶認證。

設定 lnReserved 時， OpenDSObject 的行為取決於它所連線的提供者。高安全性命名空間可能會忽略這些旗標，而且一律需要驗證。

IADsOpenDSObject：：OpenDSObject 方法會在快取中維護已驗證和加密的用戶認證。快取認證可用於後續作業，以系結至任何其他目錄物件。 ADSI 用戶端應用程式不應該快取使用者所提供的認證。相反地，他們應該依賴 ADSI 基礎結構來執行快取。若要使用快取的認證， lpszPassword 和 lpszUserName 必須在任何後續 OpenDSObject 呼叫中保持不變。下列程式代碼範例顯示這項作業。

Dim dso As IADsOpenDSObject
Dim obj1, obj2 As IADs
Dim szUsername As String
Dim szPassword As String

Set dso = GetObject("LDAP:")

' Insert code securely.

' Supply full credentials to initiate a server connection.
Set obj1 = dso.OpenDSObject( _
    "LDAP://server1/CN=Dept1,DC=Fabrikam,DC=com", _
    szUsername, _
    szPassword, _
    ADS_SECURE_AUTHENTICATION + ADS_SERVER_BIND)

' Perform an operation with the bound object, obj1
MsgBox obj1.Class

' Bind to another object with the cached user credential.
Set obj2 = dso.OpenDSObject( _
    "LDAP://server1/CN=Dept2,DC=Fabrikam,DC=com", _
    szUsername, _
    szPassword, _
    ADS_SECURE_AUTHENTICATION + ADS_SERVER_BIND)

MsgBox obj2.Class

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

Dim dso As IADsOpenDSObject
Dim obj1, obj2 As IADs
Dim szUsername As String
Dim szPassword As String

Set dso = GetObject("LDAP:")

' Insert code securely.

' Bind using full credentials.
Set obj1 = dso.OpenDSObject( _
    "LDAP://server1/CN=Dept1,DC=Fabrikam,DC=com", _
    szUsername, _
    szPassword, _
    ADS_SECURE_AUTHENTICATION + ADS_SERVER_BIND)

' Bind to another object with the default credentials.
Set obj2 = GetObject("LDAP://server1/CN=Dept2,DC=Fabrikam,DC=com")

使用無伺服器系結時，不會明確說明伺服器名稱「server1」。會改用預設伺服器。只有LDAP提供者支援無伺服器系結。若要使用此功能，用戶端計算機必須位於 Active Directory 網域上。若要嘗試從計算機進行無伺服器系結，您必須系結為網域使用者。

若要讓認證快取正常運作，請務必保留未處理的對象參考，以維護快取句柄。在上述範例中，在釋放「obj1」之後嘗試開啟「obj2」將會導致驗證失敗。

當 lpszUserName 和 lpszPassword 設定為 NULL 時，IADsOpenDSObject 方法會使用預設認證。

如果使用 LDAP 提供者成功完成特定目錄要求需要 Kerberos 驗證， 則 lpszDNName 系結字串必須使用無伺服器 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 驗證。

ADsOpenObject 協助程式函式提供與 IADsOpenDSObject：：OpenDSObject 方法相同的功能。

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

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

範例

下列程式代碼範例示範如何使用 IADsOpenDSObject ，透過 LDAP 提供者以安全驗證開啟 “Fabrikam” 上的 “Administrator” 用戶物件。

Dim dso As IADsOpenDSObject
Dim domain As IADsDomain
Dim szUsername As String
Dim szPassword As String

On Error GoTo Cleanup

' Insert code to securely retrieve the user name and password.
 
Set dso = GetObject("LDAP:")
Set domain = dso.OpenDSObject("LDAP://Fabrikam", szUsername, _
                              szPassword, _
                              ADS_SECURE_AUTHENTICATION)

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

下列程式代碼範例使用 IADsOpenDSObject 透過 LDAP 提供者開啟 Active Directory 物件。

IADsOpenDSObject *pDSO = NULL;
HRESULT hr = S_OK;
 
hr = ADsGetObject(L"LDAP:", IID_IADsOpenDSObject, (void**) &pDSO);
if (SUCCEEDED(hr))
{
    IDispatch *pDisp;
    hr = pDSO->OpenDSObject(CComBSTR("LDAP://DC=Fabrikam, DC=com"), 
                       CComBSTR("jeffsmith@Fabrikam.com"),
                       CComBSTR("passwordhere"),
                       ADS_SECURE_AUTHENTICATION, 
                       &pDisp);
    pDSO->Release();
    if (SUCCEEDED(hr))
    {
        IADs *pADs;
        hr = pDisp->QueryInterface(IID_IADs, (void**) &pADs);
        pDisp->Release();
        if (SUCCEEDED(hr))
        {
        // Perform an object manipulation here.
            pADs->Release();
        }
    }
}