Platform SDK: Active Directory, ADSI, and Directory Services

DsBrowseForContainer

The DsBrowseForContainer function sets up and displays a simple dialog for users to use to scope parts of the Active Directory™. The dialog displays a simple 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 in to, or it can use a domain that the user has specified. The user can specify a caption, title, root, and, optionally, an expansion path for the dialog to be expanded to. Upon exiting, the path and object class of the selected object is returned. The dialog also supports a callback to allow the user to override some of the default behaviors or to provide extra filtering.

int DsBrowseForContainer(
  PDSBROWSEINFO pInfo
);

Parameters

pInfo: [in] A pointer to the DSBROWSEINFO structure.

Return Values

The function returns the following values

Return value	Description
-1	There is an error.
IDCANCEL	The user clicked the CANCEL button on the dialog.
IDOK	The user clicked the OK button on the dialog.

Remarks

The function takes in a DSBROWSEINFO structure and displays the browse dialog. The user can then expand and navigate the tree to see the containers. If they click OK or double-click an object, IDOK is returned and pszPath contains the ADsPath of the selected object. If they press ESCAPE or Cancel, they receive IDCANCEL.

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

The browse dialog is used for the "Browse..." button in "Start->Search->For Printers".

Example Code [C++]

Here is a simple example of using this API to pick a container in the domain that the user is logged in to. The view will also display all the trusted domains:

void PickContainer(void)
{
    DSBROWSEINFO dsbi = { 0 };
    WCHAR szResult[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 = szResult;
    dsbi.cchPath = ARRAYSIZE(szResult);
    dsbi.dwFlags = DSBI_ENTIREDIRECTORY;
 
    if ( IDOK == DsBrowseForContainer(&dsbi) )
    {
        // szResult => resulting path!
    }
}

Requirements