Compartilhar via

IABLogon::PrepareRecips

  • Artigo

Aplica-se a: Outlook 2013 | Outlook 2016

Prepara uma lista de destinatários para uso posterior pelo sistema de mensagens.

HRESULT PrepareRecips(
  ULONG ulFlags,
  LPSPropTagArray lpPropTagArray,
  LPADRLIST lpRecipList
);

Parâmetros

ulFlags

[in] Um bitmask de sinalizadores que controla o tipo do texto nas cadeias de caracteres retornadas. O seguinte sinalizador pode ser definido:

  • MAPI_CACHE_ONLY: use apenas o catálogo de endereços offline para executar a resolução de nomes. Por exemplo, você pode usar esse sinalizador para permitir que um aplicativo cliente abra a GAL (lista de endereços global) no modo de troca armazenado em cache e acesse uma entrada no catálogo de endereços do cache sem criar tráfego entre o cliente e o servidor. Esse sinalizador tem suporte apenas pelo Provedor de Catálogo de Endereços do Exchange.

Lpproptagarray

[in] Um ponteiro para uma estrutura SPropTagArray que contém uma matriz de marcas de propriedade que indicam as propriedades que exigem atualização, se houver. O parâmetro lpPropTagArray pode ser NULL.

lpRecipList

[in] Um ponteiro para uma estrutura ADRLIST que contém a lista de destinatários.

Valor de retorno

S_OK

A lista de destinatários foi preparada com êxito.

MAPI_E_NOT_FOUND

Um ou mais dos destinatários no parâmetro lpRecipList não existem.

Um cliente chama o método MAPI IAddrBook::P repareRecips para modificar ou reorganizar um conjunto de propriedades para um ou mais destinatários. Os destinatários podem ou não fazer parte da lista de destinatários de uma mensagem de saída. O MAPI transfere essa chamada para o método IABLogon::P repareRecips de um provedor de catálogo de endereços.

IABLogon::P repareRecips executa quatro tarefas main:

  • Garante que todos os destinatários na lista de endereços apontados pelo parâmetro lpRecipList tenham um identificador de entrada de longo prazo.

  • Garante que todos os destinatários tenham as propriedades especificadas na matriz de valor da propriedade apontada pelo parâmetro lpPropTagArray .

  • Garante que as propriedades da matriz de valor da propriedade sejam exibidas antes de qualquer outra propriedade que existisse antes da chamada.

  • Garante que a ordem das propriedades na estrutura ADRENTRY de cada destinatário na estrutura ADRLIST seja a mesma da matriz de valor da propriedade.

A estrutura ADRENTRY no parâmetro lpRecipList contém uma estrutura ADRENTRY para cada destinatário. Cada estrutura do ADRENTRY contém uma matriz de estruturas SPropValue para descrever as propriedades do destinatário. Quando IABLogon::P repareRecips retorna, a matriz de estrutura SPropValue para cada destinatário inclui as propriedades do lpPropTagArray seguidas pelas outras propriedades para o destinatário.

Observações para implementadores

Implementar o IABLogon::P repareRecips envolve colocar propriedades em uma ordem específica, recuperar valores de propriedade e converter identificadores de entrada de curto prazo em identificadores de entrada de longo prazo. As propriedades solicitadas no parâmetro lpPropTagArray devem estar no início da matriz de valor da propriedade associada à estrutura ADRENTRY de cada destinatário no parâmetro lpRecipList . Se os valores dessas propriedades não existirem, abra a lista de usuários ou distribuição de mensagens associados usando seu identificador de entrada e recupere os valores de propriedade ausentes.

Alocar cada estrutura SPropValue passada em lpRecipList separadamente para que as estruturas possam ser liberadas individualmente. Se você precisar alocar espaço adicional para qualquer estrutura SPropValue , por exemplo, para armazenar os dados de uma propriedade de cadeia de caracteres, use a função MAPIAllocateBuffer para alocar espaço adicional para a matriz de valor de propriedade completa. Use a função MAPIFreeBuffer para liberar a matriz de valor da propriedade original e use a função MAPIAllocateMore para alocar qualquer memória adicional necessária.

Para implementar o IABLogon::P repareRecips, use o seguinte procedimento:

  1. Verifique se há entradas no parâmetro lpPropTagArray . Se a matriz de valor da propriedade estiver vazia, não haverá trabalho a ser feito. Retornar um valor de sucesso.

  2. Processe cada destinatário no parâmetro lpRecipList . Há um membro da estrutura ADRENTRY para cada destinatário na lista. Ignore os seguintes tipos de destinatários:

    • Destinatários sem um identificador de entrada no membro rgPropVals de sua estrutura ADRENTRY (ou seja, destinatários não resolvidos).

    • Destinatários com um identificador de entrada que não pertence ao seu provedor. Esses destinatários serão passados para outro provedor de catálogo de endereços.

  3. Abra o destinatário e recupere as propriedades que já estão definidas para o destinatário.

  4. Mesclar a matriz de valor da propriedade especificada no lpRecipList com a matriz de propriedades retornadas de GetProps. Se a mesma propriedade ocorrer em ambas as matrizes de propriedade, use o valor de lpRecipList.

  5. Se a matriz de valor da propriedade lpRecipList for grande o suficiente para manter todas as propriedades necessárias, basta substituí-la pela matriz mesclada. Se a matriz de valor da propriedade lpRecipList não for grande o suficiente, substitua-a por uma matriz recém-alocada. Certifique-se de que a nova matriz tenha um valor atualizado em cada um de seus membros cValues .

  6. Se você não reconhecer uma ou mais propriedades no parâmetro lpPropTagArray , defina o tipo de propriedade na estrutura ADRENTRY do destinatário como PT_ERROR e o valor da propriedade para MAPI_E_NOT_FOUND ou para outro valor que forneça um motivo mais específico para a indisponibilidade da propriedade. Para obter informações sobre PT_ERROR, consulte Tipos de propriedade.

Observação

Nunca realloque a estrutura ADRLIST que é passada para IABLogon::P repareRecips ou altere seu número de entradas.

Confira também