IMSProvider::Logon

Artigo
07/19/2024

Aplica-se a: Outlook 2013 | Outlook 2016

Regista a MAPI numa instância de um fornecedor de arquivo de mensagens.

HRESULT Logon(
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulFlags,
  LPCIID lpInterface,
  ULONG FAR * lpcbSpoolSecurity,
  LPBYTE FAR * lppbSpoolSecurity,
  LPMAPIERROR FAR * lppMAPIError,
  LPMSLOGON FAR * lppMSLogon,
  LPMDB FAR * lppMDB
);

Parâmetros

lpMAPISup

[in] Um ponteiro para o objeto de suporte MAPI atual para o arquivo de mensagens.

ulUIParam

[in] Uma alça para a janela principal de quaisquer caixas de diálogo ou janelas apresentadas por este método.

lpszProfileName

[in] Um ponteiro para uma cadeia que contém o nome do perfil que está a ser utilizado para o início de sessão do fornecedor da loja. Esta cadeia pode ser apresentada em caixas de diálogo, escrita num ficheiro de registo ou simplesmente ignorada. Tem de estar no formato Unicode se o sinalizador MAPI_UNICODE estiver definido no parâmetro ulFlags .

cbEntryID

[in] O tamanho, em bytes, do identificador de entrada apontado pelo parâmetro lpEntryID .

lpEntryID

[in] Um ponteiro para o identificador de entrada do arquivo de mensagens. Transmitir nulo em lpEntryID indica que um arquivo de mensagens ainda não foi selecionado e que as caixas de diálogo que permitem ao utilizador selecionar um arquivo de mensagens podem ser apresentadas.

ulFlags

[in] Uma máscara de bits de sinalizadores que controla a forma como o início de sessão é executado. Os seguintes sinalizadores podem ser definidos:

MAPI_DEFERRED_ERRORS

A chamada pode ser efetuada com êxito mesmo que o objeto subjacente não esteja disponível para a implementação de chamadas. Se o objeto não estiver disponível, uma chamada subsequente para o objeto poderá gerar um erro.

MAPI_UNICODE

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

MDB_NO_DIALOG

Impede a apresentação de caixas de diálogo de início de sessão. Se este sinalizador estiver definido, o valor de erro MAPI_E_LOGON_FAILED é devolvido se o início de sessão não for bem-sucedido. Se este sinalizador não estiver definido, o fornecedor do arquivo de mensagens pode pedir ao utilizador para corrigir um nome ou palavra-passe, inserir um disco ou executar outras ações necessárias para estabelecer ligação ao arquivo.

MDB_NO_MAIL

O arquivo de mensagens não deve ser utilizado para enviar ou receber correio. O sinalizador sinaliza MAPI para não notificar o spooler MAPI de que este arquivo de mensagens está a ser aberto. Se este sinalizador estiver definido e o arquivo de mensagens estiver fortemente associado a um fornecedor de transporte, o fornecedor não precisa de chamar o método IMAPISupport::SpoolerNotify .

MDB_TEMPORARY

Inicia sessão no arquivo para que as informações possam ser obtidas programaticamente a partir da secção de perfil, sem utilizar caixas de diálogo. Este sinalizador indica à MAPI que o arquivo não deve ser adicionado à tabela do arquivo de mensagens e que o arquivo não pode ser permanente. Se este sinalizador estiver definido, os fornecedores de arquivo de mensagens não precisam de chamar o método IMAPISupport::ModifyProfile .

MDB_WRITE

Pede permissão de leitura/escrita.

lpInterface

[in] Um ponteiro para o identificador da interface (IID) para o arquivo de mensagens para iniciar sessão. Transmitir nulo indica que a interface MAPI do arquivo de mensagens (IMsgStore) é devolvida. O parâmetro lpInterface também pode ser definido como um identificador para uma interface adequada para o arquivo de mensagens (por exemplo, IID_IUnknown ou IID_IMAPIProp).

lpcbSpoolSecurity

[fora] Um ponteiro para a variável na qual o fornecedor de arquivo devolve o tamanho, em bytes, dos dados de validação no parâmetro lppbSpoolSecurity .

lppbSpoolSecurity

[fora] Um ponteiro para o ponteiro para os dados de validação devolvidos. Estes dados de validação são fornecidos para que o método IMSProvider::SpoolerLogon possa registar o spooler MAPI no mesmo arquivo que o fornecedor do arquivo de mensagens.

lppMAPIError

[fora] Um ponteiro para um ponteiro para a estrutura MAPIERROR devolvida, se existir, que contém informações de versão, componente e contexto para um erro. O parâmetro lppMAPIError pode ser definido como nulo se não existir uma estrutura MAPIERROR para devolver.

lppMSLogon

[fora] Um ponteiro para o ponteiro para o objeto de início de sessão do arquivo de mensagens para a MAPI iniciar sessão.

lppMDB

[fora] Um ponteiro para o ponteiro para o objeto de arquivo de mensagens para que o spooler MAPI e as aplicações cliente iniciem sessão.

Valor de retorno

S_OK

A chamada foi efetuada com êxito e devolveu o valor ou valores esperados.

MAPI_E_FAILONEPROVIDER

Este fornecedor não consegue iniciar sessão, mas este erro não deve desativar o serviço.

MAPI_E_LOGON_FAILED

Não foi possível estabelecer uma sessão de início de sessão.

MAPI_E_UNCONFIGURED

O perfil não contém informações suficientes para a conclusão do início de sessão. Quando este valor é devolvido, MAPI chama a função de ponto de entrada de serviço de mensagens do fornecedor do arquivo de mensagens.

MAPI_E_USER_CANCEL

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

MAPI_E_UNKNOWN_CPID

O servidor não está configurado para suportar a página de código do cliente.

MAPI_E_UNKNOWN_LCID

O servidor não está configurado para suportar as informações de região do cliente.

MAPI_W_ERRORS_RETURNED

A chamada foi efetuada com êxito, mas o fornecedor do arquivo de mensagens tem informações de erro disponíveis. Quando este aviso é devolvido, a chamada deve ser processada com êxito. Para testar este aviso, utilize a macro HR_FAILED . Para obter mais informações, veja Utilizar Macros para Processamento de Erros. Para obter as informações de erro do fornecedor, chame o método IMAPISession::GetLastError .

Comentários

A MAPI chama o método IMSProvider::Logon para realizar a maioria do processamento necessário para obter acesso a um arquivo de mensagens. Os fornecedores de arquivo de mensagens validam todas as credenciais de utilizador necessárias para aceder a um arquivo específico e devolver um objeto de arquivo de mensagens no parâmetro lppMDB no qual o spooler MAPI e as aplicações cliente podem iniciar sessão.

Além do objeto de arquivo de mensagens devolvido para a utilização do spooler MAPI e do cliente, o fornecedor também devolve um objeto de início de sessão do arquivo de mensagens para a MAPI utilizar no controlo do arquivo aberto. O objeto de início de sessão do arquivo de mensagens e o objeto de arquivo de mensagens devem estar estreitamente ligados dentro do fornecedor do arquivo de mensagens para que cada um possa afetar o outro. A utilização do objeto de arquivo e do objeto de início de sessão deve ser idêntica; deve existir uma correspondência um-para-um entre o objeto de início de sessão e o objeto de arquivo, de modo a que os objetos atuem como se fossem um objeto que expõe duas interfaces. Os dois objetos também devem ser criados em conjunto e libertados em conjunto.

O objeto de suporte MAPI, criado pela MAPI e transmitido ao fornecedor no parâmetro lpMAPISup , fornece acesso às funções na MAPI de que o fornecedor necessita. Estas incluem funções que guardam e obtêm informações de perfil, livros de endereços de acesso, etc. O ponteiro lpMAPISup pode ser diferente para cada loja aberta. Ao processar chamadas para um arquivo de mensagens após o início de sessão, o fornecedor da loja deve utilizar a variável lpMAPISup específica desse arquivo. Para qualquer chamada de Início de Sessão que abra um arquivo de mensagens e consiga criar um objeto de início de sessão do arquivo de mensagens, o fornecedor tem de guardar um ponteiro no objeto de suporte MAPI no objeto de início de sessão do arquivo e chamar o método IUnknown::AddRef para adicionar uma referência para o objeto de suporte.

O parâmetro ulUIParam deve ser utilizado se o fornecedor apresentar caixas de diálogo durante a chamada de Início de Sessão. No entanto, as caixas de diálogo não devem ser apresentadas se ulFlags contiver o sinalizador MDB_NO_DIALOG. Se uma interface de utilizador precisar de ser chamada, mas ulFlags não a permitir ou se, por outro motivo, não for possível apresentar uma interface de utilizador, o fornecedor deverá devolver MAPI_E_LOGON_FAILED. Se o Início de Sessão apresentar uma caixa de diálogo e o utilizador cancelar o início de sessão, normalmente ao clicar no botão Cancelar da caixa de diálogo, o fornecedor deverá devolver MAPI_E_USER_CANCEL.

O parâmetro lpEntryID pode ser nulo ou apontar para um identificador de entrada de arquivo não substituído que este arquivo de mensagens criou anteriormente. Se lpEntryID apontar para um identificador de entrada não substituído, esse identificador de entrada pode ser proveniente de um de vários locais:

Pode ser um identificador de entrada que o fornecedor da loja encapsulava e escrevia anteriormente na secção de perfil como uma propriedade PR_ENTRYID (PidTagEntryId).
Pode ser um identificador de entrada que o fornecedor encapsulava e devolveu anteriormente a um cliente de chamada como uma propriedade de PR_STORE_ENTRYID (PidTagStoreEntryId).
Pode ser um identificador de entrada que o fornecedor encapsulava e devolveu anteriormente a um cliente de chamada como a propriedade PR_ENTRYID de um objeto de arquivo de mensagens.

Em qualquer um destes casos, é possível que o identificador de entrada tenha sido criado num computador diferente daquele que está a ser utilizado atualmente.

Quando lpEntryID não é nulo, deve conter todas as informações necessárias para identificar e localizar o arquivo de mensagens. Estas informações podem incluir nomes de volumes de rede, números de telefone, nomes de contas de utilizador, etc. Se não for possível efetuar a ligação ao arquivo com os dados no identificador de entrada, o fornecedor da loja deverá apresentar uma caixa de diálogo que permita ao utilizador selecionar o arquivo a abrir. Pode ser necessária uma caixa de diálogo, por exemplo, se o nome de um servidor tiver sido mudado, se um nome de conta tiver sido alterado ou se partes da rede não estiverem disponíveis.

Quando lpEntryID é nulo, o arquivo de mensagens a utilizar ainda não foi selecionado. O fornecedor ainda pode aceder a um arquivo sem apresentar uma caixa de diálogo se suportar outros métodos para especificar o arquivo. Por exemplo, o fornecedor pode verificar o respetivo ficheiro de inicialização ou pode procurar propriedades adicionais que foram colocadas na respetiva secção de perfil do respetivo serviço de mensagens na configuração.

Se um fornecedor verificar que todas as informações necessárias não estão no perfil, deverá devolver MAPI_E_UNCONFIGURED. A MAPI chamará então a função de ponto de entrada do serviço de mensagens do fornecedor para permitir que o utilizador selecione um arquivo ou até mesmo para criar um e para introduzir um nome de conta e palavra-passe, conforme necessário. A MAPI cria automaticamente uma nova secção de perfil para um novo arquivo; esta nova secção de perfil pode ser temporária ou permanente, consoante a forma como foi adicionada. Se o fornecedor da loja chamar o método IMAPISupport::ModifyProfile , a nova secção de perfil torna-se permanente e o arquivo é adicionado à lista de arquivos de mensagens devolvidos pelo método IMAPISession::GetMsgStoresTable .

O parâmetro lpInterface especifica o IID da interface necessária para o objeto de arquivo aberto recentemente. Transmitir nulo em lpInterface especifica que a interface de arquivo de mensagens MAPI, IMsgStore, é necessária. A transmissão do objeto de arquivo de mensagens, IID_IMsgStore, também especifica que iMsgStore é necessário. Se IID_IUnknown for transmitido em lpInterface, o fornecedor deve abrir o arquivo utilizando qualquer interface derivada de IUnknown que seja melhor para o fornecedor (mais uma vez, este é normalmente IMsgStore). Quando IID_IUnknown for aprovada, a implementação da chamada utiliza o método IUnknown::QueryInterface para selecionar uma interface após a operação de abertura do arquivo ser concluída com êxito.

A chamada IMSProvider::Logon deve devolver informações suficientes, como um caminho para o arquivo e credenciais para aceder ao arquivo, para permitir que o spooler MAPI inicie sessão no mesmo arquivo que o fornecedor da loja sem apresentar uma caixa de diálogo. Os parâmetros lpcbSpoolSecurity e lppbSpoolSecurity são utilizados para devolver estas informações. O fornecedor atribui a memória para estes dados ao transmitir um ponteiro para uma memória intermédia no parâmetro lpfAllocateBuffer da função MSProviderInit; o fornecedor coloca o tamanho desta memória intermédia em lpcbSpoolSecurity.

MAPI liberta esta memória intermédia quando apropriado. Se o início de sessão do spooler MAPI para o arquivo puder ser feito apenas a partir das informações na secção de perfil, o fornecedor pode devolver nulo em lppbSpoolSecurity e 0 para o tamanho da informação em lpcbSpoolSecurity. O início de spooler MAPI ocorre como parte de um processo diferente do início de sessão da loja; uma vez que a memória intermédia que contém as informações transmitidas é copiada entre processos, pode não estar na memória na mesma localização para o processo do spooler MAPI como para o processo do fornecedor de loja. Por conseguinte, um fornecedor não deve colocar endereços nesta memória intermédia. Para obter mais informações sobre o início de spooler MAPI, veja o método IMSProvider::SpoolerLogon .

A maioria dos fornecedores de arquivo utiliza o método IMAPISession::OpenProfileSection do objeto de suporte transmitido no parâmetro lpMAPISup para guardar e obter credenciais e opções de utilizador. O OpenProfileSection permite que um fornecedor de loja guarde informações arbitrárias adicionais numa secção de perfil e associe-as a um determinado recurso. Por exemplo, um fornecedor de loja pode guardar o nome da conta de utilizador e a palavra-passe associadas a um recurso e quaisquer caminhos ou outras informações necessárias para aceder a esse recurso.

As propriedades com identificadores de propriedade 0x6600 através de 0x67FF são propriedades seguras disponíveis para o fornecedor para utilização própria para armazenar dados privados em secções de perfil. Para obter mais informações sobre a utilização de propriedades em objetos de secção de perfil, veja o método IProfSect : IMAPIProp .

Além de quaisquer dados privados em propriedades com identificadores 0x6600 através de 0x67FF, o fornecedor de loja deve fornecer informações para a propriedade PR_DISPLAY_NAME (PidTagDisplayName) na secção de perfil. Deve ser colocada PR_DISPLAY_NAME o nome a apresentar do próprio fornecedor — uma cadeia de identificação (por exemplo, "Arquivo de Informações Pessoais da Microsoft") que é apresentada aos utilizadores para que possam distinguir este arquivo de mensagens de outras pessoas às quais possam ter acesso. PR_DISPLAY_NAME geralmente contém um nome de servidor, nome de conta de utilizador ou caminho.

Algumas propriedades da secção de perfil estão visíveis na tabela de arquivo de mensagens; outras pessoas são visíveis durante a configuração, instalação e configuração do subsistema MAPI. Normalmente, o fornecedor fornece informações para estas propriedades visíveis para uma nova secção de perfil, que ainda não inclui credenciais guardadas ou informações privadas, e quando descobre que as informações de propriedade foram alteradas. Para obter mais informações sobre secções de perfil, consulte IMAPISupport::OpenProfileSection.

Depois de iniciar sessão com êxito num utilizador e antes de regressar à MAPI, o fornecedor de loja deve criar a matriz de propriedades para a linha de estado do recurso e chamar o método IMAPISupport::ModifyStatusRow .

As chamadas de início de sessão que abrem arquivos de mensagens que já estão abertas para a sessão MAPI atual ignoram grande parte do processamento descrito anteriormente. Estas chamadas não criam linhas de estado, devolvem objetos de início de sessão do arquivo de mensagens, chamam AddRef para o objeto de suporte MAPI ou devolvem dados para o início de spooler MAPI. Estas chamadas devolvem S_OK e devolvem um objeto de arquivo de mensagens com a interface pedida.

Para detetar tais chamadas, o fornecedor deve manter uma lista no objeto de fornecedor de arquivo de mensagens de lojas já aberta para este objeto de fornecedor. Ao processar uma chamada de Início de Sessão, o fornecedor deve analisar esta lista de lojas abertas e determinar se o arquivo com sessão iniciada já está aberto. Se estiver, as credenciais de utilizador não precisam de ser verificadas e a apresentação de uma caixa de diálogo deve ser evitada, se possível. Se as caixas de diálogo tiverem de ser apresentadas, o fornecedor deve verificar as informações devolvidas para ver se um arquivo foi aberto uma segunda vez. Além disso, o fornecedor deve verificar se existem aberturas duplicadas com lpEntryID no início do processamento de chamadas de início de sessão.

O processamento padrão de uma chamada de Início de Sessão que acede a um arquivo aberto é o seguinte:

O fornecedor de loja chama AddRef para o objeto de arquivo existente se a nova interface que está a ser pedida for a mesma que a interface do arquivo existente. Caso contrário, chama QueryInterface para obter a nova interface. Se o arquivo não suportar a nova interface, o fornecedor deverá devolver o valor de erro MAPI_E_INTERFACE_NOT_SUPPORTED.
O fornecedor devolve um ponteiro para a interface necessária do objeto de arquivo existente no lppMDB.
O fornecedor devolve nulo em lppMSLogon.
O fornecedor não deve abrir o perfil do objeto de suporte transmitido na chamada. Além disso, não deve registar um identificador exclusivo do fornecedor, registar uma linha de estado ou devolver dados de início de sessão do spooler MAPI.
O fornecedor não deve chamar AddRef para o objeto de suporte, porque não requer um ponteiro para o objeto.

Sempre que possível, os fornecedores devem devolver as cadeias de erro e aviso adequadas para chamadas de Início de Sessão, uma vez que fazê-lo facilita consideravelmente a sobrecarga dos utilizadores na determinação do motivo pelo qual algo não funcionou. Para devolver estas cadeias, um fornecedor define os membros na estrutura MAPIERROR . A MAPI procura, utiliza e lança a estrutura MAPIERROR se for devolvida por um fornecedor.

A memória para esta estrutura MAPIERROR deve ser alocada através da memória intermédia transmitida em lpfAllocateBuffer na chamada MSProviderInit . Quaisquer cadeias de erro contidas na estrutura devolvida devem estar no formato Unicode se MAPI_UNICODE estiver definida no ulFlags de Início de Sessão; caso contrário, devem estar no conjunto de carateres ANSI.

Para a maioria dos valores de erro devolvidos a partir do Início de Sessão, MAPI desativa os serviços de mensagens aos quais pertence o fornecedor com falhas. A MAPI não chamará quaisquer fornecedores que pertençam a esses serviços durante o ciclo de vida da sessão MAPI. Por outro lado, quando o Início de Sessão devolve o valor de erro MAPI_E_FAILONEPROVIDER do respetivo início de sessão, a MAPI não desativa o serviço de mensagens ao qual o fornecedor pertence. O início de sessão deve devolver MAPI_E_FAILONEPROVIDER se encontrar um erro que não justifique a desativação de todo o serviço durante o ciclo de vida da sessão. Por exemplo, um fornecedor pode devolver este erro quando não permite a apresentação de uma interface de utilizador e uma palavra-passe necessária está indisponível.

Se um fornecedor devolver MAPI_E_UNCONFIGURED do início de sessão, a MAPI chamará a função de entrada do serviço de mensagens do fornecedor e, em seguida, repetirá o início de sessão. A MAPI transmite MSG_SERVICE_CONFIGURE como contexto para dar ao serviço a oportunidade de se configurar. Se o cliente tiver optado por permitir uma interface de utilizador no início de sessão, o serviço pode apresentar a respetiva folha de propriedades de configuração para que o utilizador possa introduzir informações de configuração.