Domain Browser

Using the IDsBrowseDomainTree interface, an application can display a domain browser dialog box and obtain the DNS name of the domain selected by the user. An application can also use the IDsBrowseDomainTree interface to obtain data about all domain trees and domains within a forest.

An instance of the IDsBrowseDomainTree interface is created by calling CoCreateInstance with the CLSID_DsDomainTreeBrowser class identifier as shown below.

The IDsBrowseDomainTree::SetComputer method can be used to specify which computer and credentials are used as the basis for retrieving the domain data. When SetComputer is called on a particular IDsBrowseDomainTree instance, IDsBrowseDomainTree::FlushCachedDomains must be called before SetComputer is called again.

The IDsBrowseDomainTree::BrowseTo method is used to display the domain browser dialog box. When the user selects a domain and clicks the OK button, the IDsBrowseDomainTree::BrowseTo returns S_OK and the ppszTargetPath parameter contains the name of the selected domain. When the name string is no longer required, the caller must free the string by calling CoTaskMemFree.

The following code example shows how to use the IDsBrowseDomainTree interface to display the domain browser dialog box.

#include <shlobj.h>
#include <dsclient.h>

void main(void)
{
    HRESULT     hr;

    hr = CoInitialize(NULL);
    if(FAILED(hr)) 
    {
        return;
    }

    IDsBrowseDomainTree *pDsDomains = NULL;

    hr = ::CoCreateInstance(    CLSID_DsDomainTreeBrowser,
                                NULL,
                                CLSCTX_INPROC_SERVER,
                                IID_IDsBrowseDomainTree,
                                (void **)(&pDsDomains));
    
    if(SUCCEEDED(hr))
    {
        LPOLESTR    pstr;        

        hr = pDsDomains->BrowseTo(  GetDesktopWindow(),
                                    &pstr,
                                    0);
        
        if(S_OK == hr)
        {
            wprintf(pstr);
            wprintf(L"\n");
            CoTaskMemFree(pstr);
        }

        pDsDomains->Release();
    }

    CoUninitialize();
}

The IDsBrowseDomainTree::GetDomains method is used to obtain domain tree data. The domain data is supplied in a DOMAINTREE structure. The DOMAINTREE structure contains the size of the structure and the number of domain elements in the tree. The DOMAINTREE structure also contains one or more DOMAINDESC structures. The DOMAINDESC contains data about a single element in the domain tree, including child and sibling data. The siblings of a domain can be enumerated by accessing the pdNextSibling member of each subsequent DOMAINDESC structure. The children of the domain can be retrieved in a similar manner by accessing the pdChildList member of each subsequent DOMAINDESC structure.

The following code example shows how to obtain and access the domain tree data using the IDsBrowseDomainTree::GetDomains method.

//  Add dsuiext.lib to the project.

#include "stdafx.h"
#include <shlobj.h>
#include <dsclient.h>

//The PrintDomain() function displays the domain name
void PrintDomain(DOMAINDESC *pDomainDesc, DWORD dwIndentLevel)
{
    DWORD i;

    // Display the domain name.
    for(i = 0; i < dwIndentLevel; i++)
    {
        wprintf(L"  ");
    }
    wprintf(pDomainDesc->pszName);
    wprintf(L"\n");
}

//The WalkDomainTree() function traverses the domain tree and prints the current domain name
void WalkDomainTree(DOMAINDESC *pDomainDesc, DWORD dwIndentLevel = 0)
{
    DOMAINDESC  *pCurrent;

    // Walk through the current item and any siblings it may have.
    for(pCurrent = pDomainDesc; 
        NULL != pCurrent; 
        pCurrent = pCurrent->pdNextSibling)
    {
        // Print the current domain name.
        PrintDomain(pCurrent, dwIndentLevel);

        // Walk the child tree, if one exists.
        if(NULL != pCurrent->pdChildList)
        {
            WalkDomainTree(pCurrent->pdChildList, 
                           dwIndentLevel + 1);
        }
    }
}

//  Entry point for application
int main(void)
{
    HRESULT hr;
    IDsBrowseDomainTree *pBrowseTree;
    CoInitialize(NULL);

    hr = CoCreateInstance(CLSID_DsDomainTreeBrowser,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_IDsBrowseDomainTree,
                          (void**)&pBrowseTree);

    if(SUCCEEDED(hr))
    {
        DOMAINTREE  *pDomTreeStruct;
        hr = pBrowseTree->GetDomains(&pDomTreeStruct, 
                                     DBDTF_RETURNFQDN);
        if(SUCCEEDED(hr))
        {
            WalkDomainTree(&pDomTreeStruct->aDomains[0]);
            hr = pBrowseTree->FreeDomains(&pDomTreeStruct);
        }
        pBrowseTree->Release();
    }
    CoUninitialize();
}