Implementacja rozszerzenia tworzenia obiektów COM

Rozszerzenie tworzenia obiektu jest obiektem COM zaimplementowanym jako serwer w procesie. Zarówno rozszerzenia tworzenia obiektów podstawowych, jak i pomocniczych muszą implementować interfejs IDsAdminNewObjExt.

Implementacja IDsAdminNewObjExt

Po utworzeniu kreatora tworzenia obiektu inicjuje każde rozszerzenie tworzenia obiektu przez wywołanie identyfikatorów rozszerzeniaAdminNewObjExt::Initialize metody. Metoda Initialize dostarcza rozszerzeniu informacji o kontenerze, w którym tworzony jest obiekt, nazwie klasy nowego obiektu i samym kreatorze. Jeśli kreator tworzenia obiektu zostanie uruchomiony w celu utworzenia nowego obiektu na podstawie istniejącego obiektu, parametr pADsCopySource nie będzie NULL. W takim przypadku rozszerzenie powinno podjąć próbę uzyskania jak najwięcej danych z skopiowanego obiektu.

Po zainicjowaniu rozszerzenia wywoływana jest metoda IDsAdminNewObjExt::AddPages. Rozszerzenie musi dodać stronę lub strony do kreatora podczas tej metody. Strona kreatora jest tworzona przez wypełnienie struktury PROPSHEETPAGE, a następnie przekazanie tej struktury do funkcji CreatePropertySheetPage. Następnie strona zostanie dodana do kreatora przy użyciu funkcji zwrotnej przekazanej do AddPages w parametrze o nazwie lpfnAddPage.

Przed wyświetleniem strony rozszerzenia wywoływana jest IDsAdminNewObjExt::SetObject. Dostarcza rozszerzeniu wskaźnik interfejsu IAD dla obiektu, który jest tworzony.

Gdy strona kreatora jest wyświetlana, powinna ona obsługiwać i odpowiadać na wszelkie niezbędne komunikaty powiadomień kreatora, takie jak PSN_SETACTIVE oraz PSN_WIZNEXT.

Gdy użytkownik ukończy wszystkie strony kreatora, kreator wyświetli stronę "Zakończ", która zawiera podsumowanie wprowadzonych danych. Kreator uzyskuje te dane, wywołując metodę IDsAdminNewObjExt::GetSummaryInfo dla każdego z rozszerzeń. Metoda GetSummaryInfo udostępnia BSTR, który zawiera dane tekstowe wyświetlane na stronie "Zakończ". Rozszerzenie tworzenia obiektu nie musi dostarczać danych podsumowania. W takim przypadku GetSummaryInfo powinien zwrócić E_NOTIMPL. GetSummaryInfo jest wywoływana tylko raz dla każdego rozszerzenia, a nie na stronę, więc jeśli rozszerzenie tworzenia obiektu dodaje więcej niż jedną stronę, rozszerzenie musi połączyć dane podsumowania w jeden ciąg.

Gdy użytkownik kliknie przycisk Zakończ na stronie "Zakończ", kreator wywołuje każdą z identyfikatorów rozszerzeniaAdminNewObjExt::WriteData z kontekstem DSA_NEWOBJ_CTX_PRECOMMIT. W takim przypadku rozszerzenie powinno zapisywać zebrane dane w odpowiednich właściwościach przy użyciu metody IADs::Put lub IADs::PutEx. Interfejs IADs jest dostarczany do rozszerzenia w metodzie IDsAdminNewObjExt::SetObject. Rozszerzenie nie powinno zatwierdzać buforowanych właściwości przez wywołanie IADs::SetInfo. Po zapisaniu wszystkich właściwości rozszerzenie tworzenia obiektu podstawowego zatwierdza zmiany, wywołując IADs::SetInfo. Zostało to omówione bardziej szczegółowo poniżej.

Jeśli wystąpi błąd, rozszerzenie zostanie o nim powiadomione oraz podczas której operacji do niego doszło, gdy wywoływana jest metoda IDsAdminNewObjExt::OnError.

Implementowanie kreatora tworzenia obiektu podstawowego

Implementacja kreatora tworzenia obiektu podstawowego jest identyczna z kreatorem tworzenia obiektu pomocniczego, z tą różnicą, że kreator tworzenia obiektu podstawowego musi wykonać jeszcze kilka kroków.

Zanim pierwsza strona zostanie odrzucona, kreator tworzenia obiektu musi utworzyć tymczasowy obiekt katalogu. W tym celu wywołaj metodę IDsAdminNewObjPrimarySite::CreateNew. Wskaźnik do interfejsu IDsAdminNewObjPrimarySite jest uzyskiwany przez wywołanie QueryInterface z IID_IDsAdminNewObjPrimarySite na interfejsie IDsAdminNewObj, który jest przekazywany do IDsAdminNewObjExt::Initialize. Metoda CreateNew tworzy nowy obiekt tymczasowy i wywołuje IDsAdminNewObjExt::SetObject dla każdego rozszerzenia.

Gdy kreator tworzenia obiektu zawiera więcej niż jedną stronę, system implementuje stronę "Zakończ", która wyświetla podsumowanie informacji o obiekcie do zapisania. Po kliknięciu przycisku Zakończ na stronie "Zakończ", system wywoła metodę IDsAdminNewObjExt::WriteData dla każdego identyfikatora rozszerzenia tworzenia obiektu, a następnie zatwierdzi obiekt tymczasowy do pamięci trwałej. Jeśli jednak kreator tworzenia obiektu zawiera tylko jedną stronę, to strona będzie mieć przyciski OK i Anuluj zamiast przycisków Wstecz, Dalej i Anuluj, które zwykle występują w kreatorze, i nie zostanie podana strona „Zakończ”. W związku z tym kreator tworzenia obiektów jednostronicowych musi wywołać IDsAdminNewObjPrimarySite::Commit, aby wykonać operacje zapisu i zapisania. Jednostronicowe rozszerzenie tworzenia obiektu podstawowego powinno wywołać Commit w odpowiedzi na powiadomienie PSN_WIZFINISH.

Ponieważ inne rozszerzenia tworzenia obiektów mogą dodawać strony do kreatora, rozszerzenie tworzenia obiektu podstawowego może nie wiedzieć, czy w kreatorze znajduje się więcej niż jedna strona. Nie jest to problem z dwóch powodów: po pierwsze, jeśli system implementuje stronę "Zakończ", rozszerzenie tworzenia obiektu podstawowego otrzyma powiadomienie PSN_WIZNEXT zamiast powiadomienia PSN_WIZNEXT. Po drugie, zatwierdzenie nie zaszkodzi, jeśli kreator zawiera więcej niż jedną stronę.