IAddrBook::ResolveName
Aplica-se a: Outlook 2013 | Outlook 2016
Executa a resolução de nomes, atribuindo identificadores de entrada a destinatários em uma lista de destinatários.
HRESULT ResolveName(
ULONG_PTR ulUIParam,
ULONG ulFlags,
LPSTR lpszNewEntryTitle,
LPADRLIST lpAdrList
);
Parâmetros
ulUIParam
[in] Um identificador para a janela pai de uma caixa de diálogo que é mostrada, se especificada, para solicitar que o usuário resolve ambiguidade.
ulFlags
[in] Um bitmask de sinalizadores que controlam vários aspectos do processo de resolução. Os seguintes sinalizadores podem ser definidos:
AB_UNICODEUI
Indica que lpszNewEntryTitle é uma cadeia de caracteres UNICODE.
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.
MAPI_DIALOG
Exibe uma caixa de diálogo para solicitar ao usuário informações adicionais de resolução de nomes. Se esse sinalizador não estiver definido, nenhuma caixa de diálogo será exibida.
MAPI_UNICODE
Indica que as propriedades retornadas na lista de endereços devem ser do tipo PT_UNICODE em vez de PT_STRING8.
lpszNewEntryTitle
[in] Um ponteiro para enviar um texto para o título do controle na caixa de diálogo que solicita que o usuário insira um destinatário. O título varia dependendo do tipo de destinatário. O parâmetro lpszNewEntryTitle pode ser NULL.
lpAdrList
[in-out] Um ponteiro para uma estrutura ADRLIST que contém a lista de nomes de destinatário a serem resolvidos. Essa estrutura ADRLIST pode ser criada pelo método IAddrBook::Address .
Valor de retorno
S_OK
O processo de resolução de nomes foi bem-sucedido.
MAPI_E_AMBIGUOUS_RECIP
Pelo menos um destinatário no parâmetro lpAdrList correspondeu a mais de uma entrada no catálogo de endereços. Normalmente, esse valor é retornado quando o sinalizador MAPI_DIALOG é definido, proibindo a exibição de uma caixa de diálogo.
MAPI_E_NOT_FOUND
Pelo menos um destinatário no parâmetro lpAdrList não pode ser resolvido. Normalmente, esse valor é retornado quando o sinalizador MAPI_DIALOG é definido, proibindo a exibição de uma caixa de diálogo.
Comentários
Clientes e provedores de serviços chamam o método ResolveName para iniciar o processo de resolução de nomes. Uma entrada não resolvida é uma entrada que ainda não tem uma propriedade de identificador de entrada ou PR_ENTRYID (PidTagEntryId).
ResolveName passa pelo processo a seguir para cada entrada não resolvida na lista de endereços passada no parâmetro lpAdrList .
Se o tipo de endereço do destinatário aderir ao formato de um endereço SMTP ( displayname@ domain.top-level-domain), ResolveName atribuirá um identificador de entrada único.
Para cada contêiner na propriedade PR_AB_SEARCH_PATH (PidTagAbSearchPath), ResolveName chama o método IABContainer::ResolveNames . ResolveNames tenta corresponder o nome de exibição de cada destinatário não resolvido com um nome de exibição que pertence a uma de suas entradas.
Se um contêiner não for compatível com ResolveNames, ResolveName restringirá a tabela de conteúdo do contêiner usando uma restrição de propriedade de PR_ANR (PidTagAnr). Essa restrição faz com que o contêiner execute um tipo de pesquisa de "melhor palpite" para localizar um destinatário correspondente. Todos os contêineres devem dar suporte à restrição de propriedade PR_ANR .
Quando um contêiner retorna um destinatário que corresponde a vários nomes, ResolveName exibe uma caixa de diálogo se o sinalizador MAPI_DIALOG estiver definido, o que permite que o usuário selecione o nome correto.
Se todos os contêineres da propriedade PR_AB_SEARCH_PATH tiverem sido chamados e nenhuma correspondência tiver sido encontrada, o destinatário permanecerá sem solução.
Se um ou mais destinatários não forem resolvidos, ResolveName retornará MAPI_E_NOT_FOUND. Se um ou mais destinatários tivessem uma resolução ambígua que não pudesse ser resolvida com uma caixa de diálogo ou porque o sinalizador MAPI_DIALOG não foi definido, ResolveName retornará MAPI_E_AMBIGUOUS_RECIP. Quando alguns dos destinatários são ambíguos e alguns não podem ser resolvidos, ResolveName pode retornar qualquer valor de erro.
Se um nome não puder ser resolvido, o cliente poderá criar um endereço único que tenha um identificador de entrada e endereço especialmente formatado. Para obter mais informações sobre o formato de identificadores de entrada únicos, consulte Identificadores de entrada únicos. Para obter mais informações sobre o formato de endereços únicos, confira Endereços únicos.
O MAPI dá suporte a cadeias de caracteres Unicode para o ADRLIST e os novos parâmetros de título de entrada para ResolveName; se você definir o sinalizador MAPI_UNICODE, as seguintes propriedades serão retornadas como PT_UNICODE de tipo nas estruturas do ADRENTRY :
PR_ADDRTYPE (PidTagAddressType)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_EMAIL_ADDRESS (PidTagEmailAddress)
PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)
No entanto, a propriedade PR_7BIT_DISPLAY_NAME (PidTag7BitDisplayName) sempre é retornada como tipo PT_STRING8.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| MAPIABFunctions.cpp |
AddOneOffAddress |
O MFCMAPI usa o método ResolveName para resolve um endereço único antes de adicioná-lo a uma mensagem. |
| MAPIABFunctions.cpp |
AddRecipient |
O MFCMAPI usa o método ResolveName para pesquisar uma entrada do catálogo de endereços por nome de exibição. |