Arkusze właściwości Użytkownicy i komputery usługi Active Directory

Przystawka MMC Użytkownicy i komputery usługi Active Directory jest przeznaczona do wyświetlania arkusza właściwości dla różnych obiektów na serwerze usługi Active Directory. Arkusz właściwości zawiera co najmniej jedną stronę używaną do wyświetlania i modyfikowania danych obiektu. Różne typy obiektów mają różne zestawy wyświetlanych dla nich stron. Przystawka MMC Użytkownicy i komputery usługi Active Directory umożliwia również dostawcom zewnętrznym dodawanie niestandardowych stron do arkusza właściwości dla określonego typu obiektu. Aby uzyskać więcej informacji, zobacz Strony właściwości do użycia z specyfikatorami wyświetlania.

Niektóre aplikacje, inne niż przystawka MMC Użytkownicy i komputery usługi Active Directory, muszą udostępnić użytkownikowi widok i edytować atrybuty obiektu na serwerze usługi Active Directory. Aplikacja może zaimplementować własne arkusze właściwości, ale lepiej jest zaoferować spójny interfejs użytkownika w celu zmniejszenia nieporozumień i czasu nauki. Na szczęście przystawka MMC Użytkownicy i komputery usługi Active Directory umożliwia każdej aplikacji OLE COM wyświetlanie arkusza właściwości dla obiektu, który jest identyczny z arkuszem właściwości, który będzie wyświetlany przez przystawkę MMC użytkownicy i komputery usługi Active Directory dla tego samego obiektu.

Aby uzyskać więcej informacji i przykład kodu hostujący arkusz właściwości Użytkownicy i komputery usługi Active Directory, zobacz przykład PropSheetHost w zestawie Sdk (Platform Software Development Kit).

Odbiorcy deweloperów

W tej dokumentacji przyjęto założenie, że czytelnik zna operacje modelu COM i programowanie składników przy użyciu języka C++. Obecnie nie można utworzyć rozszerzenia arkusza właściwości usługi Active Directory przy użyciu języka Visual Basic.

Hostowanie arkusza właściwości Użytkownicy i komputery usługi Active Directory

Aby wyświetlić arkusz właściwości dla obiektu na serwerze usługi Active Directory

1. Utwórz okno, które może służyć do przetwarzania komunikatów. Może to być istniejące okno lub okno specjalnego przeznaczenia. Jest to nazywane ukrytym oknem .

2. Utwórz obiekt OLE COM pochodzący z IDataObject. Ten obiekt danych musi obsługiwać następujące formaty danych:

   • CFSTR_DSOBJECTNAMES Ten format danych zawiera DSOBJECTNAMES identyfikujący obiekt, do którego ma zastosowanie arkusz właściwości. Podczas hostowania arkusza właściwości na poniższej liście są wyświetlane bardziej znaczące elementy członkowskie struktury DSOBJECTNAMES.

     clsidNamespace zarezerwowane. Ustaw go na identyfikator GUID dla aplikacji w tym miejscu, jeśli zostanie on użyty w przyszłości.

     aObjects Zawiera tablicę struktur DSBOJECT. Każda struktura DSBOJECT reprezentuje pojedynczy obiekt katalogu. Element członkowski cItems zawiera liczbę elementów w tablicy. Używany jest tylko pierwszy obiekt w tej tablicy. Inne obiekty są ignorowane.

   • CFSTR_DSDISPLAYSPECOPTIONS Ten format danych zawiera DSDISPLAYSPECOPTIONS struktury zawierającej dane, które będą używane przez strony właściwości, takie jak miejsce ładowania stron właściwości z serwera i poświadczeń do użycia itd. Bardziej znaczące elementy członkowskie DSDISPLAYSPECOPTIONS są wyświetlane na poniższej liście.

     offsetAttribPrefix Ciąg prefiksu atrybutu określa, gdzie jest uzyskiwana lista stron właściwości. Musi zawierać jeden z następujących ciągów.

     Ciąg prefiksu atrybutu	Opis
     "administrator"	Strony właściwości są ładowane z atrybutu adminPropertyPages.
     "powłoka"	Strony właściwości są ładowane z atrybutu shellPropertyPages.

   • CFSTR_DS_PROPSHEETCONFIG Ten format danych zawiera strukturę PROPSHEETCFG zawierającą dane hosta arkusza właściwości. Podczas hostowania arkusza właściwości bardziej znaczące elementy członkowskie struktury PROPSHEETCFG zawierają dane przedstawione na poniższej liście.

     lNotifyHandle musi być zero. hwndParentSheet Zawiera uchwyt okna do odbierania komunikatów WM_ADSPROP_NOTIFY_CHANGE, gdy coś na jednej ze stron ulegnie zmianie i zostanie zastosowane. Jeśli ten komunikat nie jest pożądany, można NULL.

     hwndHidden Zawiera uchwyt okna do odbierania komunikatów WM_DSA_SHEET_CREATE_NOTIFY i WM_DSA_SHEET_CLOSE_NOTIFY. Ustaw tę opcję na uchwyt ukrytego okna.

     wParamSheetClose Zawiera identyfikator zdefiniowany przez aplikację zwrócony w wParam w komunikacie WM_DSA_SHEET_CLOSE_NOTIFY. Jeśli ten element członkowski ma wartość zero, komunikat WM_DSA_SHEET_CLOSE_NOTIFY nie zostanie opublikowany w ukrytym oknie.

3. Utwórz wystąpienie obiektu CLSID_DsPropertyPages i uzyskaj interfejs IShellExtInit dla obiektu. Istnieje również możliwość zduplikowania zachowania obiektu CLSID_DsPropertyPages. Aby uzyskać więcej informacji, zobacz Duplikowanie zachowania obiektu CLSID_DsPropertyPages.

4. Zainicjuj obiekt CLSID_DsPropertyPages, wywołując metodę IShellExtInit::Initialize. Parametry pidlFolder i hkeyProgID nie są używane w tej metodzie. Parametr pdtobj jest wskaźnikiem do obiektu danych utworzonego w kroku 2. Po wywołaniu metody IShellExtInit::Initialize obiekt CLSID_DsPropertyPages zapisze odwołanie do obiektu danych.

5. Uzyskaj interfejs IShellPropSheetExt dla obiektu CLSID_DsPropertyPages i wywołaj metodę IShellPropSheetExt::AddPages. Parametr lpfnAddPage jest adresem funkcji wywołania zwrotnego, którą należy zaimplementować. Poniżej przedstawiono format tej funkcji. Jeśli funkcja wywołania zwrotnego jest zadeklarowana jako element członkowski klasy C++, funkcja wywołania zwrotnego musi być zadeklarowana jako statyczna. Parametr lParam jest wartością zdefiniowaną przez aplikację, która może służyć do identyfikowania obiektu implementujące funkcję wywołania zwrotnego. Po wywołaniu metody IShellPropSheetExt::AddPages obiekt CLSID_DsPropertyPages uzyska dane z obiektu danych i wyliczy strony właściwości zarejestrowane dla specyfikatorów wyświetlania obiektu. Następnie obiekt CLSID_DsPropertyPages wylicza obiekty strony właściwości, wywołując metodę IShellPropSheetExt::AddPages obiektu.

   BOOL CALLBACK AddPagesCallback(HPROPSHEETPAGE, LPARAM)
   

6. Każda strona dodana przez obiekty strony właściwości spowoduje wywołanie zwrotne funkcji wywoływanej z uchwytem do strony właściwości i wartości zdefiniowanej przez aplikację. Funkcja wywołania zwrotnego musi przechowywać każdy obsługiwany uchwyt strony właściwości, który jest przekazywany. Gdy zostanie zwrócona metoda CLSID_DsPropertyPages obiektu IShellPropSheetExt::AddPages, wszystkie strony zostaną dodane za pośrednictwem funkcji wywołania zwrotnego.

7. Wypełnij strukturę PROPSHEETHEADER, aby wyświetlić arkusz właściwości. Element phpage otrzymuje wskaźnik do tablicy dojść strony zebranych przez funkcję wywołania zwrotnego. Element członkowski nPages otrzymuje liczbę stron w tablicy dojścia strony.

8. Wyświetl arkusz właściwości, wywołując funkcję PropertySheet.

Jeśli dane na dowolnej stronie zostaną zmienione, a ok lub przycisków Zastosuj zostaną kliknięte, okno zidentyfikowane przez hwndParentSheet składowej struktury PROPSHEETCFG otrzyma komunikat WM_ADSPROP_NOTIFY_CHANGE. Ta wiadomość jest ściśle powiadomieniem i nie wymaga określonej akcji.

Po zamknięciu strony okno zidentyfikowane przez hwndHidden elementu członkowskiego PROPSHEETCFG będzie otrzymywać komunikat o WM_DSA_SHEET_CLOSE_NOTIFY. Ten komunikat jest ściśle powiadomieniem i nie wymaga wykonania określonej akcji.

W niektórych przypadkach istniejące arkusze właściwości będą musiały wyświetlić pomocniczy arkusz właściwości. Na przykład jeśli wyświetlisz arkusz właściwości dla obiektu użytkownika i wybierzesz element członkowski strony, zostanie wyświetlona lista grup, których użytkownik jest członkiem. Jeśli klikniesz dwukrotnie jedną z tych grup na liście, zostanie wyświetlony arkusz właściwości dla tej grupy. Podstawowy arkusz właściwości nie wyświetla samego arkusza pomocniczego. Żąda, aby host wyświetlił arkusz pomocniczy, wysyłając komunikat WM_DSA_SHEET_CREATE_NOTIFY do okna zidentyfikowanego przez hwndHidden członka struktury PROPSHEETCFG. wParam komunikatu WM_DSA_SHEET_CREATE_NOTIFY jest wskaźnikiem do struktury DSA_SEC_PAGE_INFO zawierającej informacje o pomocniczym arkuszu właściwości i obiekcie, który reprezentuje. W odpowiedzi na ten komunikat host arkusza właściwości musi wyświetlić pomocniczy arkusz właściwości w taki sam sposób, jak pokazano powyżej. Po przetworzeniu komunikatu WM_DSA_SHEET_CREATE_NOTIFY odbiornik komunikatów musi zwolnić strukturę DSA_SEC_PAGE_INFO, przekazując wartość wParam do funkcji LocalFree.

Duplikowanie zachowania obiektu CLSID_DsPropertyPages

Aby zduplikować zachowanie obiektu CLSID_DsPropertyPages

1. Wylicz wartości w adminPropertyPages lub shellPropertyPages atrybutu dla specyfikatora wyświetlania dla klasy obiektu. Każda wartość jest ciągiem zawierającym liczbę, po której następuje przecinek, po którym następuje reprezentacja ciągu identyfikatora klasy rozszerzenia strony właściwości. Aby uzyskać więcej informacji na temat formatu stron właściwości wyświetlających wartości specyfikatora, zobacz Rejestrowanie obiektu COM strony właściwości w specyfikatorze wyświetlania.
2. Przekonwertuj każdy ciąg identyfikatora klasy na CLSID przy użyciu funkcji CLSIDFromString.
3. Posortuj identyfikatory klas rozszerzeń według liczby, która poprzedza każdy ciąg identyfikatora klasy w wartości atrybutu. Jeśli dwie liczby są identyczne, posortuj identyfikatory klas w kolejności, w jakiej wartości atrybutów są uzyskiwane z serwera usługi Active Directory.
4. Wyliczaj identyfikatory klas rozszerzeń, tworząc wystąpienie każdego rozszerzenia.
5. Dla każdego rozszerzenia w kolejności posortowanej powyżej wywołaj rozszerzenia IShellExtInit::Initialize z tymi samymi informacjami opisanymi w kroku 4 procedury hostowania arkusza właściwości Użytkownicy i komputery usługi Active Directory.
6. Dla każdego rozszerzenia w kolejności posortowanej powyżej wywołaj rozszerzenia IShellPropSheetExt::AddPages z tymi samymi informacjami opisanymi w kroku 5 procedury hostowania arkusza właściwości Użytkownicy i komputery usługi Active Directory.

Jeśli to możliwe, użyj obiektu CLSID_DsPropertyPages, aby utworzyć strony, a nie ręcznie. CLSID_DsPropertyPages została zoptymalizowana i będzie poprawnie obsługiwać przypadki awarii, takie jak brak specyfikatora wyświetlania jest dostępny dla bieżących ustawień regionalnych. Ponadto obiekt CLSID_DsPropertyPages może ulec zmianie w przyszłości, co oznacza, że arkusze właściwości mogą nie być dokładnie zgodne z tymi wyświetlanymi przez przystawkę MMC Użytkownicy i komputery usługi Active Directory.

Specjalne elementy programowania

Obecnie następujące elementy programowania nie są zdefiniowane w opublikowanym pliku nagłówka. Aby użyć tych elementów, musisz zdefiniować je samodzielnie w dokładnym formacie pokazanym na określonej stronie referencyjnej.

• CFSTR_DS_PROPSHEETCONFIG
• PROPSHEETCFG
• WM_DSA_SHEET_CLOSE_NOTIFY
• WM_DSA_SHEET_CREATE_NOTIFY
• DSA_SEC_PAGE_INFO

Przykładowy kod

Poniższy przykład kodu C++ przedstawia bezpieczny sposób definiowania tych elementów, które będą nadal działać, nawet jeśli te elementy są zdefiniowane w opublikowanym pliku nagłówka w przyszłości.

#ifndef CFSTR_DS_PROPSHEETCONFIG
    #define CFSTR_DS_PROPSHEETCONFIG_W L"DsPropSheetCfgClipFormat"
    #define CFSTR_DS_PROPSHEETCONFIG_A "DsPropSheetCfgClipFormat"

    #ifdef UNICODE
        #define CFSTR_DS_PROPSHEETCONFIG CFSTR_DS_PROPSHEETCONFIG_W
    #else
        #define CFSTR_DS_PROPSHEETCONFIG CFSTR_DS_PROPSHEETCONFIG_A
    #endif //UNICODE
#endif //CFSTR_DS_PROPSHEETCONFIG


#ifndef WM_ADSPROP_SHEET_CREATE
    #define WM_ADSPROP_SHEET_CREATE (WM_USER + 1108)
#endif


#ifndef WM_DSA_SHEET_CREATE_NOTIFY
    #define WM_DSA_SHEET_CREATE_NOTIFY (WM_USER + 6)
#endif


#ifndef WM_DSA_SHEET_CLOSE_NOTIFY
    #define WM_DSA_SHEET_CLOSE_NOTIFY (WM_USER + 5) 
#endif


#ifndef DSA_SEC_PAGE_INFO
    typedef struct _DSA_SEC_PAGE_INFO
    {
        HWND    hwndParentSheet;
        DWORD   offsetTitle;
        DSOBJECTNAMES dsObjectNames;
    } DSA_SEC_PAGE_INFO, *PDSA_SEC_PAGE_INFO;
#endif //DSA_SEC_PAGE_INFO

#ifndef PROPSHEETCFG
    typedef struct _PROPSHEETCFG
    {  
        LONG_PTR lNotifyHandle;  
        HWND hwndParentSheet;  
        HWND hwndHidden;  
        WPARAM wParamSheetClose;
    } PROPSHEETCFG, *PPROPSHEETCFG;
#endif //PROPSHEETCFG