Browser Kontainer

Aplikasi dapat menggunakan fungsiDsBrowseForContainer untuk menampilkan kotak dialog yang dapat digunakan untuk menelusuri kontainer dalam Layanan Domain Direktori Aktif. Kotak dialog menampilkan kontainer dalam format pohon dan memungkinkan pengguna menavigasi melalui pohon menggunakan keyboard dan mouse. Saat pengguna memilih item dalam kotak dialog, ADsPath kontainer yang dipilih oleh pengguna disediakan.

DsBrowseForContainer membawa pointer ke strukturDSBROWSEINFOyang berisi data tentang kotak dialog dan mengembalikan ADsPath dari item yang dipilih.

Anggota pszRoot adalah penunjuk ke string Unicode yang berisi kontainer akar pohon. Jika pszRootNULL, pohon akan berisi seluruh pohon.

Anggota pszPath menerima ADsPath dari objek yang dipilih. Dimungkinkan untuk menentukan kontainer tertentu untuk terlihat dan dipilih saat kotak dialog pertama kali ditampilkan. Ini dicapai dengan mengatur pszPath ke ADsPath item yang akan dipilih dan mengatur bendera DSBI_EXPANDONOPEN di dwFlags.

Konten dan perilaku kotak dialog juga dapat dikontrol saat runtime dengan menerapkan fungsi BFFCallBack. Fungsi BFFCallBack diimplementasikan oleh aplikasi dan dipanggil ketika peristiwa tertentu terjadi. Aplikasi dapat menggunakan peristiwa ini untuk mengontrol bagaimana item dalam kotak dialog ditampilkan serta konten aktual kotak dialog. Misalnya, aplikasi dapat memfilter item yang ditampilkan dalam kotak dialog dengan menerapkan fungsi BFFCallBack yang dapat menangani pemberitahuan DSBM_QUERYINSERT. Saat pemberitahuan DSBM_QUERYINSERT diterima, gunakan pszADsPath anggota strukturDSBITEMuntuk menentukan item mana yang akan dimasukkan. Jika aplikasi menentukan bahwa item tidak boleh ditampilkan, aplikasi dapat menyembunyikan item dengan melakukan langkah-langkah berikut.

1. Tambahkan bendera DSBF_STATE ke dwMask anggota strukturDSBITEM.
2. Tambahkan bendera DSBS_HIDDEN ke dwStateMask anggota strukturDSBITEM.
3. Tambahkan bendera DSBS_HIDDEN ke dwState anggota strukturDSBITEM.
4. Mengembalikan nilai bukan nol dari fungsiBFFCallBack.

Selain menyembunyikan item tertentu, aplikasi dapat mengubah teks dan ikon yang ditampilkan untuk item dengan menangani pemberitahuan DSBM_QUERYINSERT. Untuk informasi selengkapnya, lihatDSBITEM.

FungsiBFFCallBack dapat menggunakan pemberitahuan BFFM_INITIALIZED untuk mendapatkan handel kotak dialog. Aplikasi dapat menggunakan handel ini untuk mengirim pesan, seperti BFFM_ENABLEOK, ke kotak dialog. Untuk informasi selengkapnya tentang pesan yang dapat dikirim ke kotak dialog, lihat BFFCallBack.

Handel kotak dialog juga dapat digunakan untuk mendapatkan akses langsung ke kontrol dalam kotak dialog. DSBID_BANNER adalah pengidentifikasi untuk kontrol teks statis tempat pszTitle anggota strukturDSBROWSEINFOditampilkan. DSBID_CONTAINERLIST adalah pengidentifikasi kontrol tampilan pohon yang digunakan untuk menampilkan konten pohon. Penggunaan item ini harus dihindari, jika memungkinkan, untuk mencegah masalah kompatibilitas aplikasi di masa mendatang.

Contoh kode C++ berikut menunjukkan cara menggunakan fungsiDsBrowseForContainer untuk membuat kotak dialog browser kontainer dan menerapkan fungsiBFFCallBack. BFFCallBack menggunakan pemberitahuan DSBM_QUERYINSERT untuk mengubah nama tampilan untuk setiap item menjadi nama khusus item.

#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;
}