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

Artigo
03/09/2023

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

A função MAPIAddress cria ou modifica um conjunto de entradas de lista de endereços.

Sintaxe

MAPIADDRESS Mapiaddress;

ULONG Mapiaddress(
  [in]  LHANDLE lhSession,
  [in]  ULONG_PTR ulUIParam,
  [in]  LPSTR lpszCaption,
  [in]  ULONG nEditFields,
  [in]  LPSTR lpszLabels,
  [in]  ULONG nRecips,
  [in]  lpMapiRecipDesc lpRecips,
  [in]  FLAGS flFlags,
        ULONG ulReserved,
  [out] LPULONG lpnNewRecips,
        lpMapiRecipDesc *lppNewRecips
)
{...}

Parâmetros

[in] lhSession

Identificador de sessão 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, uma 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] lpszCaption

Ponteiro para o legenda da caixa de diálogo da lista de endereços, NULL ou uma cadeia de caracteres vazia. Quando o parâmetro lpszCaption é NULL ou aponta para uma cadeia de caracteres vazia, MAPIAddress usa o padrão legenda "Catálogo de Endereços".

[in] nEditFields

O número de controles de edição que devem estar presentes na lista de endereços. Os valores de 0 a 4 são válidos. Se o valor do parâmetro nEditFields for 4, cada classe de destinatário compatível com o sistema de mensagens subjacente terá um controle de edição. Se o valor de nEditFields for zero, somente a navegação na lista de endereços será possível. Os valores de 1, 2 ou 3 controlam o número de controles de edição presentes. No entanto, se o número de classes de destinatário na matriz apontada pelo parâmetro lpRecips for maior que o valor de nEditFields, o número de classes em lpRecips será usado para indicar o número de controles de edição em vez do valor de nEditFields. Se o valor de nEditFields for 1 e mais de um tipo de entrada existir em lpRecips, o parâmetro lpszLabels será ignorado. As entradas selecionadas para os diferentes controles são diferenciadas pelo membro ulRecipClass na estrutura de destinatário retornada.

[in] lpszLabels

Ponteiro para uma cadeia de caracteres a ser usada como um rótulo de controle de edição na caixa de diálogo de lista de endereços. Quando o parâmetro nEditFields é definido como qualquer valor diferente de 1, o parâmetro lpszLabels é ignorado e deve ser NULL ou apontar para uma cadeia de caracteres vazia. Além disso, se o chamador exigir o rótulo de controle padrão "To", lpszLabels deverá ser NULL ou apontar para uma cadeia de caracteres vazia.

[in] nRecips

O número de entradas na matriz indicada pelo parâmetro lpRecips . Se o valor do parâmetro nRecips for zero, lpRecips será ignorado.

[in] lpRecips

Ponteiro para uma matriz de estruturas MapiRecipDesc definindo as entradas iniciais do destinatário a serem usadas para preencher a caixa de diálogo de lista de endereços. As entradas não precisam ser agrupadas por classe de destinatário; eles são diferenciados pelos valores dos membros ulRecipClass das estruturas MapiRecipDesc na matriz. Se o número de classes de destinatário diferentes for maior que o valor indicado pelo parâmetro nEditFields , os parâmetros nEditFields e lpszLabels serão ignorados .

[in] flFlags

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

Valor	Significado
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, MAPIAddress usará uma sessão compartilhada existente.

ulReserved

Reservados; deve ser zero.

[out] lpnNewRecips

Ponteiro para o número de entradas na matriz de saída do destinatário lppNewRecips . Se o valor do parâmetro lpnNewRecips for zero, o parâmetro lppNewRecips será ignorado.

lppNewRecips

Valor retornado

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

Código de retorno	Descrição
MAPI_E_FAILURE	Um ou mais erros não especificados ocorreram durante o endereçamento da mensagem. Nenhuma lista de entradas de destinatário foi retornada.
MAPI_E_INSUFFICIENT_MEMORY	Não havia memória suficiente para continuar. Nenhuma lista de entradas de destinatário foi retornada.
MAPI_E_INVALID_EDITFIELDS	O valor do parâmetro nEditFields estava fora do intervalo de 0 a 4. Nenhuma lista de entradas de destinatário foi retornada.
MAPI_E_INVALID_RECIPS	Um ou mais dos destinatários na lista de endereços não era válido. Nenhuma lista de entradas de destinatário foi retornada.
MAPI_E_INVALID_SESSION	Um identificador de sessão inválido foi usado para o parâmetro lhSession . Nenhuma lista de entradas de destinatário foi retornada.
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. Nenhuma lista de entradas de destinatário foi retornada.
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. Nenhuma lista de entradas de destinatário foi retornada.
SUCCESS_SUCCESS	A chamada foi bem-sucedida e uma lista de entradas de destinatário foi retornada.

Comentários

A função MAPIAddress exibe uma caixa de diálogo de lista de endereços padrão para mostrar um conjunto inicial de zero ou mais destinatários. O usuário pode escolher novas entradas para adicionar ao conjunto ou fazer alterações em entradas existentes. Essa caixa de diálogo não pode ser suprimida, mas o chamador pode definir características da caixa de diálogo. O conjunto alterado de destinatários é retornado ao chamador.

Antes de MAPIAddress gravar informações novas ou alteradas do destinatário, ele deve alocar memória para a matriz de estrutura que conterá as informações. A memória também é alocada como parte do pré-carregamento do catálogo de endereços, independentemente de os dados do destinatário novos ou alterados serem gravados. Os aplicativos cliente devem chamar a função MAPIFreeBuffer para liberar essa memória após o retorno de MAPIAddress . Se ocorrer algum erro, nenhuma memória foi alocada e os clientes não precisam chamar MAPIFreeBuffer.