IMAPISession::OpenEntry

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Abre um objeto e retorna um ponteiro de interface para acesso adicional.

HRESULT OpenEntry(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parâmetros

cbEntryID

[in] A contagem de bytes no identificador de entrada apontada pelo parâmetro lpEntryID .

Lpentryid

[in] Um ponteiro para o identificador de entrada do objeto a ser aberto.

lpInterface

[in] Um ponteiro para o IID (identificador de interface) que representa a interface a ser usada para acessar o objeto aberto. Passar NULL retorna a interface padrão do objeto. Por exemplo, se o objeto a ser aberto for uma mensagem, a interface padrão será IMessage; para pastas, é IMAPIFolder. As interfaces padrão para objetos do catálogo de endereços são IDistList para uma lista de distribuição e IMailUser para um usuário de mensagens.

ulFlags

[in] Um bitmask de sinalizadores que controla como o objeto é aberto. Os seguintes sinalizadores podem ser usados:

MAPI_BEST_ACCESS

Solicita que o objeto seja aberto usando as permissões de rede máximas permitidas para o usuário e o acesso máximo do aplicativo cliente. Por exemplo, se o cliente tiver permissão de leitura/gravação, o objeto deverá ser aberto com permissão de leitura/gravação; se o cliente tiver permissão somente leitura, o objeto deverá ser aberto com permissão somente leitura.

MAPI_CACHE_OK

Use todos os meios, incluindo os livros de endereços offline, para executar a resolução de nomes.

MAPI_CACHE_ONLY

Use apenas o catálogo de endereços offline para executar a resolução de nomes. Por exemplo, você pode usar esse sinalizador para permitir que um aplicativo cliente abra a GAL (lista de endereços global) no modo de troca armazenado em cache e acesse uma entrada no catálogo de endereços do cache sem criar tráfego entre o cliente e o servidor. Esse sinalizador tem suporte apenas pelo Provedor de Catálogo de Endereços do Exchange.

MAPI_DEFERRED_ERRORS

Permite que o OpenEntry retorne com êxito, possivelmente antes que o objeto esteja totalmente disponível para o cliente de chamada. Se o objeto não estiver disponível, fazer uma chamada de objeto subsequente poderá causar um erro.

MAPI_MODIFY

Solicita permissão de leitura/gravação. Por padrão, os objetos são abertos com permissão somente leitura e os clientes não devem trabalhar na suposição de que a permissão de leitura/gravação é concedida.

MAPI_NO_CACHE

Não use o catálogo de endereços offline para executar a resolução de nomes. Esse sinalizador tem suporte apenas pelo Provedor de Catálogo de Endereços do Exchange.

SHOW_SOFT_DELETES

Mostrar itens que atualmente são marcados como excluídos suavemente (ou seja, eles estão na fase de tempo de retenção de item excluído).

lpulObjType

[out] Um ponteiro para o tipo do objeto aberto.

Lppunk

[out] Um ponteiro para um ponteiro para o objeto aberto.

Valor de retorno

S_OK

O objeto foi aberto com êxito.

MAPI_E_NO_ACCESS

Foi feita uma tentativa de modificar um objeto somente leitura ou uma tentativa de acessar um objeto para o qual o usuário tem permissões insuficientes.

MAPI_E_NOT_FOUND

Não há um objeto associado ao identificador de entrada passado no parâmetro lpEntryID .

MAPI_E_UNKNOWN_ENTRYID

O identificador de entrada passado no parâmetro lpEntryID está em um formato irreconhecível. Esse valor normalmente será retornado se o provedor de serviços que contém o objeto não estiver aberto.

Comentários

O método IMAPISession::OpenEntry abre um repositório de mensagens ou objeto de catálogo de endereços, retornando um ponteiro para uma interface que pode ser usada para acessar o objeto.

Notas para chamadores

Importante

Ao abrir entradas de pasta em um repositório público, como pastas e mensagens, use IMsgStore::OpenEntry em vez de IMAPISession::OpenEntry. Isso garante que as pastas públicas funcionem corretamente quando várias contas do Exchange são definidas em um perfil.

Chame IMAPISession::OpenEntry somente quando você não souber que tipo de objeto está abrindo. Se você souber que está abrindo uma pasta ou uma mensagem, chame IMsgStore::OpenEntry. Se você souber que está abrindo um contêiner de catálogo de endereços, um usuário de mensagens ou uma lista de distribuição, chame IAddrBook::OpenEntry. Esses métodos mais específicos são mais rápidos que IMAPISession::OpenEntry.

O MAPI abre todos os objetos com permissão somente leitura, a menos que você defina o sinalizador MAPI_MODIFY ou MAPI_BEST_ACCESS no parâmetro ulFlags . A configuração de um desses sinalizadores não garante um tipo específico de acesso; as permissões concedidas dependem do provedor de serviços, do nível de acesso e do objeto. Para determinar o nível de acesso do objeto aberto, recupere sua propriedade PR_ACCESS_LEVEL (PidTagAccessLevel).

Chamar IMAPISession::OpenEntry e definir lpEntryID para apontar para o identificador de entrada de um repositório de mensagens é o mesmo que chamar o método IMAPISession::OpenMsgStore com o conjunto de sinalizadores MDB_NO_DIALOG. As configurações de sinalizador também são equivalentes, exceto que para solicitar permissão de leitura/gravação com OpenMsgStore, você deve definir o sinalizador MDB_WRITE em vez de MAPI_MODIFY.

Verifique o valor retornado no parâmetro lpulObjType para determinar se o tipo de objeto retornado é o esperado. Se o tipo de objeto não for o tipo esperado, selecione o ponteiro do parâmetro lppUnk para um ponteiro do tipo apropriado. Por exemplo, se você estiver abrindo uma pasta, lance lppUnk em um ponteiro do tipo LPMAPIFOLDER.