Directory Services

DsBrowseForContainer

The DsBrowseForContainer function displays a dialog box used to browse for Active Directory container objects.

int DsBrowseForContainer(
  PDSBROWSEINFO pInfo
);

Parameters

pInfo: [in] Pointer to a DSBROWSEINFO structure that contains data about how to initialize the container browser dialog and recevies data about the selected object.

Return Values

The function returns one of the following values.

-1: An error occurred.
IDCANCEL: The user cancelled the dialog box.
IDOK: The user selected an object in the dialog box and accepted the selection.

Remarks

The dialog box displays a container picker which is either populated with containers from a particular root or which uses trusted domains. If it uses trusted domains, it can use either the domain that the user is currently logged on to, or it can use an alternate domain specified by the application using the pszRoot member of the DSBROWSEINFO structure. If the user clicks the OK pushbutton or double-clicks an object, IDOK is returned and pszPath contains the ADsPath of the selected object. If the user cancels the dialog box, DsBrowseForContainer returns IDCANCEL.

The pszRoot member contains an ADsPath, which requires the following form.

LDAP://fabrikam.com/CN=Users,DC=Fabrikam,DC=com

DsBrowseForContainer uses this path as the root of the tree. The pszRoot member can also be used to specify a domain that has a trust with the domain that the user is logged on to, so that the user can browse the Users container of the alternate domain. If the pszPath member contains a path, the dialog will navigate from pszRoot through the containers until it reaches the object specified by pszPath.

The DsBrowseForContainer function supports a callback function as specified in the DSBROWSEINFO structure. The callback function can be used to filter, modify, or otherwise update the view based on selection change, and so on. For more information, see BFFCallBack.

Example Code

The following code example shows using this function to choose a container in the domain that the user is logged on to. The view also displays all the trusted domains.

void PickContainer(void)
{
	DSBROWSEINFO dsbi = { 0 };
	WCHAR wszResult[MAX_PATH];
 
	dsbi.cbStruct = SIZEOF(dsbi);
	dsbi.pszCaption = TEXT("The container picker");
	dsbi.pszTitle = TEXT("Pick a container for this example. This will be returned if the user clicks ""OK""");
	dsbi.pszPath = wszResult;
	dsbi.cchPath = MAX_PATH;
	dsbi.dwFlags = DSBI_ENTIREDIRECTORY;
 
	if ( IDOK == DsBrowseForContainer(&dsbi) )
	{
		// wszResult contains the resulting path
}
}

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.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.
Header: Declared in Dsclient.h.
Library: Use Dsuiext.lib.