Implementazione dell'oggetto COM Object Creation Extension

Un'estensione per la creazione di oggetti è un oggetto COM implementato come server in-proc. Le estensioni per la creazione di oggetti primari e secondari devono implementare l'interfaccia IDsAdminNewObjExt .

Implementazione di IDAdminNewObjExt

Quando viene creata la creazione guidata dell'oggetto, inizializza ogni estensione per la creazione di oggetti chiamando il metodo IDsAdminNewObjExt::Initialize dell'estensione. Il metodo Initialize fornisce all'estensione informazioni sul contenitore in cui viene creato l'oggetto, il nome della classe del nuovo oggetto e le informazioni sulla procedura guidata stessa. Se la creazione guidata dell'oggetto viene avviata per creare un nuovo oggetto da un oggetto esistente, il parametro pADsCopySource non sarà NULL. In questo caso, l'estensione deve tentare di ottenere il maggior numero di dati dall'oggetto copiato come possibile.

Dopo l'inizializzazione dell'estensione, viene chiamato il metodo IDsAdminNewObjExt::AddPages . L'estensione deve aggiungere la pagina o le pagine alla procedura guidata durante questo metodo. Una pagina della procedura guidata viene creata compilando una struttura PROPSHEETPAGE e quindi passando questa struttura alla funzione CreatePropertySheetPage . La pagina viene quindi aggiunta alla procedura guidata chiamando la funzione di callback passata a AddPages nel parametro lpfnAddPage .

Prima che venga visualizzata la pagina dell'estensione, viene chiamato IDsAdminNewObjExt::SetObject . In questo modo viene fornita l'estensione con un puntatore all'interfaccia ID per l'oggetto creato.

Durante la visualizzazione della pagina della procedura guidata, la pagina deve gestire e rispondere a eventuali messaggi di notifica della procedura guidata necessari, ad esempio PSN_SETACTIVE e PSN_WIZNEXT.

Al termine di tutte le pagine della procedura guidata, la procedura guidata visualizzerà una pagina "Fine" che fornisce un riepilogo dei dati immessi. La procedura guidata ottiene questi dati chiamando il metodo IDsAdminNewObjExt::GetSummaryInfo per ognuna delle estensioni. Il metodo GetSummaryInfo fornisce una stringa BSTR contenente i dati di testo visualizzati nella pagina "Finish". Un'estensione per la creazione di oggetti non deve fornire dati di riepilogo. In questo caso, GetSummaryInfo deve restituire E_NOTIMPL. GetSummaryInfo viene chiamato una sola volta per ogni estensione, non per pagina, quindi se l'estensione per la creazione dell'oggetto aggiunge più di una pagina, l'estensione deve combinare i dati di riepilogo in una stringa.

Quando l'utente fa clic sul pulsante Finish nella pagina "Finish", la procedura guidata chiama ognuno dei metodi IDsAdminNewObjExt::WriteData con il contesto di DSA_NEWOBJ_CTX_PRECOMMIT . In questo caso, l'estensione deve scrivere i dati raccolti nelle proprietà appropriate usando il metodo IADs::P ut o IADs::P utEx . L'interfaccia IADs viene fornita all'estensione nel metodo IDsAdminNewObjExt::SetObject . L'estensione non deve eseguire il commit delle proprietà memorizzate nella cache chiamando IADs::SetInfo. Quando tutte le proprietà sono state scritte, l'estensione per la creazione dell'oggetto primario esegue il commit delle modifiche chiamando IADs::SetInfo. Questo argomento è illustrato più dettagliatamente di seguito.

Se si verifica un errore, l'estensione riceverà una notifica dell'errore e durante l'operazione che si è verificata quando viene chiamato il metodo IDsAdminNewObjExt::OnError .

Implementazione di una Creazione guidata oggetto primario

L'implementazione di una creazione guidata di oggetti primario è identica a una creazione guidata di oggetti secondari, ad eccezione del fatto che la creazione guidata di oggetti primari deve eseguire alcuni passaggi aggiuntivi.

Prima di chiudere la prima pagina, la creazione guidata dell'oggetto deve creare l'oggetto directory temporaneo. A tale scopo, chiamare il metodo IDsAdminNewObjPrimarySite::CreateNew . Un puntatore all'interfaccia IDsAdminNewObjPrimarySite viene ottenuto chiamando QueryInterface con IID_IDsAdminNewObjPrimarySite nell'interfaccia IDsAdminNewObj passata a IDsAdminNewObjExt::Initialize. Il metodo CreateNew crea un nuovo oggetto temporaneo e chiama IDsAdminNewObjExt::SetObject per ogni estensione.

Quando una creazione guidata di oggetti contiene più pagine, il sistema implementa una pagina "Fine" che visualizza un riepilogo delle informazioni sull'oggetto da salvare. Quando si fa clic sul pulsante Fine nella pagina "Fine", il sistema chiamerà ogni ID dell'estensione di creazione dell'oggettoAdminNewObjExt ::WriteData e quindi eseguirà il commit dell'oggetto temporaneo nella memoria persistente. Se, tuttavia, la creazione guidata oggetti contiene solo una pagina, la pagina avrà i pulsanti OK e Annulla anziché i pulsanti Indietro, Avanti e Annulla normalmente presenti in una procedura guidata e non viene fornita alcuna pagina "Fine". Per questo motivo, una procedura guidata per la creazione di oggetti a pagina singola deve chiamare IDsAdminNewObjPrimarySite::Commit per eseguire le operazioni di scrittura e salvataggio. Un'estensione per la creazione di oggetti primari a pagina singola deve chiamare Commit in risposta alla notifica di PSN_WIZFINISH .

Poiché altre estensioni per la creazione di oggetti possono aggiungere pagine alla procedura guidata, l'estensione per la creazione di oggetti primario potrebbe non sapere se è presente più di una pagina nella procedura guidata. Questo non è un problema per due motivi: innanzitutto, se il sistema implementa la pagina "Fine", l'estensione per la creazione dell'oggetto primario riceverà la notifica PSN_WIZNEXT anziché la notifica di PSN_WIZNEXT . In secondo luogo, commit avrà esito negativo in modo innocuo se la procedura guidata contiene più di una pagina.