Directory Services

IADsContainer Property Methods

The property methods of the IADsContainer interface get or set the properties described in the following table. For more information, and a general discussion about property methods, see Interface Property Methods.

Properties

Property Description
Count

[Visual Basic]
Access: Read-only
DataType: Long

[C++]
HRESULT get_Count
([out] LONG* plCount);

Retrieves the number of items in the container. When Filter is set, Count returns only the number of filtered items.
Filter

[Visual Basic]
Access: Read/Write
DataType: Variant

[C++]
HRESULT get_Filter
([out] VARIANT* pvFilter);
HRESULT put_Filter
([in] VARIANT vFilter);

Retrieves or sets the filter used to select object classes in a given enumeration. This is a variant array, each element of which is the name of a schema class. If Filter is not set or set to empty, all objects of all classes are retrieved by the enumerator.
Hints

[Visual Basic]
Access: Read/Write
DataType: Variant

[C++]
HRESULT get_Hints
([out] VARIANT* pvHints);
HRESULT put_Hints
([in] VARIANT vHints);

A variant array of BSTR strings. Each element identifies the name of a property found in the schema definition. The vHints parameter enables the client to indicate which attributes to load for each enumerated object. Such data may be used to optimize network access. The exact implementation, however, is provider-specific, and is currently not used by the WinNT, NWCOMPAT, and NDS providers.

Remarks

The enumeration processes under IADsContainer::get__NewEnum and IADsContainer::get_Count are performed against the contained objects in the cache. When a container contains a large number of objects, the performance may be affected. To enhance performance, turn off the cache, set up an appropriate page size, and use the IDirectorySearch interface. For this reason, the get_Count property is not supported in the Microsoft LDAP provider.

Example Code [Visual Basic]

The following Visual Basic code example shows how property methods of IADsContainer can be used.

Dim cont As IADsContainer
Dim usr As IADsUser

On Error GoTo Cleanup
 
Set cont = GetObject("LDAP://OU=Sales, DC=Fabrikam, DC=COM")
cont.Hints = Array("adminDescription") ' Load this attribute. Optional.
Debug.Print cont.Get("adminDescription")

' Filter users.
cont.Filter = Array("user")

For Each usr In cont
  Debug.Print usr.Name
Next

Cleanup:
	If (Err.Number<>0) Then
		MsgBox("An error has occurred. " & Err.Number)
	End If
	Set cont = Nothing
	Set usr = Nothing

Example Code [C++]

The following C++ code example shows how the property methods of IADsContainer can be used. For brevity, error checking is omitted.

IADsContainer *pCont;
IADs *pChild;
IADs *pADs;
 
HRESULT hr = ADsGetObject(L"LDAP://OU=Sales,DC=Fabrikam,DC=COM",
						IID_IADsContainer, 
						(void**)&pCont);

if(FAILED(hr)){goto Cleanup;}

LPWSTR pszArray[] = { L"adminDescription" };
DWORD dwNumber = sizeof(pszArray)/sizeof(LPWSTR);
hr = ADsBuildVarArrayStr( pszArray, dwNumber, &var);
if(FAILED(hr)){goto Cleanup;}

hr = pCont->put_Hints( var );
if(FAILED(hr)){goto Cleanup;}

VariantClear(&var);
 
hr = pCont->QueryInterface(IID_IADs, (void**)pADs);
if(FAILED(hr)){goto Cleanup;}
 
hr = pADs->Get(CComBSTR("adminDescription"), var);
 
LPWSTR pszUsers = {L"user"};
dwNumber = sizeof(pszUsers)/sizeof(LPWSTR);
hr = ADsBuildVarArrayStr(pszUsers, dwNumber, &var);
hr = pCont->put_Filter( var );
VariantClear(&var);
 
// Enumerate user objects in the container.
IEnumVARIANT *pEnum = NULL;
hr = ADsBuildEnumerator(pCont, &pEnum);
pCont->Release(); // Not required when users are enumerated.
 
ULONG lFetch;
VariantClear(&var);
while (SUCCEEDED(ADsEnumerateNext(pEnum, 1, &var, &lFetch)) && 
					lFetch==1) {
	hr = V_DISPATCH(&var)->QueryInterface(IID_IADs, (void**)&pChild)
	if(SUCCEEDED(hr)) {
		BSTR bstrName;
		pChild->get_Name(&bstrName);
		printf("  %S\n", bstrName);
		SysFreeString(bstrName);
		pChild->Release();
}
	VariantClear(&var);
}
Cleanup:
	if(pADs)
		pADs->Release();

	if(pCont)
		pCont->Release();

	if(pChild)
		pChild->Release();

	VariantClear(&var);

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

IADsContainer, IDirectorySearch