Compartilhar via

Atuar como um provedor de catálogo de endereços estrangeiro

  • Artigo

Aplica-se a: Outlook 2013 | Outlook 2016

Um provedor estrangeiro é um provedor de catálogo de endereços que:

  • Atribui identificadores de modelo para seus destinatários.
  • Dá suporte ao método IABLogon::OpenTemplateID .
  • Fornece código para manter destinatários que existem nos contêineres de outros provedores de catálogo de endereços conhecidos como provedores de host. Esse código envolve um objeto de propriedade, normalmente uma implementação de interface IMAPIProp , que envolve um objeto de propriedade do provedor de host.

Atuar como um provedor estrangeiro é uma função opcional; nem todos os provedores precisam dar suporte a identificadores de modelo e seu código relacionado. Implemente seu provedor como um provedor estrangeiro se você quiser manter o controle sobre os destinatários que os provedores de host criam usando modelos fornecidos pelo seu provedor.

O formato que seu provedor usa para seus identificadores de entrada também pode ser usado para seus identificadores de modelo. Os identificadores de modelo devem incluir o MAPIUID registrado do provedor para permitir que o MAPI vincule os destinatários com êxito aos provedores apropriados.

O MAPI chama o método IABLogon::OpenTemplateID do provedor quando um provedor de host chama IMAPISupport::OpenTemplateID. O provedor de host passa o identificador de modelo do destinatário no parâmetro lpTemplateID em sua chamada para IMAPISupport::OpenTemplateID. O MAPI determina que o identificador de modelo pertence ao seu provedor, correspondendo o MAPIUID no identificador de modelo com o MAPIUID que seu provedor registrou em tempo de logon. MAPI encaminha a chamada do provedor de host para seu provedor por meio do método IABLogon::OpenTemplateID .

O provedor de host também passa um ponteiro para sua implementação de objeto de propriedade para o destinatário no parâmetro lpMAPIPropData , um identificador de interface no parâmetro lpInterface que corresponde ao tipo de implementação de interface passada em lpMAPIPropData e um sinalizador opcional, FILL_ENTRY. Espera-se que seu provedor retorne no parâmetro lppMAPIPropNew um ponteiro para uma implementação de objeto de propriedade do tipo especificado em lpInterface. O ponteiro retornado pode ser para o objeto de propriedade encapsulado implementado pelo provedor ou para o objeto fornecido pelo provedor de host em lpMAPIPropData. Seu provedor deve retornar um ponteiro de objeto de propriedade encapsulado quando:

  • A tabela de exibição do destinatário contém controles de caixa de listagem.
  • O endereço de email do destinatário deve ser montado a partir de dados em vários controles de tabela de exibição.
  • Seus problemas de provedor exibem notificações de tabela.

O sinalizador FILL_ENTRY indica ao provedor que o provedor host exige que todas as propriedades do destinatário sejam atualizadas. Seu provedor é necessário para atender a essa solicitação.

Quando um provedor de host chama o método OpenTemplateID do provedor, seu provedor pode:

  • Atualize periodicamente os dados de uma entrada copiada.
  • Mantenha uma entrada copiada sincronizada com o original, como quando uma entrada de catálogo de endereços é copiada para o catálogo de endereços pessoal.
  • Implemente a funcionalidade que não pode ser implementada pelo provedor host, como preencher dinamicamente caixas de lista na tabela de detalhes da entrada copiada a partir de dados em um servidor.
  • Controle a interação entre propriedades em uma entrada copiada ou modelo instanciado. Por exemplo, PR_EMAIL_ADDRESS de computação de outras propriedades exibidas na tabela de detalhes.

Os dois primeiros itens são exemplos de tarefas que não exigem que seu provedor forneça um objeto de propriedade encapsulado – uma implementação do IMAPIProp baseada na implementação do provedor host. Seu provedor pode simplesmente atualizar as propriedades conforme necessário e retornar, definindo o parâmetro lppMAPIPropNew para apontar para o ponteiro passado pelo provedor host no parâmetro lpMAPIPropData .

As duas segundas tarefas exigem que seu provedor retorne ao provedor de host um objeto de propriedade que envolve o objeto do provedor de host com funcionalidade adicional, como a capacidade de exibir uma folha de propriedades para a entrada. Esse objeto de propriedade será um usuário de mensagens ou uma lista de distribuição, dependendo do tipo de objeto passado pelo provedor de host no parâmetro lpMAPIPropData e indicado pelo identificador de interface no parâmetro lpInterface . Se o parâmetro lpMAPIPropData apontar para um usuário de mensagens, o objeto de propriedade encapsulado do provedor deve ser uma implementação do IMailUser . Se lpMAPIPropData apontar para uma lista de distribuição, ela deverá ser uma implementação IDistList .

O objeto de propriedade encapsulado do provedor intercepta chamadas de método IMAPIProp para executar a manipulação específica do contexto do destinatário do provedor de host, o objeto que ele está encapsulando. O MAPI só tem um requisito para objetos de propriedade encapsulados: todas as chamadas para IMAPIProp::OpenProperty solicitando a propriedade PR_DETAILS_TABLE (PidTagDetailsTable) devem ser passadas para o provedor de host. A implementação do provedor pode usar a tabela retornada para interceptar notificações de tabela de exibição ou para adicionar as próprias, se necessário.

A lista a seguir inclui tarefas que normalmente são implementadas no objeto de propriedade encapsulada implementado por provedores estrangeiros:

  • Valores de propriedade de pré-processamento e pós-processamento para o destinatário do host em IMAPIProp::GetProps.
  • O tratamento de detalhes exibe controles de tabela, como botões e caixas de lista, em IMAPIProp::OpenProperty.
  • Validar ou manipular valores de propriedade para o destinatário do host em IMAPIProp::SetProps.
  • Calcular propriedades necessárias, como PR_EMAIL_ADDRESS e verificar se todas as propriedades necessárias foram definidas antes de salvar o destinatário do host em IMAPIProp::SaveChanges.

Para implementar iABLogon::OpenTemplateID

  1. Verifique se o identificador de modelo passado com o parâmetro lpTemplateID é válido e está em um formato que seu provedor reconhece. Se não for, falhe e retorne MAPI_E_INVALID_ENTRYID.

  2. Crie um objeto do tipo indicado pelo identificador de modelo, um usuário de mensagens, uma lista de distribuição ou um destinatário único.

  3. Chame o método IUnknown::AddRef no objeto de propriedade do provedor de host, que é o objeto apontado pelo parâmetro lpMAPIPropData .

  4. Se o parâmetro ulTemplateFlags estiver definido como FILL_ENTRY:

    1. Se o novo objeto for um usuário de mensagens ou uma lista de distribuição:

      1. Recupere todas as propriedades do novo objeto, possivelmente chamando seu método IMAPIProp::GetProps .

      2. Chame o método IMAPIProp::SetProps do provedor de host para copiar todas as propriedades recuperadas para o objeto de propriedade do provedor de host.

    2. Se o novo objeto for um destinatário único, chame o método IMAPIProp::SetProps do provedor de host para definir as seguintes propriedades:

      • PR_ADDRTYPE (PidTagAddressType) para o tipo de endereço manipulado pelo provedor.

      • PR_TEMPLATEID (PidTagTemplateid) para o identificador de modelo dos parâmetros lpTemplateID e cbTemplateID .

      • PR_DISPLAY_TYPE (PidTagDisplayType) para DT_MAILUSER ou DT_DISTLIST, conforme apropriado.

  5. Defina o conteúdo do parâmetro lppMAPIPropNew para apontar para o novo objeto do provedor ou o objeto de propriedade passado com o parâmetro lpMAPIPropData , dependendo se o provedor determinar se um objeto encapsulado é necessário.

  6. Se ocorrer um erro crítico, como uma falha de rede ou uma condição fora da memória, retorne o valor de erro apropriado. Esse valor deve ser propagado para o cliente com a estrutura MAPIERROR apropriada, uma tarefa executada pelo provedor de host.