Directory Services

IADsContainer::GetObject

The IADsContainer::GetObject method retrieves an interface for a directory object in the container.

HRESULT GetObject( 
  BSTR bstrClass,
  BSTR bstrRelativeName,
  IDispatch** ppNamedObject
);

Parameters

bstrClass
[in] A BSTR that specifies the name of the object class as of the object to retrieve. If this parameter is NULL, the provider returns the first item found in the container.
bstrRelativeName
[in] A BSTR that specifies the relative distinguished name of the object to retrieve.
ppNamedObject
[out] Pointer to a pointer to the IDispatch interface on the specified object.

Return Values

This method supports standard return values, including S_OK for a successful operation. For more information about error codes, see ADSI Error Codes.

Remarks

For the LDAP provider, the bstrRelativeName parameter must contain the name prefix, such as "CN=Jeff Smith". The bstrRelativeName parameter can also contain more than one level of name, such as "CN=Jeff Smith,OU=Sales".

In C++, when GetObject has succeeded, the caller must query the IDispatch interface for the desired interface using the QueryInterface method.

Example Code [Visual Basic]

The following code example retrieves a user object from a container object.

Dim cont As IADsContainer
Dim usr As IADsUser
Set cont = GetObject("LDAP://OU=Sales,DC=Fabrikam,DC=com")
Set usr = cont.GetObject("user", "jeffsmith")

This is equivalent to:

Dim usr As IADsUser
Set usr=GetObject("LDAP://CN=jeffsmith, OU=Sales,DC=Fabrikam,DC=com")

Example Code [C++]

The following code example retrieves a user object from a container object.

HRESULT hr = S_OK;
CoInitialize(NULL);
 
IADsContainer *pCont = NULL;
 
hr = ADsGetObject(L"LDAP://DC=windows2000,DC=mytest,DC=fabrikam,DC=com",
			IID_IADsContainer, 
			(void**) &pCont );

if(FAILED(hr)){goto Cleanup;}
 
///////////////////////////////////////////////////////////////////////
// Retrieve the child from the container.
// Be aware that in the LDAP provider you can navigate multiple levels.
///////////////////////////////////////////////////////////////////////
IDispatch *pDisp = NULL;
IADs *pADs = NULL;
hr = pCont->GetObject(CComBSTR("user"), CComBSTR("CN=Jeff Smith,OU=DSys"), &pDisp );
pCont->Release();
if(FAILED(hr))
{
	goto Cleanup;
}
 
hr = pDisp->QueryInterface(IID_IADs, (void**)&pADs);
pDisp->Release(); 
if(FAILED(hr))
{
	goto Cleanup;
}
 
// Perform an operation with pADs.
pADs->Release();
 
Cleanup:
if(pCont)
	pCont->Release();

if(pDisp)
	pDisp->Release();

if(pADs)
	pADs->Release();

CoUninitialize();

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 Iads.h.

See Also

ADSI Error Codes, ADsGetObject, IADs, IADs::get_Class, IADs::get_Name, IADsContainer, IDispatch