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 for 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 preenchendo uma estrutura PROPSHEETPAGE e, em seguida, passando essa estrutura para a função CreatePropertySheetPage. A página é adicionada ao assistente chamando a função de retorno de chamada que é passada para AddPages no parâmetro lpfnAddPage .

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

Enquanto a página do assistente é exibida, a página deve manipular e responder a quaisquer mensagens de notificação do assistente necessárias, 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 método IDsAdminNewObjExt::GetSummaryInfo para cada uma das extensões. O GetSummaryInfo método fornece um BSTR que contém os dados de texto exibidos na página "Concluir". 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 usuário 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::P ut ou IADs::P utEx . A interface IADs é 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 em mais detalhes abaixo.

Se ocorrer um erro, a extensão será notificada do erro e durante qual operação ele ocorreu quando o método IDsAdminNewObjExt::OnError for 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 da 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 método IDsAdminNewObjPrimarySite::CreateNew. Um ponteiro para a interface IDsAdminNewObjPrimarySite é obtido 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 o botão Concluir na página "Concluir" for clicado, o sistema chamará cada um dos IDs da extensão de criação de objeto do método AdminNewObjExt::WriteData e, em seguida, confirmará o objeto temporário na memória persistente. Se, no entanto, o assistente de criação de objeto contiver apenas uma página, a página terá os botões OK e Cancelar em vez dos botões Voltar, Avançar e Cancelar 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 de criação de objeto primário de página única deve chamar 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 de PSN_WIZNEXT . Em segundo lugar, a confirmação falhará inofensivamente se o assistente contiver mais de uma página.