IABContainer::ResolveNames
Aplica-se a: Outlook 2013 | Outlook 2016
Executa a resolução de nomes para uma ou mais entradas de destinatário.
HRESULT ResolveNames(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags,
LPADRLIST lpAdrList,
LPFlagList lpFlagList
);
Parâmetros
Lpproptagarray
[in] Um ponteiro para uma estrutura SPropTagArray que contém uma matriz de marcas de propriedade que descrevem as propriedades a serem incluídas na estrutura ADRLIST retornada pelo provedor. Para solicitar o conjunto padrão de propriedades do provedor, passe NULL no parâmetro lpPropTagArray .
ulFlags
[in] Um bitmask de sinalizadores que controla o tipo do texto nas cadeias de caracteres retornadas. Os seguintes sinalizadores podem ser definidos:
EMS_AB_ADDRESS_LOOKUP
Somente serão encontradas correspondências exatas de endereço proxy; as correspondências parciais são ignoradas. Esse sinalizador tem suporte apenas pelo Provedor de Catálogo de Endereços do Exchange.
MAPI_CACHE_ONLY
Somente o catálogo de endereços offline será usado 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 nesse 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.
MAPI_UNICODE
As propriedades de cadeia de caracteres retornadas estão no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, as cadeias de caracteres estarão no formato ANSI.
lpAdrList
[in, out] Na entrada, um ponteiro para uma estrutura ADRLIST que contém a lista de destinatários a serem resolvidos. Na saída, um ponteiro para uma estrutura ADRLIST que contém os nomes resolvidos.
lpFlagList
[in, out] Um ponteiro para uma matriz de sinalizadores, cada sinalizador correspondente a uma estrutura ADRENTRY no parâmetro lpAdrList, que fornece o status da operação de resolução de nomes para o destinatário. Os sinalizadores no parâmetro lpFlagList estão na mesma ordem que as entradas em lpAdrList. Os seguintes sinalizadores podem ser definidos:
MAPI_AMBIGUOUS
O destinatário correspondente foi resolvido, mas não para um identificador de entrada exclusivo. Outros contêineres não devem tentar resolve esse destinatário.
MAPI_RESOLVED
O destinatário correspondente foi resolvido para um identificador de entrada exclusivo. Outros contêineres não devem tentar resolve esse destinatário.
MAPI_UNRESOLVED
A entrada correspondente não foi resolvida. Outros contêineres devem tentar resolve esse destinatário.
Valor de retorno
S_OK
O processo de resolução de nomes foi bem-sucedido.
MAPI_E_BAD_CHARWIDTH
O sinalizador MAPI_UNICODE foi definido e a implementação não dá suporte ao Unicode ou MAPI_UNICODE não foi definido e a implementação dá suporte apenas ao Unicode.
MAPI_E_NO_SUPPORT
O provedor de catálogo de endereços não dá suporte à resolução de nomes em massa usando esse método.
Comentários
O método ResolveNames tenta corresponder destinatários não resolvidos da matriz de entradas no parâmetro lpAdrList aos destinatários neste contêiner do catálogo de endereços. Um destinatário não resolvido normalmente tem apenas a propriedade PR_DISPLAY_NAME (PidTagDisplayName) e possivelmente algumas outras propriedades. Um destinatário não resolvido não tem a propriedade PR_ENTRYID (PidTagEntryId) e seu sinalizador correspondente no parâmetro lpFlagList está definido como MAPI_UNRESOLVED. Por outro lado, um destinatário resolvido sempre tem pelo menos a propriedade PR_ENTRYID mais várias outras propriedades, como PR_EMAIL_ADDRESS (PidTagEmailAddress), PR_DISPLAY_NAME e PR_ADDRTYPE (PidTagAddressType).
A resolução de nomes normalmente começa quando um cliente chama o método IAddrBook::ResolveName . O Outlook MAPI responde chamando o método ResolveNames de cada contêiner de catálogo de endereços incluído no caminho de pesquisa do catálogo de endereços, especificado pela propriedade PR_AB_SEARCH_PATH (PidTagAbSearchPath). As entradas no parâmetro lpAdrList incluem destinatários já resolvidos porque estão em contêineres para os quais o MAPI já chamou ResolveNames, pois as entradas aparecem anteriormente no caminho de pesquisa.
Cada contêiner tenta resolve as entradas não resolvidas correspondendo ao nome de exibição do destinatário com o nome de exibição de uma de suas entradas. Quando uma correspondência exclusiva é encontrada, ResolveNames adiciona a propriedade PR_ENTRYID e outras propriedades incluídas no parâmetro lpPropTagArray à entrada correspondente na estrutura ADRLIST de saída. ResolveNames define a entrada no parâmetro lpFlagList como MAPI_RESOLVED. O identificador de entrada armazenado na propriedade PR_ENTRYID pode ser de curto ou longo prazo.
Depois que todos os contêineres no caminho de pesquisa tentarem o processo de resolução de nomes, o MAPI abre uma caixa de diálogo, se possível, para solicitar ajuda ao usuário para resolver quaisquer conflitos restantes.
Os clientes também podem usar a estrutura ADRLIST retornada em chamadas para o método IMessage::ModifiRecipients .
Observações para implementadores
Não é necessário dar suporte à resolução de nomes com o método ResolveNames . Em vez disso, ou, além disso, você pode dar suporte a ele com a restrição de propriedade PR_ANR (PidTagAnr). Se você decidir confiar na restrição de PR_ANR para resolução de nomes, poderá retornar MAPI_E_NO_SUPPORT. Para obter mais informações, confira Implementando a Resolução de Nomes.
Defina a entrada de sinalizador de um destinatário no parâmetro lpFlagList para MAPI_UNRESOLVED se o destinatário não corresponder a nenhum dos destinatários do contêiner.
Quando um destinatário corresponder a vários destinatários, defina seu sinalizador como MAPI_AMBIGUOUS e não altere sua estrutura ADRENTRY .
O MAPI requer determinadas propriedades para destinatários incluídos na lista de destinatários de uma mensagem. Você pode incluí-los na estrutura do ADRENTRY como parte do processo de resolução de nomes ou aguardar que a MAPI as solicite com chamadas para os métodos IAddrBook::P repareRecips e IMAPISupport::ExpandRecips . Você pode eliminar essas chamadas extras e melhorar o desempenho incluindo as seguintes propriedades nas estruturas do ADRENTRY de todos os destinatários resolvidos:
PR_ADDRTYPE
PR_DISPLAY_NAME
PR_EMAIL_ADDRESS
PR_ENTRYID
PR_OBJECT_TYPE (PidTagObjectType)
PR_SEARCH_KEY (PidTagSearchKey)
PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)
Se algumas das propriedades no parâmetro lpPropTagArray não estiverem disponíveis, normalmente porque a entrada do contêiner não dá suporte às propriedades e elas não estão incluídas no membro ADRENTRY do destinatário na estrutura ADRLIST , defina o tipo de propriedade de cada propriedade indisponível como PT_ERROR.
Não remova nenhuma propriedade da estrutura ADRENTRY de um destinatário resolvido.
Se você precisar substituir em vez de modificar uma estrutura ADRENTRY , libere a estrutura original do ADRENTRY primeiro chamando a função MAPIFreeBuffer e, em seguida, aloque a estrutura ADRENTRY de substituição por MAPIAllocateBuffer.