IABContainer::CreateEntry
Aplica-se a: Outlook 2013 | Outlook 2016
Cria uma nova entrada, que pode ser um usuário de mensagens, uma lista de distribuição ou outro contêiner.
HRESULT CreateEntry(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulCreateFlags,
LPMAPIPROP FAR * lppMAPIPropEntry
);
Parâmetros
cbEntryID
[in] A contagem dos bytes no identificador de entrada apontado pelo parâmetro lpEntryID .
Lpentryid
[in] Um ponteiro para o identificador de entrada de um modelo para criar novas entradas de um tipo específico.
ulCreateFlags
[in] Um bitmask de sinalizadores que controla como a criação de entrada é executada. Os seguintes sinalizadores podem ser definidos:
CREATE_CHECK_DUP_LOOSE
Um nível frouxo de verificação de entrada duplicada deve ser executado. A implementação da verificação de entrada duplicada frouxa é específica do provedor. Por exemplo, um provedor pode definir uma correspondência solta como qualquer duas entradas que tenham o mesmo nome de exibição.
CREATE_CHECK_DUP_STRICT
Um nível estrito de verificação de entrada duplicada deve ser executado. A implementação da verificação de entrada duplicada estrita é específica do provedor. Por exemplo, um provedor pode definir uma correspondência estrita como qualquer duas entradas que tenham o mesmo nome de exibição e endereço de mensagens.
CREATE_REPLACE
Uma nova entrada deve substituir uma existente se for determinado que os dois são duplicados.
lppMAPIPropEntry
[out] Um ponteiro para um ponteiro para a entrada recém-criada.
Valor de retorno
S_OK
A nova entrada foi criada com êxito.
Comentários
O método IABContainer::CreateEntry cria uma nova entrada de um tipo específico no contêiner especificado, retornando um ponteiro para uma implementação de interface para obter mais acesso à entrada. A nova entrada é criada usando um modelo que foi selecionado na lista de modelos disponíveis do contêiner publicados em sua tabela única. Os chamadores acessam a tabela única de um contêiner chamando seu método IMAPIProp::OpenProperty e solicitando a propriedade PR_CREATE_TEMPLATES (PidTagCreateTemplates).
Observações para implementadores
Todos os contêineres compatíveis com o método IABContainer::CreateEntry devem ser modificáveis. Defina o sinalizador de AB_MODIFIABLE do contêiner em sua propriedade PR_CONTAINER_FLAGS (PidTagContainerFlags) para indicar que ele é modificável.
Você deve dar suporte a todos os sinalizadores ulCreateFlags . No entanto, a interpretação e o uso desses sinalizadores são específicos da implementação, ou seja, você pode determinar o que a semântica de CREATE_CHECK_DUP_LOOSE e CREATE_CHECK_DUP_STRICT significam no contexto de sua implementação. Se você não puder ou não determinar se uma entrada é duplicada, sempre permita que a entrada seja criada.
Alguns provedores implementam uma verificação de entrada estrita correspondendo ao nome de exibição, ao endereço de mensagens e à chave de pesquisa em uma entrada; outros provedores limitam a correspondência para exibir nome e endereço. A verificação de entrada solta geralmente é implementada verificando apenas o nome de exibição.
Notas aos Implementadores do Provedor de Catálogo de Endereços de Host
Se o contêiner puder criar entradas a partir dos modelos de outros provedores, sua implementação do CreateEntry deverá fornecer armazenamento para algumas ou todas as propriedades associadas às entradas criadas. Por exemplo, se você fornecer armazenamento para a propriedade PR_DETAILS_TABLE (PidTagDetailsTable) de uma entrada, poderá gerar sua caixa de diálogo de detalhes sem precisar depender do provedor estrangeiro.
Se o contêiner puder criar entradas que dão suporte à propriedade PR_TEMPLATEID (PidTagTemplateid), sua implementação do CreateEntry deverá fazer o seguinte:
Chame o método IMAPISupport::OpenTemplateID . OpenTemplateID permite que o código do provedor estrangeiro para a entrada se associe à nova entrada que está sendo criada. Provedores estrangeiros dão suporte a esse processo de associação para manter o controle sobre as entradas criadas de seus modelos nos contêineres de provedores de catálogo de endereços de host.
Execute qualquer inicialização necessária e preencha o novo objeto com todas as propriedades da entrada no provedor estrangeiro que o objeto retornou no parâmetro lppMAPIPropNew do OpenTemplateID.
Se OpenTemplateID for bem-sucedido, copie as propriedades para a implementação apontada pelo parâmetro lppMAPIPropNew em vez de diretamente para a implementação apontada pelo parâmetro lpMAPIPropData . Inicialize a nova entrada para uso offline como faria com qualquer outra entrada de um provedor estrangeiro.
Se OpenTemplateID retornar um erro, CreateEntry deverá falhar. Não permita que a entrada seja criada. Como o provedor estrangeiro pode fazer suposições sobre os dados em seu provedor, não crie uma entrada com um identificador de modelo que não tenha sido associado com êxito ao provedor estrangeiro.
Notas para chamadores
Quando CreateEntry retornar, você poderá ou não ser capaz de acessar imediatamente o identificador de entrada da nova entrada. Alguns provedores de catálogo de endereços não o disponibilizam até que você tenha chamado o método IMAPIProp::SaveChanges da nova entrada.
Embora sinalizadores de verificação duplicados sejam passados como parâmetros para CreateEntry, a operação de verificação duplicada não ocorre até que SaveChanges seja chamado. Portanto, erros relacionados, como MAPI_E_COLLISION, que indica que foi feita uma tentativa de criar uma entrada já existente, são retornados pelo SaveChanges em vez de CreateEntry.