MAPILogonEx

Aplica-se a: Outlook 2013 | Outlook 2016

Registra um aplicativo cliente em uma sessão com o sistema de mensagens.

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

Parâmetros

ulUIParam

[em] Identificador para a janela para a qual a caixa de diálogo de 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

[em] Ponteiro para uma cadeia de caracteres que contém o nome do perfil a ser usado quando o usuário fizer logon. Esta cadeia de caracteres é limitada a 64 caracteres.

lpszPassword

[em] Ponteiro para uma cadeia de caracteres que contém a senha do perfil. O parâmetro lpszPassword deve ser NULL.

flFlags

[em] 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 nenhuma credencial de usuário.

MAPI_APP_PROFILE

Incluir perfis de "aplicativo" na lista de caixas de diálogo de logon. Se esse sinalizador não estiver definido, os perfis de "aplicativo" não serão incluídos. Esse sinalizador pode não ser reconhecido ou não ter suporte em todas as implementações MAPI.

MAPI_BG_SESSION

Faça logon em uma sessão e execute 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 que seja discreta para o thread em primeiro plano, ele deverá chamar com o sinalizador MAPI_BG_SESSION. Um aplicativo cliente, como um mecanismo de indexação ou a abertura de um PST (Arquivo de Pastas Particulares) 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 solicitado a fornecer um perfil.

MAPI_EXTENDED

Faça logon com recursos estendidos. Esse sinalizador deve estar sempre definido.

MAPI_FORCE_DOWNLOAD

Deve-se tentar baixar todas as mensagens do usuário antes de retornar. Se o sinalizador de MAPI_FORCE_DOWNLOAD não estiver definido, as mensagens podem 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 de MAPI_LOGON_UI não está 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

Deve-se tentar criar uma nova sessão MAPI em vez de adquirir a sessão compartilhada. Se o sinalizador MAPI_NEW_SESSION não estiver definido, o 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 sobre a 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 fortemente acoplado. Um cliente de chamada define esse sinalizador se estiver atuando como um agente, se for necessário fazer um trabalho de configuração ou se o cliente estiver navegando pelos repositórios de mensagens disponíveis.

MAPI_NT_SERVICE

O chamador está sendo executado como um serviço do Windows. Os chamadores que não estão executando como um serviço do Windows não devem definir esse sinalizador; Os chamadores que estão executando como um serviço devem definir esse sinalizador.

MAPI_SERVICE_UI_ALWAYS

O MAPILogonEx deve exibir uma caixa de diálogo de configuração para cada serviço de mensagens no perfil. As caixas de diálogo são exibidas depois que o perfil tiver sido escolhido, mas antes que qualquer serviço de mensagens seja conectado. A caixa de diálogo comum MAPI para logon também contém uma caixa de marca que solicita a mesma operação.

MAPI_TIMEOUT_SHORT

O logon deverá falhar se bloqueado por mais do que 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

[fora] Ponteiro para um ponteiro para a interface de 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 parâmetros do MAPILogonEx eram inválidos ou porque já havia muitas sessões abertas.

MAPI_E_TIMEOUT

O MAPI serializa todos os logons por meio de um mutex. Isso retorna se o sinalizador de MAPI_TIMEOUT_SHORT foi definido e outro thread conteve o mutex.

MAPI_E_USER_CANCEL

O usuário cancelou a operação, geralmente 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 passadas e retornadas de e para chamadas MAPI são terminadas 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 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 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 de perfil padrão seja usado quando lpszProfileName é NULL ou vazio, a menos que o sinalizador MAPI_USE_DEFAULT também esteja presente.

O sinalizador de MAPI_NO_MAIL tem vários efeitos que causam o seguinte quando o spooler MAPI não está sendo usado:

• Nenhuma mensagem pode ser enviada ou entregue pelo spooler MAPI durante esta sessão. Somente provedores de armazenamento e transporte fortemente 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 de status não contém entradas para provedores de transporte e qualquer funcionalidade de transporte dependente de objetos de status (como configuração) não está disponível.

• A linha do spooler de mensagens na tabela status contém o valor STATUS_FAILURE.

• São permitidos logons piggyback, mas eles não fazem com que o logon anterior receba atualizações de objeto de status.

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.

Confira também

IMAPISession::GetMsgStoresTable

IMAPISession::OpenMsgStore

MFCMAPI como exemplo de código