IXPProvider::TransportLogon
Aplica-se a: Outlook 2013 | Outlook 2016
Estabelece uma sessão na qual um aplicativo cliente faz logon em um provedor de transporte.
HRESULT TransportLogon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG FAR * lpulFlags,
LPMAPIERROR FAR * lppMAPIError,
LPXPLOGON FAR * lppXPLogon
);
Parâmetros
lpMAPISup: [in] Ponteiro para o objeto de suporte do provedor de transporte para funções de retorno de chamada no MAPI para esta sessão. Esse objeto permanece válido até que o provedor de transporte o libere.
ulUIParam: [in] Manipular para a janela pai de qualquer caixa de diálogo ou janelas que este método exibe. O parâmetro ulUIParam pode ser não nulo, por exemplo, quando o sinalizador LOGON_SETUP é definido no parâmetro lpulFlags .
lpszProfileName: [in] Ponteiro para o nome do perfil do usuário. O parâmetro lpszProfileName é usado principalmente quando uma caixa de diálogo deve ser apresentada.
lpulFlags: [in, out] Bitmask de sinalizadores que controla como a sessão de logon é estabelecida. Os seguintes sinalizadores podem ser definidos na entrada pelo spooler MAPI:
LOGON_NO_CONNECT: a conta de usuário está fazendo logon neste provedor de transporte para fins diferentes de transmissão e recepção de mensagens. O provedor de transporte não deve tentar fazer nenhuma conexão com outros sistemas de mensagens.
LOGON_NO_DIALOG: nenhuma caixa de diálogo deve ser exibida mesmo que as credenciais de usuário salvas no momento sejam inválidas ou insuficientes para logon.
LOGON_NO_INBOUND: o provedor de transporte não precisa inicializar para a recepção de mensagens e não deve aceitar mensagens de entrada. O spooler MAPI pode usar o método IXPLogon::TransportNotify mais tarde para sinalizar o provedor de transporte para habilitar o processamento de mensagens de entrada.
LOGON_NO_OUTBOUND: o provedor de transporte não precisa inicializar para enviar mensagens, pois o spooler MAPI não fornece nenhum. Se um aplicativo cliente exigir uma conexão com um provedor remoto durante a composição de uma mensagem para que ele possa fazer chamadas de método IXPLogon::AddressTypes , o provedor de transporte deverá fazer a conexão. O spooler MAPI pode usar TransportNotify para sinalizar o provedor de transporte quando as operações de saída podem começar.
MAPI_UNICODE: a cadeia de caracteres passada para o nome do perfil está no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, a cadeia de caracteres estará no formato ANSI.
Os seguintes sinalizadores podem ser definidos na saída pelo provedor de transporte:
LOGON_SP_IDLE: solicita que o spooler MAPI chame frequentemente o método IXPLogon::Idle do provedor de transporte para processamento de tempo ocioso.
LOGON_SP_POLL: solicita que o spooler MAPI chame frequentemente o método IXPLogon::P oll no objeto logon retornado para marcar para novas mensagens. Se esse sinalizador não estiver definido, o spooler MAPI só verificará novas mensagens quando o provedor de transporte usar o método IMAPISupport::SpoolerNotify para notificar o spooler de que há novas mensagens a serem processadas. Um provedor de transporte efetivamente se torna somente envio não definindo esse sinalizador e não notificando o carretel MAPI do recibo de mensagem.
LOGON_SP_RESOLVE: solicita que o spooler MAPI resolve para endereços completos de todos os endereços de mensagem para destinatários não compatíveis com esse provedor de transporte. Portanto, o provedor de transporte pode construir um caminho de resposta para todos os destinatários.
MAPI_UNICODE: as cadeias de caracteres retornadas na estrutura MAPIERROR , se houver, estão no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, as cadeias de caracteres estarão no formato ANSI.
lppMAPIError: [out] Ponteiro para um ponteiro para a estrutura MAPIERROR retornada, se houver, que contém informações de versão, componente e contexto para o erro. O parâmetro lppMAPIError poderá ser definido como NULL se não houver nenhuma estrutura MAPIERROR a ser retornada.
lppXPLogon: [out] Ponteiro para o ponteiro para o objeto logon do provedor de transporte retornado.
Valor de retorno
S_OK: a chamada foi bem-sucedida e retornou o valor ou valores esperados.
MAPI_E_FAILONEPROVIDER: esse provedor não pode fazer logon, mas esse erro não deve desabilitar o serviço.
MAPI_E_UNCONFIGURED: o perfil não contém informações suficientes para que o logon seja concluído. O MAPI chama a função de ponto de entrada do serviço de mensagem do provedor.
MAPI_E_UNKNOWN_CPID: o provedor não pode dar suporte à página de código do cliente.
MAPI_E_UNKNOWN_LCID: o provedor não pode 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 em uma caixa de diálogo.
Comentários
O spooler MAPI chama o método IXPProvider::TransportLogon para estabelecer uma sessão de logon para um usuário.
A maioria dos provedores de transporte usa o método IMAPISupport::OpenProfileSection fornecido com o objeto de suporte apontado pelo parâmetro lpMAPISup para salvar e recuperar informações de identidade do usuário, endereços de servidor e credenciais. Usando o OpenProfileSection, um provedor de transporte pode salvar informações arbitrárias e associá-la a um logon a um determinado recurso. Por exemplo, um provedor pode usar OpenProfileSection para salvar o nome da conta e a senha associados a uma sessão específica e quaisquer nomes de servidor ou outras informações necessárias que sejam necessárias para acessar recursos para essa sessão. O MAPI oculta informações associadas a um recurso de acesso externo. A seção de perfil disponibilizada por meio do lpMAPISup é gerenciada pelo spooler MAPI para que os dados relacionados a esse contexto de usuário sejam separados dos dados para outros contextos.
O provedor de transporte deve chamar o método IUnknown::AddRef no objeto de suporte e manter uma cópia do ponteiro para esse objeto como parte do objeto logon do provedor.
O nome de exibição de perfil em lpszProfileName é fornecido para que o provedor de transporte possa usá-lo em mensagens de erro ou caixas de diálogo de logon. Se o provedor mantiver esse nome, ele deverá ser copiado para o armazenamento alocado pelo provedor.
Os provedores de transporte que estão fortemente associados a outros provedores de serviços podem ter que fazer um trabalho adicional no logon para estabelecer as boas credenciais necessárias para operações entre provedores complementares.
Normalmente, os provedores de transporte são abertos quando o usuário faz logon pela primeira vez em um perfil. Como o primeiro logon em um perfil geralmente vem antes do logon em qualquer repositório de mensagens, o spooler MAPI geralmente chama TransportLogon com os sinalizadores LOGON_NO_INBOUND e LOGON_NO_OUTBOUND definidos em lpulFlags. Posteriormente, quando os armazenamentos de mensagens apropriados estiverem disponíveis na sessão de perfil, o spooler MAPI chama TransportNotify para iniciar operações de entrada e saída para o provedor de transporte.
Passar o sinalizador de LOGON_NO_CONNECT em lpulFlags sinaliza a operação offline do provedor de transporte. Esse sinalizador indica que nenhuma conexão externa deve ser feita; se o provedor de transporte não puder estabelecer uma sessão sem uma conexão externa, ele deverá retornar um valor de erro para o logon.
Um provedor de transporte deve definir o sinalizador de LOGON_SP_IDLE em lpulFlags no momento da inicialização se ele for projetado para usar o tempo que o sistema de outra forma gasta ocioso. Esse tempo geralmente é usado para lidar com operações automáticas, como download automático de mensagens, download de mensagens em tempo hábil ou envio de mensagem em tempo hábil. Se esse sinalizador for definido, o spooler MAPI chamará Idle quando o tempo ocioso do sistema ocorrer para iniciar essas operações. O spooler MAPI não chama Idle em intervalos definidos; em vez disso, ele é chamado somente durante o tempo ocioso verdadeiro. Portanto, os provedores não devem trabalhar em nenhuma suposição sobre a frequência com que seus métodos ociosos serão chamados. Os provedores que dão suporte a operações de tempo ocioso devem fornecer uma interface do usuário de configuração para ele na planilha de propriedades do provedor.
Se o logon do provedor de transporte for bem-sucedido, o provedor deverá retornar no parâmetro lppXPLogon um ponteiro para um objeto logon. O spooler MAPI usará esse objeto para acesso adicional ao provedor. Se TransportLogon exibir uma caixa de diálogo de logon e o usuário cancelar o logon normalmente clicando no botão Cancelar na caixa de diálogo, o provedor deverá retornar MAPI_E_USER_CANCEL.
Para a maioria dos valores de erro retornados do TransportLogon, o MAPI desabilita os serviços de mensagem aos quais o provedor pertence. O MAPI não chamará nenhum provedor que pertença a esse serviço para o restante da sessão MAPI. Por outro lado, quando o TransportLogon retorna o MAPI_E_FAILONEPROVIDER valor de erro de seu logon, o MAPI não desabilitará o serviço de mensagem ao qual o provedor pertence. O TransportLogon deverá retornar MAPI_E_FAILONEPROVIDER se encontrar um erro que não justifique desabilitar o serviço para o resto da sessão.
Se um provedor retornar MAPI_E_UNCONFIGURED de seu logon, o MAPI chamará a função de entrada do serviço de mensagem do provedor e tentará novamente o logon. MAPI passa MSG_SERVICE_CONFIGURE como o contexto, para dar ao serviço a chance de se configurar. Se o cliente tiver escolhido permitir uma interface do usuário no logon, o serviço poderá apresentar sua folha de propriedades de configuração para que o usuário possa inserir informações de configuração.
Se o provedor descobrir que todas as informações necessárias não estão no perfil, ele deverá retornar MAPI_E_UNCONFIGURED para que o MAPI chame a função de ponto de entrada do serviço de mensagem do provedor.