Przeglądarka kontenerów

Aplikacja może użyć funkcji DsBrowseForContainer, aby wyświetlić okno dialogowe, którego można użyć do przeglądania kontenerów w usłudze domenowej Active Directory. W oknie dialogowym są wyświetlane kontenery w formacie drzewa i umożliwia użytkownikowi przechodzenie przez drzewo przy użyciu klawiatury i myszy. Gdy użytkownik wybierze element w oknie dialogowym, zostanie podana ścieżka ADsPath kontenera wybranego przez użytkownika.

DsBrowseForContainer przyjmuje wskaźnik do DSBROWSEINFO struktury zawierającej dane dotyczące okna dialogowego i zwraca ścieżkę ADsPath wybranego elementu.

Element członkowski pszRoot jest wskaźnikiem do ciągu Unicode zawierającego kontener główny drzewa. Jeśli pszRoot ma wartość null , drzewo będzie zawierać całe drzewo.

Element członkowski pszPath otrzymuje ścieżkę ADsPath wybranego obiektu. Istnieje możliwość określenia określonego kontenera, który ma być widoczny i wybrany po pierwszym wyświetleniu okna dialogowego. Jest to realizowane przez ustawienie pszPath na ścieżkę ADsPath elementu do wybrania i ustawienie flagi DSBI_EXPANDONOPEN w dwFlags.

Zawartość i zachowanie okna dialogowego można również kontrolować w czasie wykonywania, implementując funkcję BFFCallBack. Funkcja BFFCallBack jest implementowana przez aplikację i jest wywoływana w przypadku wystąpienia niektórych zdarzeń. Aplikacja może używać tych zdarzeń do kontrolowania sposobu wyświetlania elementów w oknie dialogowym oraz rzeczywistej zawartości okna dialogowego. Na przykład aplikacja może filtrować elementy wyświetlane w oknie dialogowym, implementując funkcję BFFCallBack, która może obsługiwać powiadomienie DSBM_QUERYINSERT. Po odebraniu powiadomienia DSBM_QUERYINSERT użyj elementu pszADsPath elementu członkowskiego DSBITEM, aby określić, który element ma zostać wstawiony. Jeśli aplikacja ustali, że element nie powinien być wyświetlany, może ukryć element, wykonując następujące kroki.

1. Dodaj flagę DSBF_STATE do dwMask elementu członkowskiego struktury DSBITEM.
2. Dodaj flagę DSBS_HIDDEN do elementu członkowskiego dwStateMask strukturyDSBITEM.
3. Dodaj flagę DSBS_HIDDEN do dwState składowej strukturyDSBITEM.
4. Zwraca wartość niezerową z funkcji BFFCallBack.

Oprócz ukrywania niektórych elementów aplikacja może modyfikować tekst i ikonę wyświetlaną dla elementu, obsługując powiadomienie DSBM_QUERYINSERT. Aby uzyskać więcej informacji, zobacz DSBITEM.

Funkcja BFFCallBack może użyć powiadomienia BFFM_INITIALIZED w celu uzyskania uchwytu okna dialogowego. Aplikacja może użyć tego uchwytu do wysyłania komunikatów, takich jak BFFM_ENABLEOK, do okna dialogowego. Aby uzyskać więcej informacji na temat komunikatów, które można wysłać do okna dialogowego, zobacz BFFCallBack.

Uchwyt okna dialogowego może również służyć do uzyskania bezpośredniego dostępu do kontrolek w oknie dialogowym. DSBID_BANNER jest identyfikatorem statycznej kontrolki tekstu, w którą jest wyświetlana strukturapszTitleDSBROWSEINFO. DSBID_CONTAINERLIST jest identyfikatorem kontrolki widoku drzewa używanej do wyświetlania zawartości drzewa. Należy unikać używania tych elementów, jeśli to możliwe, aby zapobiec przyszłym problemom ze zgodnością aplikacji.

Poniższy przykład kodu C++ pokazuje, jak używać funkcji DsBrowseForContainer w celu utworzenia okna dialogowego przeglądarki kontenerów i zaimplementowania funkcjiBFFCallBack. BFFCallBack używa powiadomienia DSBM_QUERYINSERT, aby zmienić nazwę wyświetlaną każdego elementu na nazwę wyróżniającą elementu.

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

/**********

    WideCharToLocal()
   
***********/

int WideCharToLocal(LPTSTR pLocal, LPWSTR pWide, DWORD dwChars)
{
    *pLocal = NULL;
    size_t nWideLength = 0;
    wchar_t *pwszSubstring;

    nWideLength = wcslen(pWide);

#ifdef UNICODE
    if(nWideLength < dwChars)
    {
        wcsncpy_s(pLocal, pWide, dwChars);
    }
    else
    {
        wcsncpy_s(pLocal, pWide, dwChars-1);
        pLocal[dwChars-1] = NULL;
    }
#else
    if(nWideLength < dwChars)
    {
        WideCharToMultiByte(    CP_ACP, 
                                0, 
                                pWide, 
                                -1, 
                                pLocal, 
                                dwChars, 
                                NULL, 
                                NULL);
    }
    else
    {
        pwszSubstring = new WCHAR[dwChars];
        wcsncpy_s(pwszSubstring,pWide,dwChars-1);
        pwszSubstring[dwChars-1] = NULL;

        WideCharToMultiByte(    CP_ACP, 
                                0, 
                                pwszSubstring, 
                                -1, 
                                pLocal, 
                                dwChars, 
                                NULL, 
                                NULL);

    delete [] pwszSubstring;
    }
#endif

    return lstrlen(pLocal);
}

/**********

    BrowseCallback()

***********/

int CALLBACK BrowseCallback(HWND hWnd, 
                            UINT uMsg, 
                            LPARAM lParam, 
                            LPARAM lpData)
{
    switch(uMsg)
    {
    case DSBM_QUERYINSERT:
        {
            BOOL fReturn = FALSE;
            DSBITEM *pItem = (DSBITEM*)lParam;

            /*
            If this is to the root item, get the distinguished name 
            for the object and set the display name to the 
            distinguished name.
            */
            if(!(pItem->dwState & DSBS_ROOT))
            {
                HRESULT hr;
                IADs    *pads;

                hr = ADsGetObject(pItem->pszADsPath , 
                    IID_IADs, (LPVOID*)&pads);
                if(SUCCEEDED(hr))
                {
                    VARIANT var;

                    VariantInit(&var);
                    hr = pads->Get(CComBSTR("distinguishedName"), 
                        &var);
                    if(SUCCEEDED(hr))
                    {
                        if(VT_BSTR == var.vt)
                        {
                            WideCharToLocal(pItem->szDisplayName, 
                                var.bstrVal, 
                                DSB_MAX_DISPLAYNAME_CHARS);
                            pItem->dwMask |= DSBF_DISPLAYNAME;
                            fReturn = TRUE;
                        }
                        
                        VariantClear(&var);
                    }
                    
                    pads->Release();
                }
            }

            return fReturn;
        }

        break;
    }
    
    return FALSE;
}

/***********

    BrowseForContainer()

************/

HRESULT BrowseForContainer(HWND hwndParent, 
    LPOLESTR *ppContainerADsPath)
{
    HRESULT hr = E_FAIL;
    DSBROWSEINFO dsbi;
    OLECHAR wszPath[MAX_PATH * 2];
    DWORD result;
 
    if(!ppContainerADsPath)
    {
        return E_INVALIDARG;
    }
 
    ZeroMemory(&dsbi, sizeof(dsbi));
    dsbi.hwndOwner = hwndParent;
    dsbi.cbStruct = sizeof (DSBROWSEINFO);
    dsbi.pszCaption = TEXT("Browse for a Container");
    dsbi.pszTitle = TEXT("Select an Active Directory container.");
    dsbi.pszRoot = NULL;
    dsbi.pszPath = wszPath;
    dsbi.cchPath = sizeof(wszPath)/sizeof(OLECHAR);
    dsbi.dwFlags = DSBI_INCLUDEHIDDEN |
                    DSBI_IGNORETREATASLEAF|
                    DSBI_RETURN_FORMAT;
    dsbi.pfnCallback = BrowseCallback;
    dsbi.lParam = 0;
    dsbi.dwReturnFormat = ADS_FORMAT_X500;
 
    // Display the browse dialog box.
    // Returns -1, 0, IDOK, or IDCANCEL.
    result = DsBrowseForContainer(&dsbi); 
    if(IDOK == result)
    {
        // Allocate memory for the string.
        *ppContainerADsPath = (OLECHAR*)CoTaskMemAlloc(
            sizeof(OLECHAR)*(wcslen(wszPath) + 1));
        if(*ppContainerADsPath)
        {
            wcscpy_s(*ppContainerADsPath, wszPath);
            // Caller must free using CoTaskMemFree. 
            hr = S_OK;
        }
        else
        {
            hr = E_FAIL;
        }
    }
    else
    {
        hr = E_FAIL;
    }
 
    return hr;
}