ADsGetObject

The ADsGetObject function binds to an object given its path and a specified interface identifier.

HRESULT ADsGetObject(
  LPWSTR lpszPathName,
  REFIID riid,
  VOID** ppObject
);

Parameters

lpszPathName

[in] The null-terminated Unicode string that specifies the path used to bind to the object in the underlying directory service. For more information and code examples for binding strings for this parameter, see LDAP ADsPath and WinNT ADsPath.

riid

[in] Interface identifier for a specified interface on this object.

ppObject

[out] Pointer to a pointer to the requested Interface.

Return Values

This method supports the standard HRESULT return values.

For more information about other return values, see ADSI Error Codes.

Remarks

A C/C++ client calls the ADsGetObject helper function to bind to an ADSI object. It is equivalent to a Visual Basic client calling the GetObject function. They both take an ADsPath as input and returns a pointer to the requested interface. By default the binding uses ADS_SECURE_AUTHENTICATION option with the security context of the calling thread. However, if the authentication fails, the secure bind is downgraded to an anonymous bind, for example, a simple bind without any user credentials. To securely bind to an ADSI object, use the ADsOpenObject function instead of the ADsGetObject function.

The following code example binds to a user object, "WinNT:://MyDomain/Users/JeffSmith" through the WinNT provider.

IADsUser	*pUser;
BSTR		bstrName;
HRESULT	 hr;
hr = ADsGetObject(L"WinNT://MyDomain/Users/JeffSmith",
				IID_IADsUser,
				(void**) &pUser);

It is possible to bind to an ADSI object with a user credential different from that of the currently logged-on user. To perform this operation, use the ADsOpenObject function.

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, ADsOpenObject, Binding