MAPILogonEx
Aplica-se a: Outlook 2013 | Outlook 2016
Registra um aplicativo cliente em uma 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] Manipule para a janela para a qual a caixa de diálogo logon é modal. Se nenhuma caixa de diálogo for exibida durante a chamada, o parâmetro ulUIParam será ignorado. Esse parâmetro pode ser zero.
Lpszprofilename
[in] Ponteiro para uma cadeia de caracteres que contém o nome do perfil a ser usado quando o usuário faz logon. Esta cadeia de caracteres é limitada a 64 caracteres.
lpszPassword
[in] Ponteiro para uma cadeia de caracteres que contém a senha do perfil. O parâmetro lpszPassword deve ser NULL.
flFlags
[in] Bitmask de sinalizadores usados para controlar como o logon é executado. Os seguintes sinalizadores podem ser definidos:
MAPI_ALLOW_OTHERS
A sessão compartilhada deve ser retornada, o que permite que clientes posteriores obtenham a sessão sem fornecer credenciais de usuário.
MAPI_BG_SESSION
Faça logon em uma sessão e execute todas as operações em segundo plano. Em geral, se um cliente pretende fazer o processamento em um thread em segundo plano ou em um processo separado de uma maneira discreta para o thread em primeiro plano, ele deve chamar com o sinalizador de MAPI_BG_SESSION. Um aplicativo cliente, como um mecanismo de indexação ou abrir um PST (Arquivo de Pastas Pessoais) para acesso ao tipo de plano de fundo, são alguns exemplos de onde usar MAPI_BG_SESSION. MAPILogonEx.
MAPI_EXPLICIT_PROFILE
O perfil padrão não deve ser usado e o usuário deve ser necessário para fornecer um perfil.
MAPI_EXTENDED
Faça logon com recursos estendidos. Esse sinalizador deve ser sempre definido.
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 para MAPILogonEx.
MAPI_LOGON_UI
Uma caixa de diálogo deve ser exibida para solicitar ao usuário informações de logon, se necessário. Quando o sinalizador MAPI_LOGON_UI não é definido, o cliente de chamada não exibe uma caixa de diálogo de logon e retorna 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 MAPI em vez de adquirir a sessão compartilhada. Se o sinalizador MAPI_NEW_SESSION não estiver definido, MAPILogonEx usará uma sessão compartilhada existente, mesmo que o parâmetro lpszprofileName não seja NULL.
MAPI_NO_MAIL
O 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 por meio de um par de armazenamento e transporte bem acoplados. Um cliente de chamada define esse sinalizador se ele estiver agindo como um agente, se o trabalho de configuração precisar ser feito ou se o cliente estiver navegando nos repositórios de mensagens disponíveis.
MAPI_NT_SERVICE
O chamador está em execução como um serviço windows. Os chamadores que não estão em execução como um serviço Windows não devem definir esse sinalizador; os chamadores que estão em execução como um serviço devem definir esse sinalizador.
MAPI_SERVICE_UI_ALWAYS
MAPILogonEx deve exibir uma caixa de diálogo de configuração para cada serviço de mensagem no perfil. As caixas de diálogo são exibidas após a escolha do perfil, mas antes que qualquer serviço de mensagem seja conectado. A caixa de diálogo comum MAPI para logon também contém uma caixa de marcar que solicita a mesma operação.
MAPI_TIMEOUT_SHORT
O logon deve falhar se estiver bloqueado por mais de alguns segundos.
MAPI_UNICODE
As cadeias de caracteres passadas estão no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, as cadeias de caracteres estarão no formato ANSI.
MAPI_USE_DEFAULT
O subsistema de mensagens deve substituir o nome do perfil padrão pelo parâmetro lpszProfileName . O sinalizador MAPI_EXPLICIT_PROFILE é ignorado, a menos que lpszProfileName seja NULL ou vazio.
lppSession
[out] Ponteiro para um ponteiro para a interface da sessão MAPI.
Valor de retorno
S_OK
O logon foi bem-sucedido.
MAPI_E_LOGON_FAILED
O logon não foi bem sucedido, porque um ou mais dos parâmetros para MAPILogonEx eram inválidos ou porque já havia muitas sessões abertas.
MAPI_E_TIMEOUT
MAPI serializa todos os logons por meio de um mutex. Isso será retornado se o sinalizador MAPI_TIMEOUT_SHORT estiver definido e outro thread segurar o mutex.
MAPI_E_USER_CANCEL
O usuário cancelou a operação, normalmente clicando no botão Cancelar em uma caixa de diálogo.
Comentários
Os aplicativos cliente MAPI chamam a função MAPILogonEx para fazer logon em uma sessão com o sistema de mensagens. Todas as cadeias de caracteres que são passadas e retornadas de e para chamadas MAPI são encerradas em nulo e devem ser especificadas no conjunto de caracteres atual ou na página de código do sistema operacional do cliente ou provedor de chamada.
O parâmetro lpszProfileName será ignorado se houver uma sessão anterior existente chamada MapiLogonEx com o conjunto de sinalizadores MAPI_ALLOW_OTHERS e se o sinalizador MAPI_NEW_SESSION não estiver definido. Se o parâmetro lpszProfileName for NULL ou apontar para uma cadeia de caracteres vazia e o parâmetro flFlags incluir o sinalizador MAPI_LOGON_UI, a função MAPILogonEx gerará uma caixa de diálogo de logon com um campo vazio para o nome do perfil.
Ao fazer logon em um perfil específico, um cliente deve passar o sinalizador de MAPI_NEW_SESSION para MAPILogonEx, além do nome do perfil. Caso contrário, se outro cliente tiver estabelecido uma sessão compartilhada fazendo logon com MAPI_ALLOW_OTHERS, o cliente será conectado à sessão compartilhada em vez do perfil solicitado.
O sinalizador MAPI_EXPLICIT_PROFILE não faz com que o nome do perfil padrão seja usado quando lpszProfileName for NULL ou 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 ao não usar o spooler MAPI:
Nenhuma mensagem pode ser enviada ou entregue pelo spooler MAPI durante esta sessão. Somente provedores de armazenamento e transporte bem acoplados podem enviar e entregar mensagens.
Os repositórios baseados em servidor ainda podem enviar ou entregar mensagens.
As mensagens enviadas ou entregues por repositórios baseados em servidor não são processadas por nenhum provedor de gancho.
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 provedores de transporte e nenhuma funcionalidade de transporte dependente de objetos status (como configuração) não está disponível.
A linha do spooler de mensagem na tabela status contém o valor STATUS_FAILURE.
Logons com piggyback são permitidos, mas esses logons não fazem com que o logon anterior receba status atualizações de objeto.
Um serviço deve sempre fazer logon usando o sinalizador MAPI_NO_MAIL.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| MAPIObjects.cpp |
CMapiObjects::MAPILogonEx |
O MFCMAPI usa o método MAPILogonEx para fazer logon no MAPI. |