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

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

A função MAPILogon inicia uma sessão MAPI simples, carregando o repositório de mensagens padrão e os provedores de catálogo de endereços.

Sintaxe

MAPILOGON Mapilogon;

ULONG Mapilogon(
  [in]           ULONG_PTR ulUIParam,
  [in, optional] LPSTR lpszProfileName,
  [in, optional] LPSTR lpszPassword,
  [in]           FLAGS flFlags,
                 ULONG ulReserved,
  [out]          LPLHANDLE lplhSession
)
{...}

Parâmetros

[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, optional] lpszProfileName

Ponteiro para uma cadeia de caracteres de nome de perfil terminada em nulo, limitada a 256 caracteres ou menos. Esse é o perfil a ser usado ao fazer logon. Se o parâmetro lpszProfileName for NULL ou apontar para uma cadeia de caracteres vazia e o parâmetro flFlags estiver definido como MAPI_LOGON_UI, MAPILogon exibirá uma caixa de diálogo de logon com um campo de nome vazio.

[in, optional] lpszPassword

Ponteiro para uma cadeia de caracteres de credencial terminada em nulo, limitada a 256 caracteres ou menos. Se o sistema de mensagens não exigir credenciais de senha ou se exigir que o usuário as insira, o parâmetro lpszPassword deverá ser NULL ou apontar para uma cadeia de caracteres vazia. Quando o usuário deve inserir credenciais, o parâmetro flFlags deve ser definido como MAPI_LOGON_UI para permitir que uma caixa de diálogo de logon seja exibida.

[in] flFlags

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

Valor	Significado
MAPI_FORCE_DOWNLOAD	Uma tentativa deve ser feita para baixar todas as mensagens do usuário antes de retornar. Se o sinalizador MAPI_FORCE_DOWNLOAD não estiver definido, as mensagens poderão ser baixadas em segundo plano após o retorno da chamada de função.
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, MAPILogon usará uma sessão compartilhada existente.
MAPI_LOGON_UI	Uma caixa de diálogo de logon deve ser exibida para solicitar ao usuário informações de logon. Se o usuário precisar fornecer uma senha e um nome de perfil para habilitar um logon bem-sucedido, MAPI_LOGON_UI deverá ser definido.
MAPI_PASSWORD_UI	MAPILogon só deve solicitar uma senha e não permitir que o usuário altere o nome do perfil. MAPI_PASSWORD_UI ou MAPI_LOGON_UI não deve ser definido, pois a intenção é selecionar entre duas caixas de diálogo diferentes para logon.

ulReserved

Reservados; deve ser zero.

[out] lplhSession

Identificador de sessão MAPI simples.

Retornar valor

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 logon. Nenhum identificador de sessão foi retornado.
MAPI_E_INSUFFICIENT_MEMORY	Não havia memória suficiente para continuar. Nenhum identificador de sessão foi retornado.
MAPI_E_LOGIN_FAILURE	Não havia logon padrão e o usuário não conseguiu fazer logon com êxito quando a caixa de diálogo de logon foi exibida. Nenhum identificador de sessão foi retornado.
MAPI_E_TOO_MANY_SESSIONS	O usuário tinha muitas sessões abertas simultaneamente. Nenhum identificador de sessão foi retornado.
MAPI_E_USER_ABORT	O usuário cancelou a caixa de diálogo de logon. Nenhum identificador de sessão foi retornado.
SUCCESS_SUCCESS	A chamada foi bem-sucedida e uma sessão MAPI simples foi estabelecida.

Comentários

A função MAPILogon inicia uma sessão com o sistema de mensagens, retornando um identificador que pode ser usado em chamadas MAPI subsequentes para fornecer explicitamente as credenciais do usuário para o sistema de mensagens. Para solicitar a exibição de uma caixa de diálogo de logon se as credenciais apresentadas não validarem a sessão, defina o parâmetro flFlags como MAPI_LOGON_UI.

O aplicativo cliente testa uma sessão existente chamando MAPILogon com um valor NULL para o parâmetro lpszProfileName , um valor NULL para o parâmetro lpszPassword e não definindo o sinalizador MAPI_LOGON_UI em flFlags. Se houver uma sessão existente, a chamada terá êxito e retornará um LHANDLE válido para a sessão. Caso contrário, a chamada falhará.

Requisitos

Requisito	Valor
Plataforma de Destino	Windows
Cabeçalho	mapi.h

Confira também

MAPILogoff

MAPI simples