The ADsOpenObject function binds to an ADSI object using explicit user name and password credentials.ADsOpenObject is a wrapper function for IADsOpenDSObject and is equivalent to the IADsOpenDSObject::OpenDsObject method.
HRESULT ADsOpenObject( LPCWSTR lpszPathName, LPCWSTR lpszUserName, LPCWSTR lpszPassword, DWORD dwReserved, REFIID riid, void **ppObject );
The null-terminated Unicode string that specifies the user name to supply to the directory service to use for credentials. This string should always be in the format "<domain><user name>" to avoid ambiguity. For example, if DomainA and DomainB have a trust relationship and both domains have a user with the name "user1", it is not possible to predict which domain ADsOpenObject will use to validate "user1".
The null-terminated Unicode string that specifies the password to supply to the directory service to use for credentials.
Provider-specific authentication flags used to define the binding options. For more information, see ADS_AUTHENTICATION_ENUM.
Interface identifier for the requested interface on this object.
Pointer to a pointer to the requested interface.
This method supports the standard HRESULT return values, including the following.
For more information, see ADSI Error Codes.
This function should not be used just to validate user credentials. For more information about validating user credentials, see Microsoft Knowledge Base article 180548 HOWTO: Validate User Credentials on Microsoft Operating Systems.
A C/C++ client calls the ADsOpenObject helper function to bind to an ADSI object, using the user name and password supplied as credentials for the appropriate directory service. If lpszUsername and lpszPassword are NULL and ADS_SECURE_AUTHENTICATION is set, ADSI binds to the object using the security context of the calling thread, which is either the security context of the user account under which the application is running or of the client user account that the calling thread impersonates.
The credentials passed to the ADsOpenObject function are used only with the particular object bound to and do not affect the security context of the calling thread. This means that, in the example below, the call to ADsOpenObject will use different credentials than the call to 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);
To work with the WinNT: provider, you can pass in lpszUsername as one of the following strings:
- The name of a user account, that is, "jeffsmith".
- The Windows style user name, that is, "Fabrikam\jeffsmith".
- The name of a user account, such as "jeffsmith". To use a user name by itself, you must set only the ADS_SECURE_AUTHENTICATION flag in the dwReserved parameter.
- The user path from a previous version of Windows, such as "Fabrikam\jeffsmith".
- Distinguished Name, such as "CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=Com". To use a DN, the dwReserved parameter must be zero or it must include the ADS_USE_SSL flag.
- User Principal Name (UPN), such as "jeffsmith@Fabrikam.com". To use a UPN, assign the appropriate UPN value for the userPrincipalName attribute of the target user object.
The following code example shows how to bind to a directory service object with the requested user credentials.
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);
|Minimum supported client||Windows Vista|
|Minimum supported server||Windows Server 2008|