MAPILogonEx

Artigo
12/18/2024

Aplica-se a: Outlook 2013 | Outlook 2016

Regista uma aplicação cliente numa sessão com o sistema de mensagens.

Propriedade	Valor
Arquivo de cabeçalho:	Mapix.h
Implementado por:	MAPI
Chamado por:	Aplicativos do cliente

HRESULT MAPILogonEx(
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  LPSTR lpszPassword,
  FLAGS flFlags,
  LPMAPISESSION FAR * lppSession
);

Parâmetros

ulUIParam

[in] Identificador para a janela na qual a caixa de diálogo de início de sessão é modal. Se não for apresentada nenhuma caixa de diálogo durante a chamada, o parâmetro ulUIParam é ignorado. Este parâmetro pode ser zero.

lpszProfileName

[in] Ponteiro para uma cadeia que contém o nome do perfil a utilizar quando o utilizador iniciar sessão. Esta cadeia de caracteres é limitada a 64 caracteres.

lpszPassword

[in] Ponteiro para uma cadeia que contém a palavra-passe do perfil. O parâmetro lpszPassword tem de ser NULL.

flFlags

[in] Máscara de bits de sinalizadores utilizada para controlar a forma como o início de sessão é executado. Os seguintes sinalizadores podem ser definidos:

MAPI_ALLOW_OTHERS

A sessão partilhada deve ser devolvida, o que permite que os clientes posteriores obtenham a sessão sem fornecer credenciais de utilizador.

MAPI_APP_PROFILE

Inclua perfis de "aplicação" na lista de diálogo de início de sessão. Se este sinalizador não estiver definido, os perfis de "aplicação" não serão incluídos. Este sinalizador pode não ser reconhecido ou suportado em todas as implementações mapi.

MAPI_BG_SESSION

Inicie sessão numa sessão e execute todas as operações em segundo plano. Em geral, se um cliente pretender efetuar o processamento num thread em segundo plano ou num processo separado de uma forma discreta para o thread de primeiro plano, deve chamar com o sinalizador MAPI_BG_SESSION. Uma aplicação cliente, como um motor de indexação ou a abertura de um Ficheiro de Pastas Pessoais (PST) para acesso ao tipo de fundo, são alguns exemplos de onde utilizar MAPI_BG_SESSION. MAPILogonEx.

MAPI_EXPLICIT_PROFILE

O perfil predefinido não deve ser utilizado e o utilizador deve ser obrigado a fornecer um perfil.

MAPI_EXTENDED

Inicie sessão com capacidades expandidas. Este sinalizador deve ser sempre definido.

MAPI_FORCE_DOWNLOAD

Deve ser efetuada uma tentativa de transferir todas as mensagens do utilizador antes de regressar. Se o sinalizador MAPI_FORCE_DOWNLOAD não estiver definido, as mensagens podem ser transferidas em segundo plano após a devolução da chamada para MAPILogonEx.

MAPI_LOGON_UI

Deve ser apresentada uma caixa de diálogo para pedir ao utilizador informações de início de sessão, se necessário. Quando o sinalizador MAPI_LOGON_UI não estiver definido, o cliente de chamada não apresenta uma caixa de diálogo de início de sessão e devolve um valor de erro se o utilizador não tiver sessão iniciada.

MAPI_NEW_SESSION

Deve ser feita uma tentativa para criar uma nova sessão MAPI em vez de adquirir a sessão partilhada. Se o sinalizador MAPI_NEW_SESSION não estiver definido, MAPILogonEx utiliza uma sessão partilhada existente, mesmo que o parâmetro lpszprofileName não seja NULL.

MAPI_NO_MAIL

A MAPI não deve informar o spooler MAPI da existência da sessão. O resultado é que nenhuma mensagem pode ser enviada ou recebida na sessão, exceto através de um par de armazenamento e transporte bem acoplados. Um cliente de chamada define este sinalizador se estiver a agir como um agente, se o trabalho de configuração tiver de ser feito ou se o cliente estiver a navegar nos arquivos de mensagens disponíveis.

MAPI_NT_SERVICE

O autor da chamada está em execução como um serviço Windows. Os autores de chamadas que não estejam em execução como um serviço Windows não devem definir este sinalizador; os autores de chamadas em execução como um serviço têm de definir este sinalizador.

MAPI_SERVICE_UI_ALWAYS

MAPILogonEx deve apresentar uma caixa de diálogo de configuração para cada serviço de mensagens no perfil. As caixas de diálogo são apresentadas depois de o perfil ter sido escolhido, mas antes de qualquer serviço de mensagens ser iniciado. A caixa de diálogo comum MAPI para início de sessão também contém uma caixa de marcar que pede a mesma operação.

MAPI_TIMEOUT_SHORT

O início de sessão deverá falhar se estiver bloqueado durante mais de alguns segundos.

MAPI_UNICODE

As cadeias de carateres transmitidas estão no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, as cadeias de carateres estão no formato ANSI.

MAPI_USE_DEFAULT

O subsistema de mensagens deve substituir o nome do perfil predefinido pelo parâmetro lpszProfileName . O sinalizador MAPI_EXPLICIT_PROFILE é ignorado, a menos que lpszProfileName seja NULL ou vazio.

lppSession

[fora] Ponteiro para um ponteiro para a interface de sessão MAPI.

Valor de retorno

S_OK

O início de sessão foi concluído com êxito.

MAPI_E_LOGON_FAILED

O início de sessão não teve êxito porque um ou mais dos parâmetros para MAPILogonEx eram inválidos ou porque já havia demasiadas sessões abertas.

MAPI_E_TIMEOUT

A MAPI serializa todos os inícios de sessão através de um mutex. Isto é devolvido se o sinalizador MAPI_TIMEOUT_SHORT tiver sido definido e outro thread tiver mantido o mutex.

MAPI_E_USER_CANCEL

Normalmente, o utilizador cancelou a operação ao clicar no botão Cancelar numa caixa de diálogo.

Comentários

As aplicações cliente MAPI chamam a função MAPILogonEx para iniciar sessão numa sessão com o sistema de mensagens. Todas as cadeias que são transmitidas e devolvidas de e para chamadas MAPI são terminadas de forma nula e têm de ser especificadas no conjunto de carateres ou página de código atual do sistema operativo do cliente ou fornecedor de chamadas.

O parâmetro lpszProfileName é ignorado se existir uma sessão anterior denominada MapiLogonEx com o sinalizador MAPI_ALLOW_OTHERS definido e se o sinalizador MAPI_NEW_SESSION não estiver definido. Se o parâmetro lpszProfileName for NULL ou apontar para uma cadeia vazia e o parâmetro flFlags incluir o sinalizador MAPI_LOGON_UI, a função MAPILogonEx gera uma caixa de diálogo de início de sessão que tem um campo vazio para o nome do perfil.

Ao iniciar sessão num perfil específico, um cliente deve transmitir o sinalizador MAPI_NEW_SESSION para MAPILogonEx, além do nome do perfil. Caso contrário, se outro cliente tiver estabelecido uma sessão partilhada ao iniciar sessão com MAPI_ALLOW_OTHERS, o cliente será registado na sessão partilhada em vez do perfil pedido.

O sinalizador MAPI_EXPLICIT_PROFILE não faz com que o nome de perfil predefinido seja utilizado quando lpszProfileName é NULO ou está vazio, a menos que o sinalizador MAPI_USE_DEFAULT também esteja presente.

O sinalizador MAPI_NO_MAIL tem vários efeitos que causam o seguinte quando não utiliza o spooler MAPI:

Não é possível enviar ou entregar mensagens pelo spooler MAPI durante esta sessão. Apenas os fornecedores de armazenamento e transporte bem acoplados podem enviar e entregar mensagens.
Os arquivos baseados no servidor ainda podem enviar ou entregar mensagens.
As mensagens enviadas ou entregues por arquivos baseados no servidor não são processadas por fornecedores de hook.
As opções por mensagem e por destinatário para transportes não estão disponíveis.
A tabela status não contém entradas para fornecedores de transporte e nenhuma funcionalidade de transporte dependente de objetos status (como a configuração) não está disponível.
A linha do spooler de mensagens na tabela status contém o valor STATUS_FAILURE.
Os inícios de sessão com piggyback são permitidos, mas esses inícios de sessão não fazem com que o início de sessão anterior receba status atualizações de objetos.