IABProvider::Logon
Aplica-se a: Outlook 2013 | Outlook 2016
Estabelece uma conexão com uma sessão ativa.
HRESULT Logon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG ulFlags,
ULONG FAR * lpulcbSecurity,
LPBYTE FAR * lppbSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPABLOGON FAR * lppABLogon
);
Parâmetros
lpMAPISup
[in] Um ponteiro para o objeto de suporte do provedor de catálogo de endereços.
ulUIParam
[in] Um identificador para a janela pai da caixa de diálogo logon que o método Logon exibe, se permitido. O parâmetro ulUIParam contém o valor do parâmetro do mesmo nome passado para MAPI na chamada anterior para a função MAPILogonEx .
Lpszprofilename
[in] Um ponteiro para o nome do perfil da sessão.
ulFlags
[in] Um bitmask de sinalizadores que controla como o logon é executado. Os seguintes sinalizadores podem ser definidos:
AB_NO_DIALOG
O provedor não deve exibir uma caixa de diálogo durante o logon. Se esse sinalizador não estiver definido, o provedor poderá exibir uma caixa de diálogo para solicitar ao usuário informações de configuração ausentes.
MAPI_DEFERRED_ERRORS
Permite que o Logon retorne com êxito, possivelmente antes que o processo de logon seja concluído.
MAPI_UNICODE
Todas as cadeias de caracteres devem estar no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, as cadeias de caracteres deverão estar no formato ANSI.
LpulcbSecurity
[in, out] Um ponteiro para o tamanho, em bytes, da estrutura de credenciais de segurança apontada pelo parâmetro lppbSecurity . Na entrada, o valor deve não ser zero; na saída, o valor deve ser zero. Em ambos os casos, os ponteiros devem ser válidos.
lppbSecurity
[in, out] Um ponteiro para um ponteiro para credenciais de segurança. Na entrada, o valor deve não ser zero; na saída, o valor deve ser zero. Em ambos os casos, o ponteiro deve ser válido.
lppMAPIError
[out] Um ponteiro para um ponteiro para uma estrutura MAPIERROR . O parâmetro lppMAPIError poderá ser definido como NULL se não houver nenhuma estrutura MAPIERROR a ser retornada.
lppABLogon
[out] Um ponteiro para um ponteiro para o objeto de logon do provedor.
Valor de retorno
S_OK
Uma conexão com uma sessão ativa foi estabelecida com êxito.
MAPI_E_FAILONEPROVIDER
O provedor não pode fazer logon, mas o MAPI pode continuar a fazer logon nos outros provedores no serviço de mensagens ao qual o provedor pertence.
MAPI_E_UNCONFIGURED
O provedor não tem informações suficientes para concluir o logon. O MAPI chama a função de entrada do serviço de mensagem do provedor.
MAPI_E_UNKNOWN_CPID
O servidor não está configurado para dar suporte à página de código do cliente.
MAPI_E_UNKNOWN_LCID
O servidor não está configurado para dar suporte às informações de localidade do cliente.
MAPI_E_USER_CANCEL
O usuário cancelou a operação, normalmente clicando no botão Cancelar na caixa de diálogo logon.
Comentários
Connections são estabelecidas com cada provedor de catálogo de endereços no perfil de sessão quando um cliente chama o método IMAPISession::OpenAddressBook. OpenAddressBook chama o método Logon de cada provedor.
O nome do perfil apontado pelo parâmetro lpszProfileName é exibido no conjunto de caracteres do cliente do usuário, conforme indicado pela presença ou ausência do sinalizador MAPI_UNICODE no parâmetro ulFlags .
Observações para implementadores
Na implementação do método Logon , chame o método IMAPISupport::SetProviderUID para registrar um identificador exclusivo ou estrutura MAPIUID . Cada um dos objetos terá um identificador de entrada que inclui este MAPIUID. O MAPI usa o MAPIUID para corresponder um objeto com seu provedor. Por exemplo, quando um cliente chama o método IMAPISession::OpenEntry para abrir um usuário de mensagens, o OpenEntry examina a parte MAPIUID do identificador de entrada que foi passada e corresponde a ela com um MAPIUID registrado por um provedor de catálogo de endereços.
Se um cliente fizer logon em seu provedor mais de uma vez, talvez você queira registrar um MAPIUID diferente para cada logon. O registro de estruturas MAPIUID exclusivas permite que o MAPI rote corretamente as solicitações para a instância de provedor apropriada. No entanto, talvez você queira que cada objeto de logon compartilhe um MAPIUID. Nesse caso, você deve ser capaz de lidar com o roteamento por conta própria em vez de confiar no MAPI. Para obter mais informações sobre como criar um MAPIUID, consulte Registrando identificadores exclusivos do provedor de serviços.
O objeto de suporte que MAPI passa para o método Logon no parâmetro lpMAPISup fornece acesso a muitos dos métodos incluídos na interface IMAPISupport : IUnknown . O MAPI cria um objeto de suporte personalizado para o seu tipo de provedor. Por exemplo, se você precisar fazer logon em um sistema de mensagens subjacente ou serviço de diretório ao estabelecer sua conexão, poderá chamar o método IMAPISupport::OpenProfileSection para recuperar credenciais de segurança para esta sessão de logon específica.
Se o Logon for bem-sucedido, chame o método IUnknown::AddRef do objeto de suporte para incrementar sua contagem de referência. Isso permite que seu provedor mantenha o ponteiro de objeto de suporte para o restante da sessão. Se você não chamar esse método AddRef , o MAPI descarregará seu provedor.
Você pode incluir o nome do perfil passado no parâmetro lpszProfileName em caixas de diálogo de erro, telas de logon ou outras interfaces de usuário. Para usar o nome do perfil, copie-o para o armazenamento alocado.
Crie um objeto logon e retorne um ponteiro para ele no parâmetro lppABLogon . O MAPI usa esse objeto logon para fazer chamadas para os métodos na implementação do IABLogon .
Se você precisar de uma senha durante o logon, exiba uma caixa de diálogo de logon somente se o sinalizador AB_NO_DIALOG não estiver definido. Se o usuário cancelar o processo de logon, normalmente clicando no botão Cancelar na caixa de diálogo, retorne MAPI_E_USER_CANCEL do Logon.
Normalmente, quando um provedor de catálogo de endereços não pode fazer logon, o MAPI desabilita o serviço de mensagem ao qual o provedor com falha pertence , ou seja, o MAPI não tentará estabelecer conexões para nenhum dos outros provedores que pertencem ao serviço pelo resto do tempo de vida da sessão. No entanto, se o provedor não puder estabelecer uma conexão e você não quiser desabilitar todo o serviço, retorne MAPI_E_FAILONEPROVIDER ou MAPI_E_UNCONFIGURED. O MAPI não desabilitará o serviço de mensagem ao qual o provedor pertence.
Retorne MAPI_E_FAILONEPROVIDER se ocorrer um erro que não seja grave o suficiente para impedir que os outros provedores no serviço de mensagens estabeleçam conexões. Retorne MAPI_E_UNCONFIGURED se as informações de configuração necessárias estiverem ausentes do perfil e você não puder exibir uma caixa de diálogo para solicitar o usuário. O MAPI responderá chamando a função de ponto de entrada do serviço de mensagem do provedor com MSG_SERVICE_CONFIGURE definido como o parâmetro ulContext para dar ao serviço a chance de se configurar, programaticamente ou usando uma folha de propriedades. Quando a função de ponto de entrada do serviço de mensagem for concluída, o MAPI repetirá o logon.