IMAPISession::QueryIdentity

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Retorna o identificador de entrada do objeto que fornece a identidade primária para a sessão.

HRESULT QueryIdentity(
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Parâmetros

lpcbEntryID

[out] Um ponteiro para a contagem de bytes no identificador de entrada apontado pelo parâmetro lppEntryID .

lppEntryID

[out] Um ponteiro para um ponteiro para o identificador de entrada do objeto que fornece a identidade primária.

Valor de retorno

S_OK

A identidade primária foi retornada com êxito.

MAPI_W_NO_SERVICE

A chamada foi bem-sucedida, mas não há identidade primária para a sessão. Quando esse aviso é retornado, a chamada deve ser tratada como bem-sucedida. Para testar esse aviso, use a macro HR_FAILED . Para obter mais informações, confira Usando macros para tratamento de erros.

Comentários

O método IMAPISession::QueryIdentity recupera a identidade primária da sessão atual e retorna o valor por meio do parâmetro lppEntryID . A identidade primária é um objeto, normalmente um usuário de mensagens, que representa o usuário de uma sessão. lppEntryID retorna a identidade primária de um objeto IMailUser , que também é armazenado como a propriedade PidTagEntryID . Você pode usar o valor retornado em lppEntryID para abrir um objeto IMailUser usando IMAPISession::OpenEntry.

Embora muitos provedores de serviços em vários serviços de mensagens possam fornecer a identidade primária para uma sessão, o MAPI designa um único provedor de serviços. O provedor de serviços que fornece a identidade primária define os seguintes itens:

O sinalizador STATUS_PRIMARY_IDENTITY na propriedade PR_RESOURCE_FLAGS (PidTagResourceFlags).
A propriedade PR_IDENTITY_DISPLAY (PidTagIdentityDisplay).
A propriedade PR_IDENTITY_ENTRYID (PidTagIdentityEntryId).
A propriedade PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey).

Se o provedor de serviços que fornece a identidade primária pertencer a um serviço de mensagem, os outros provedores de serviços no serviço de mensagem também definirão as propriedades PR_IDENTITY. Essas propriedades são publicadas na tabela status da sessão.

Se possível, QueryIdentity retornará o valor da propriedade PR_IDENTITY_ENTRYID da linha status marcada com STATUS_PRIMARY_IDENTITY. Se a propriedade PR_IDENTITY_ENTRYID estiver ausente da linha de identidade primária, QueryIdentity retornará um identificador de entrada único criado com outras informações dessa linha.

Se o sinalizador de STATUS_PRIMARY_IDENTITY estiver ausente de todas as colunas de PR_RESOURCE_FLAG na tabela status, QueryIdentity retornará o primeiro identificador de entrada encontrado. Quando não há um identificador de entrada apropriado para retornar, QueryIdentity é bem-sucedido com o MAPI_W_NO_SERVICE de aviso e aponta lppEntryID para um identificador de entrada codificado em código.

Notas para chamadores

Você pode chamar o método IMsgServiceAdmin::SetPrimaryIdentity para atribuir a um serviço de mensagem a tarefa de fornecer a identidade primária da sessão.

Outra maneira de recuperar a identidade primária é pesquisando a tabela status para a linha com as colunas PR_RESOURCE_FLAGS definidas como STATUS_PRIMARY_IDENTITY. Para obter mais informações sobre essa maneira alternativa de recuperar informações de identidade, consulte Tabela de Status e Objetos de Status.

Quando terminar de usar o identificador de entrada para a identidade primária retornada pela QueryIdentity, libere sua memória chamando a função MAPIFreeBuffer .

Para obter mais informações sobre identidade em geral, consulte Identidade Primária mapi.

Para obter mais informações sobre como recuperar a identidade da sessão MAPI, consulte Recuperando identidade primária e de provedor.

Referência do MFCMAPI

Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.

Arquivo	Função	Comentário
MainDlg.cpp	CMainDlg::OnQueryIdentity	O MFCMAPI usa o método IMAPISession::QueryIdentity para abrir a entrada do catálogo de endereços para a identidade primária da sessão.