ADsOpenObject

The ADsOpenObject function binds to an ADSI object using explicit username and password credentials.ADsOpenObject is a wrapper function for IADsOpenDSObject and is equivalent to the IADsOpenDSObject::OpenDsObject method.

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

Parameters

lpszPathName

[in] The null-terminated Unicode string that specifies the ADsPath of the ADSI object. For more information and examples of binding strings for this parameter, see LDAP ADsPath and WinNT ADsPath.

lpszUserName

[in] The null-terminated Unicode string that specifies the user name to supply to the directory service to use for credentials.

lpszPassword

[in] The null-terminated Unicode string that specifies 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] Pointer to a pointer to the requested interface.

Return Values

This method supports the standard HRESULT return values, including the following.

For more information and 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 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);

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

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 jeffsmith. 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\jeffsmith.
• 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 jeffsmith@Fabrikam.com. To use a UPN, you must assign the appropriate UPN value for the userPrincipalName attribute of the targeted user object

If Kerberos authentication is required for the successful completion of a specific directory request using the LDAP provider, the lpszPathName binding string must use either a serverless ADsPath, such as "LDAP://CN=Jeff Smith, CN=admin, DC=Fabrikam, DC=com", or it must use an ADsPath with a fully-qualified DNS server name, such as "LDAP://central3.corp.Fabrikam.com/CN=Jeff Smith, CN=admin, DC=Fabrikam, DC=com". Binding to the server using a flat NETBIOS name or a short DNS name (for example, using the short name "central3" instead of "central3.corp.Fabrikam.com") may or may not yield Kerberos authentication.

The following code example shows how to bind to a directory service object with the requested user credentials.

[C++]
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);

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Adshlp.h.
Library: Use ActiveDS.lib.

See Also

ADSI Error Codes, ADSI Functions, IADsOpenDSObject, IADsOpenDSObject::OpenDsObject, Binding, ADsOpenObject and IADsOpenDSObject::OpenDsObject