Função de retorno de chamada MAPIRESOLVENAME (mapi.h)

Artigo
03/05/2024

[O uso dessa função é desencorajado. Ele pode estar alterado ou indisponível nas versões subsequentes do Windows.]

A função MAPIResolveName transforma o nome de um destinatário da mensagem conforme inserido por um usuário em uma entrada de lista de endereços inequívoca.

Sintaxe

MAPIRESOLVENAME Mapiresolvename;

ULONG Mapiresolvename(
  [in]  LHANDLE lhSession,
  [in]  ULONG_PTR ulUIParam,
  [in]  LPSTR lpszName,
  [in]  FLAGS flFlags,
        ULONG ulReserved,
        lpMapiRecipDesc *lppRecip
)
{...}

Parâmetros

[in] lhSession

Identificador que representa uma sessão MAPI simples ou zero. Se o valor do parâmetro lhSession for zero, MAPI faz logon no usuário e cria uma sessão que existe apenas durante a chamada. Essa sessão temporária pode ser uma sessão compartilhada existente ou uma nova. Se necessário, a caixa de diálogo de logon será exibida.

[in] ulUIParam

Identificador de janela pai ou zero, indicando que, se uma caixa de diálogo for exibida, ela será modal do aplicativo. Se o parâmetro ulUIParam contiver um identificador de janela pai, ele será do tipo HWND (convertido em um ULONG_PTR). Se nenhuma caixa de diálogo for exibida durante a chamada, ulUIParam será ignorado.

[in] lpszName

Ponteiro para o nome a ser resolvido.

[in] flFlags

Máscara de bits de sinalizadores de opção. Os sinalizadores a seguir podem ser definidos.

Valor	Significado
MAPI_AB_NOMODIFY	O chamador está solicitando que a caixa de diálogo seja somente leitura, proibindo alterações. MAPIResolveName ignorará esse sinalizador se MAPI_DIALOG não estiver definido.
MAPI_DIALOG	Uma caixa de diálogo deve ser exibida para resolução de nomes. Se esse sinalizador não estiver definido e o nome não puder ser resolvido, MAPIResolveName retornará o valor MAPI_E_AMBIGUOUS_RECIPIENT.
MAPI_LOGON_UI	Uma caixa de diálogo deve ser exibida para solicitar que o usuário faça logon, se necessário. Quando o sinalizador MAPI_LOGON_UI não estiver definido, o aplicativo cliente não exibirá uma caixa de diálogo de logon e retornará um valor de erro se o usuário não estiver conectado.
MAPI_NEW_SESSION	Uma tentativa deve ser feita para criar uma nova sessão em vez de adquirir a sessão compartilhada do ambiente. Se o sinalizador MAPI_NEW_SESSION não estiver definido, MAPIResolveName usará uma sessão compartilhada existente.

ulReserved

Reservados; deve ser zero.

lppRecip

Retornar valor

Essa função retorna um dos valores a seguir.

Código de retorno	Descrição
MAPI_E_AMBIGUOUS_RECIPIENT	O destinatário solicitado não foi ou não pôde ser resolvido para uma entrada de lista de endereços exclusiva.
MAPI_E_UNKNOWN_RECIPIENT	O destinatário não pôde ser resolvido para nenhum endereço. O destinatário pode não existir ou ser desconhecido.
MAPI_E_FAILURE	Ocorreu um ou mais erros não especificados. O nome não foi resolvido.
MAPI_E_INSUFFICIENT_MEMORY	Não havia memória suficiente para continuar. O nome não foi resolvido.
MAPI_E_LOGIN_FAILURE	Não havia nenhum logon padrão e o usuário não conseguiu fazer logon com êxito quando a caixa de diálogo de logon foi exibida. O nome não foi resolvido.
MAPI_E_NOT_SUPPORTED	A operação não era compatível com o sistema de mensagens subjacente.
MAPI_E_USER_ABORT	O usuário cancelou uma das caixas de diálogo. O nome não foi resolvido.
SUCCESS_SUCCESS	A chamada foi bem-sucedida e o nome foi resolvido.

Comentários

A função MAPIResolveName resolve o nome de um destinatário da mensagem (conforme inserido por um usuário) para uma entrada de lista de endereços inequívoca, solicitando opcionalmente que o usuário escolha entre possíveis entradas, se necessário. Uma estrutura de descritor de destinatário que contém informações totalmente resolvidas sobre a entrada é alocada e retornada. O chamador deve liberar essa estrutura MapiRecipDesc em algum momento chamando a função MAPIFreeBuffer . Se MAPIResolveName retornar um valor de erro, não será necessário desalocar memória com MAPIFreeBuffer.