ADsGetObject

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

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

Parameters

lpszPathName

[in] The path name used to bind to the object in the underlying directory service.

riid

[in] Interface identifier for a specified 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 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.

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

IADsUser    *pUser;
BSTR        bstrName;
HRESULT     hr;
hr = ADsGetObject(L"WinNT://MyDomain/Users/John",
                  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. This is accomplished by using the ADsOpenObject function.

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