Implementando o objeto COM da extensão de criação de objeto

Uma extensão de criação de objeto é um objeto COM implementado como um servidor in-proc. As extensões de criação de objeto primário e secundário devem implementar a interface IDsAdminNewObjExt.

Implementando IDsAdminNewObjExt

Quando o assistente de criação de objeto é criado, ele inicializa cada extensão de criação de objeto chamando o método IDsAdminNewObjExt::Initialize da extensão. O método Initialize fornece à extensão informações sobre o contêiner no qual o objeto está sendo criado, o nome da classe do novo objeto e informações sobre o próprio assistente. Se o assistente de criação de objeto for iniciado para criar um novo objeto a partir de um objeto existente, o parâmetro pADsCopySource não será NULL. Nesse caso, a extensão deve tentar obter o máximo de dados do objeto que está sendo copiado quanto possível.

Depois que a extensão é inicializada, o método IDsAdminNewObjExt::AddPages é chamado. A extensão deve adicionar a página ou páginas ao assistente durante esse método. Uma página do assistente é criada ao preencher uma estrutura PROPSHEETPAGE e, em seguida, passar essa estrutura para a função CreatePropertySheetPage . A página é então adicionada ao assistente ao chamar a função de retorno de chamada que é passada para o parâmetro lpfnAddPage em AddPages.

Antes de a página de extensão ser exibida, IDsAdminNewObjExt::SetObject é chamado. Isso fornece à extensão um ponteiro de interface IADs para o objeto que está a ser criado.

Enquanto a página do assistente é exibida, a página deve manipular e responder a todas as mensagens de notificação necessárias do assistente, como PSN_SETACTIVE e PSN_WIZNEXT.

Quando o usuário concluir todas as páginas do assistente, o assistente exibirá uma página "Concluir" que fornece um resumo dos dados inseridos. O assistente obtém esses dados chamando o IDsAdminNewObjExt::GetSummaryInfo método para cada uma das extensões. O GetSummaryInfo método fornece um BSTR que contém os dados de texto exibidos na página "Finish". Uma extensão de criação de objeto não precisa fornecer dados de resumo. Nesse caso, GetSummaryInfo deve retornar E_NOTIMPL. GetSummaryInfo é chamado apenas uma vez para cada extensão, não por página, portanto, se a extensão de criação de objeto adicionar mais de uma página, a extensão deverá combinar os dados de resumo em uma cadeia de caracteres.

Quando o utilizador clica no botão Concluir na página "Concluir", o assistente chama cada um dos métodos IDsAdminNewObjExt::WriteData da extensão com o contexto DSA_NEWOBJ_CTX_PRECOMMIT. Quando isso ocorre, a extensão deve gravar os dados coletados nas propriedades apropriadas usando o método IADs::Put ou IADs::PutEx. A IADs interface é fornecida para a extensão no método IDsAdminNewObjExt::SetObject. A extensão não deve confirmar as propriedades armazenadas em cache chamando IADs::SetInfo. Quando todas as propriedades tiverem sido gravadas, a extensão de criação de objeto primário confirmará as alterações chamando IADs::SetInfo. Isso é discutido mais detalhadamente abaixo.

Se ocorrer um erro, a extensão será notificada do erro e durante qual operação ocorreu quando o método IDsAdminNewObjExt::OnError é chamado.

Implementando um Assistente de Criação de Objeto Principal

A implementação de um assistente de criação de objeto primário é idêntica a um assistente de criação de objeto secundário, exceto que um assistente de criação de objeto primário deve executar mais algumas etapas.

Antes de a primeira página ser descartada, o assistente de criação de objeto deve criar o objeto de diretório temporário. Para fazer isso, chame o IDsAdminNewObjPrimarySite::CreateNew método. Um ponteiro para a interface IDsAdminNewObjPrimarySite obtém-se chamando QueryInterface com IID_IDsAdminNewObjPrimarySite na interface IDsAdminNewObj que é passada para IDsAdminNewObjExt::Initialize. O método CreateNew cria um novo objeto temporário e chama IDsAdminNewObjExt::SetObject para cada extensão.

Quando um assistente de criação de objeto contém mais de uma página, o sistema implementa uma página "Concluir" que exibe um resumo das informações do objeto a ser salvo. Quando se clica no botão Concluir na página 'Concluir', o sistema chamará cada método IDsAdminNewObjExt::WriteDatadas extensões de criação de objetoe, em seguida, confirmará o objeto temporário na memória persistente. Se, no entanto, o assistente de criação de objetos contiver apenas uma página, a página terá botões OK e Cancelar em vez dos botões Voltar, Avançar e Cancelar botões normalmente encontrados em um assistente e nenhuma página "Concluir" será fornecida. Por isso, um assistente de extensão de criação de objeto de página única deve chamar IDsAdminNewObjPrimarySite::Commit para executar as operações de gravação e salvamento. Uma extensão para criação de um objeto primário numa página única deve realizar uma chamada para Commit em resposta à notificação PSN_WIZFINISH.

Como outras extensões de criação de objeto podem adicionar páginas ao assistente, a extensão de criação de objeto principal pode não saber se há mais de uma página no assistente. Isso não é um problema por dois motivos: primeiro, se o sistema implementar a página "Concluir", a extensão de criação de objeto principal receberá a notificação de PSN_WIZNEXT em vez da notificação PSN_WIZNEXT. Em segundo lugar, Commit falhará inofensivamente se o assistente contiver mais de uma página.