ADsOpenObject

The ADsOpenObject function binds to an ADSI object using explicit username and password credentials.

HRESULT ADsOpenObject(
  LPWSTR lpszPathName, 
  LPWSTR lpszUserName, 
  LPWSTR lpszPassword, 
  DWORD dwReserved, 
  REFIID riid, 
  VOID FAR * FAR *ppObject 
);

Parameters

lpszPathName

[in] The path name to use to bind to the object in the underlying directory using the lpszUserName and lpszPassword credentials.

lpszUserName

[in] The user name to supply to the directory service to use for credentials.

lpszPassword

[in] The password to supply to the directory service to use for credentials.

dwReserved

[in] Provider-specific authentication flags used to define the binding options. For more information, see ADS_AUTHENTICATION_ENUM.

riid

[in] Interface identifier for the requested interface on this object.

ppObject

[out] Indirect pointer to the requested interface.

Return Values

This method supports the standard HRESULT return values, including:

S_OK

Binding to the specified object has been successful.

For other return values, see ADSI Error Codes.

Remarks

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 is impersonating.

The ADsOpenObject function ignores the dwReserved flag when attempting to bind to an NDS or NWCOMPAT object.

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, jsmith,
• the Windows NT® 4.0 style user name, that is, Fabrikam\jsmith.

With the LDAP provider for Active Directory, you may pass in lpszUserName as one of the following strings:

• The name of a user account, such as jsmith. To use a user name by itself, you must set only the ADS_SECURE_AUTHENTICATION flag in the lnReserved parameter.
• The user path from a previous version of Windows NT, such as Fabrikam\jsmith.
• Distinguished Name, such as CN=Jeff Smith, OU=Sales, DC=Fabrikam, DC=Com. To use a DN, the lnReserved parameter must be zero or it must include the ADS_USE_SSL flag
• User Principal Name (UPN), such as jsmith@Fabrikam.com. To use a UPN, you must assign the appropriate UPN value for the userPrincipalName attribute of the targeted user object

The following code snippet illustrates how to bind to a directory service object with the user credential of jsmith.

IADs    *pObject;
HRESULT hr;
hr = ADsOpenObject(L"LDAP://CN=Bob,DC=Fabrikam,DC=com",
                   "jsmith",
                   "etercespot",
                   ADS_SECURE_AUTHENTICATION, 
                   IID_IADs,
                   (void**) &pObject);
 

This function is equivalent to the IADsOpenDSObject::OpenDsObject method.

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Adshlp.h.
  Library: Included as a resource in ActiveDs.dll.

See Also

ADSI Error Codes, ADSI Functions, IADsOpenDSObject, IADsOpenDSObject::OpenDsObject