IABLogon::OpenTemplateID
Aplica-se a: Outlook 2013 | Outlook 2016
Abre uma entrada de destinatário que tem dados residentes em um provedor de catálogo de endereços de host.
HRESULT OpenTemplateID(
ULONG cbTemplateID,
LPENTRYID lpTemplateID,
ULONG ulTemplateFlags,
LPMAPIPROP lpMAPIPropData,
LPCIID lpInterface,
LPMAPIPROP FAR * lppMAPIPropNew,
LPMAPIPROP lpMAPIPropSibling
);
Parâmetros
cbTemplateID
[in] A contagem de bytes no identificador de modelo apontado pelo parâmetro lpTemplateID .
lpTemplateID
[in] Um ponteiro para o identificador de modelo ou a propriedade PR_TEMPLATEID (PidTagTemplateid) da entrada do destinatário a ser aberta.
ulTemplateFlags
[in] Um bitmask de sinalizadores usado para indicar como abrir a entrada representada pelo identificador de modelo. O seguinte sinalizador pode ser definido:
FILL_ENTRY
O provedor de host está criando uma nova entrada em seu contêiner com base na entrada representada pelo identificador de modelo. O método IABLogon::OpenTemplateID deve executar inicialização específica da entrada do provedor host usando a implementação IMAPIProp : IUnknown no parâmetro lpMAPIPropData ou retornar uma implementação de interface IMAPIProp personalizada no parâmetro lppMAPIPropNew .
lpMAPIPropData
[in] Um ponteiro para o objeto de propriedade do provedor host e a implementação de uma interface derivada de IMAPIProp.
lpInterface
[in] Um ponteiro para o IID (identificador de interface) que representa o tipo de ponteiro de interface a ser retornado no parâmetro lppMAPIPropNew . Passar nulo retorna a interface do usuário de mensagens padrão, IMailUser : IMAPIProp.
lppMAPIPropNew
[out] Um ponteiro para o objeto de propriedade vinculado e uma implementação de uma interface derivada do IMAPIProp.
lpMAPIPropSibling
[out] Reservados; deve ser nulo.
Valor de retorno
S_OK
O código apropriado foi associado com êxito a dados relacionados no provedor de host.
MAPI_E_NO_SUPPORT
O objeto não dá suporte a IDs de modelo.
MAPI_E_UNKNOWN_ENTRYID
O identificador de modelo passado no parâmetro lpTemplateID não é reconhecido pelo provedor do catálogo de endereços.
Comentários
O método IABLogon::OpenTemplateID é implementado apenas por provedores de catálogo de endereços que precisam manter o controle sobre cópias de suas entradas localizadas nos contêineres de provedores host. Os provedores que implementam o OpenTemplateID são conhecidos como provedores de catálogo de endereços estrangeiros. Os provedores de host chamam IMAPISupport::OpenTemplateID para criar uma entrada copiada ou abrir a entrada copiada e MAPI passa a chamada para IABLogon::OpenTemplateID. IABLogon::OpenTemplateID abre a entrada e associa o código que o controla aos dados no provedor de host.
Em vez de usar um identificador de entrada, iABLogon::OpenTemplateID usa outra propriedade, o identificador de modelo da entrada, PR_TEMPLATEID. Os identificadores de modelo devem ter suporte para entradas cujo código deve estar vinculado a dados em um provedor de host.
Alguns exemplos de quando um provedor de catálogo de endereços deve implementar iABLogon::OpenTemplateID são os seguintes:
Para atualizar periodicamente os dados de uma entrada copiada para que ele permaneça sincronizado com o original.
Para implementar a funcionalidade que o provedor host não pode implementar, como preencher dinamicamente uma lista que aparece na tabela de detalhes da entrada a partir de dados em um servidor.
Para controlar a interação entre propriedades na entrada do provedor host e a entrada original, como calcular o PR_EMAIL_ADDRESS (PidTagEmailAddress) dos valores dos controles de edição na exibição de detalhes que contêm diferentes componentes do endereço.
Observações para implementadores
Quando um provedor de host copia ou cria uma entrada do provedor e você fornece uma implementação de objeto de propriedade por meio de IABLogon::OpenTemplateID, você lida com a maioria das chamadas para manter a entrada. No entanto, como cabe ao provedor host encaminhar essas chamadas para você, o provedor host pode interceptar qualquer chamada e executar o processamento personalizado antes de encaminhar a chamada.
Você deve usar as seguintes diretrizes em suas implementações de objeto de propriedade:
Quando IMAPIProp::GetProps for chamado, determine se a solicitação é para uma propriedade computada e, se for, manipule-a. Transfira todas as solicitações de propriedades não compatíveis para o provedor de host.
Quando IMAPIProp::OpenProperty é chamado para abrir qualquer tabela, exceto a tabela de exibição de detalhes, manipule a solicitação. A maioria das tabelas não pode ser copiada com precisão para o provedor de host. Você deve gerar a implementação IMAPITable para essas tabelas solicitadas. A propriedade PR_DETAILS_TABLE de tabela de detalhes (PidTagDetailsTable) deve ser copiada para o provedor de host. Isso permite que esse provedor gere a tabela localmente. Talvez você queira concluir a implementação da tabela de exibição para gerar notificações de tabela de exibição.
Quando IMAPIProp::SetProps é chamado, o provedor host pode validar os dados antes de permitir que você defina as propriedades. Você pode verificar se todas as propriedades necessárias foram definidas ou calculadas. Se um erro for detectado, retorne o valor de erro apropriado e, se puder, qualquer explicação adicional por meio de IMAPIProp::GetLastError.
Quando IMAPIProp::SaveChanges é chamado, o provedor host pode querer executar o processamento antes de salvar a entrada. Você deve salvar todos os dados afetados pelas propriedades alteradas, como um novo endereço, na entrada do provedor de host.
Em geral, faça com que a implementação da entrada que você repasse ao provedor host intercepte todos os métodos para executar a manipulação específica do contexto das propriedades relevantes. Se o sinalizador FILL_ENTRY for passado no parâmetro ulTemplateFlags , defina todas as propriedades para a entrada.
Se você retornar um novo objeto de propriedade no parâmetro lppMAPIPropNew , chame o método IUnknown::AddRef do objeto de propriedade do provedor host para manter uma referência. Todas as chamadas por meio do objeto vinculado que a implementação IMAPIProp retornada em lppMAPIPropNew devem ser roteadas para o método correspondente no objeto de propriedade host depois de serem tratadas pelo objeto vinculado.
Os identificadores de propriedade de quaisquer propriedades nomeadas que são passadas pelo objeto de propriedade vinculado estão no namespace do identificador do provedor. Sua implementação do método IMAPIProp::GetNamesFromIDs deve determinar os nomes das propriedades para que ela possa executar quaisquer tarefas específicas do modelo. Da mesma forma, as propriedades que seu provedor passa para o provedor de host também devem estar em seu namespace. Por exemplo, se você definir uma propriedade nomeada no OpenTemplateID, deverá usar um de seus identificadores para o nome, criando-a, se necessário, chamando o método IMAPIProp::GetIDsFromNames .
Se você não reconhecer o identificador de entrada passado em lpTemplateID, retorne MAPI_E_UNKNOWN_ENTRYID.
Para obter mais informações sobre como trabalhar com identificadores de modelo de catálogo de endereços, consulte Agindo como um provedor de catálogo de endereços estrangeiro.