Compartilhar via

OpenIMsgOnIStg

  • Artigo

Aplica-se a: Outlook 2013 | Outlook 2016

Cria um novo objeto IMessage em cima de um objeto OLE IStorage existente, a ser usado em uma sessão de mensagem.

Propriedade Valor
Arquivo de cabeçalho:
 Imessage.h
Implementado por:
 MAPI
Chamado por:
 Aplicativos cliente e provedores de serviços
 
SCODE OpenIMsgOnIStg(
  LPMSGSESS lpMsgSess,
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPALLOCATEMORE lpAllocateMore,
  LPFREEBUFFER lpFreeBuffer,
  LPMALLOC lpmalloc,
  LPVOID lpMapiSup,
  LPSTORAGE lpStg,
  MSGCALLRELEASE FAR * lpfMsgCallRelease,
  ULONG ulCallerData,
  ULONG ulFlags,
  LPMESSAGE FAR * lppMsg
);

Parâmetros

lpMsgSess

[in] Ponteiro para um objeto de sessão de mensagem no qual o novo objeto IMessage-on-IStorage deve ser criado.

lpAllocateBuffer

[in] Ponteiro para a função MAPIAllocateBuffer , a ser usada para alocar memória.

lpAllocateMore

[in] Ponteiro para a função MAPIAllocateMore , a ser usada para alocar memória adicional.

lpFreeBuffer

[in] Ponteiro para a função MAPIFreeBuffer , a ser usada para liberar memória.

lpMalloc

[in] Ponteiro para um objeto alocador de memória expondo a interface OLE IMalloc . A interface IMessage precisa usar esse método de alocação ao trabalhar com interfaces como IStorage e IStream.

lpMapiSup

[in] Ponteiro opcional para um objeto de suporte mapi que um provedor de serviços pode usar para chamar os métodos da interface IMAPISupport : IUnknown .

lpStg

[in, out] Ponteiro para um objeto OLE IStorage que está aberto e tem permissão de leitura ou de leitura/gravação. Como o IMessage não dá suporte ao acesso somente gravação, o OpenIMsgOnIStg não aceita um objeto de armazenamento aberto no modo somente gravação.

lpfMsgCallRelease

[in] Ponteiro opcional para uma função de retorno de chamada com base no protótipo MSGCALLRELEASE que MAPI deve chamar após a última versão no objeto IMessage-on-IStorage.

ulCallerData

[in] Dados de chamador salvos pelo MAPI com o objeto IMessage-on-IStorage e passados para a função de retorno de chamada baseada em MSGCALLRELEASE. Os dados fornecem contexto sobre o objeto IMessage que está sendo lançado e o objeto IStorage em cima do qual ele foi criado.

ulFlags

[in] O bitmask de sinalizadores usado para controlar se o método OLE IStorage::Commit é chamado quando o aplicativo cliente ou provedor de serviços chama o método IMessage::SaveChanges . Os seguintes sinalizadores podem ser definidos:

IMSG_NO_ISTG_COMMIT

O método OLE IStorage::Commit não deve ser chamado quando o cliente ou provedor chama SaveChanges.

MAPI_UNICODE

Habilita a criação de arquivos unicode .msg. O arquivo IMessage resultante mostra STORE_UNICODE_OK em seu PR_STORE_SUPPORT_MASK e dá suporte a propriedades Unicode.

Observação

O sinalizador MAPI_UNICODE só tem suporte nessa função no Outlook 2003 ou superior.

lppMsg

[out] Ponteiro para um ponteiro para o objeto IMessage aberto.

Valor de retorno

S_OK

A chamada foi bem-sucedida e retornou o valor ou valores esperados.

Comentários

Os atributos de propriedade só podem ser acessados em objetos de propriedade, ou seja, objetos que implementam a interface IMAPIProp : IUnknown . Para disponibilizar propriedades MAPI em um objeto de armazenamento estruturado OLE, OpenIMsgOnIStg cria um objeto IMessage : IMAPIProp na parte superior do objeto OLE IStorage . Os atributos de propriedade nesses objetos podem ser definidos ou alterados com SetAttribIMsgOnIStg e recuperados com GetAttribIMsgOnIStg.

Notas para chamadores

Uma sessão de mensagem deve ser aberta com OpenIMsgSession antes que OpenIMsgOnIStg seja chamado. O fornecimento de um parâmetro lpMsgSess válido garante que a nova mensagem seja criada em uma sessão de mensagem para que ela seja fechada quando a sessão for fechada. Se lpMsgSess for NULL, a mensagem será criada independentemente de qualquer sessão de mensagem. Se o aplicativo cliente ou o provedor de serviços que criou a mensagem não a liberar, bem como todos os seus anexos e tabelas abertas, a memória será vazada e poderá fazer com que o aplicativo seja encerrado.

O MAPI usa as funções apontadas por lpAllocateBuffer, lpAllocateMore e lpFreeBuffer para a maioria da alocação e alocação de memória, em particular para alocar memória para uso por aplicativos cliente ao chamar interfaces de objeto como IMAPIProp::GetProps e IMAPITable::QueryRows. Os ponteiros lpAllocateBuffer, lpAllocateMore e lpFreeBuffer são opcionais quando a função OpenIMsgOnIStg é chamada com um parâmetro lpMapiSup válido.

Como ele está lidando com um objeto OLE subjacente, o MAPI também precisa usar a alocação de memória OLE. Para obter mais informações sobre objetos de armazenamento estruturados OLE e alocação de memória OLE, consulte a Referência do Programador OLE.

Se um valor válido for fornecido para lpMapiSup, o IMessage oferecerá suporte aos sinalizadores MAPI_DIALOG e ATTACH_DIALOG chamando o método IMAPISupport::D oProgressDialog para fornecer uma interface de usuário de progresso para os métodos IMAPIProp::CopyTo e IMessage::D eleteAttach . Além disso, o método IMessage::ModifiRecipients tenta converter identificadores de entrada de curto prazo em identificadores de entrada de longo prazo chamando o método IMAPISupport::OpenAddressBook e fazendo chamadas no objeto do catálogo de endereços resultante. Se NULL for passado para lpMapiSup, o IMessage ignorará MAPI_DIALOG e ATTACH_DIALOG e armazenará identificadores de entrada de curto prazo sem conversão.

O objeto IStorage apontado pelo parâmetro lpStg deve ser aberto no modo STGM_READ ou STGM_READWRITE. Se o modo STGM_READWRITE for usado, o modo STGM_TRANSACTED também deverá ser definido.

A função de retorno de chamada apontada pelo parâmetro lpfMsgCallRelease é opcional; se fornecido, ele deve ser baseado no protótipo da função MSGCALLRELEASE . A interface IMessage a chama quando a contagem de referência do objeto IMessage-on-IStorage é definida como zero pela última chamada para o método Release. A função de retorno de chamada é comumente usada para liberar a interface IStorage subjacente. O IMessage não tentará acessar o objeto IStorage apontado pelo parâmetro lpStg depois de fazer o retorno de chamada.

Alguns clientes ou provedores podem gravar dados adicionais no objeto IStorage além do que o próprio IMessage grava quando seu método SaveChanges é chamado. O cliente ou provedor pode usar o sinalizador IMSG_NO_ISTG_COMMIT para impedir que o IMessage chame o método OLE IStorage::Commit durante o processamento de uma chamada SaveChanges ; nesse caso, o cliente ou provedor deve confirmar o objeto IStorage quando os dados adicionais forem gravados. Para ajudar nisso, a implementação do IMessage garante nomear todas as sub-estruturas que ela cria no objeto IStorage começando com a cadeia de caracteres "__", ou seja, com dois sublinhados. O cliente ou provedor pode evitar colisões de nome mantendo seus nomes de substorage fora desse namespace.

O MAPI não define o comportamento de várias operações abertas executadas em um subobjeto de uma mensagem, como um anexo, um fluxo ou uma mensagem inserida. O MAPI atualmente permite um subobjeto que já está aberto para ser aberto mais uma vez, mas o MAPI executa a operação aberta incrementando a contagem de referência para o objeto aberto existente e retornando-o ao cliente ou provedor que chamou o método IMessage::OpenAttach ou IMAPIProp::OpenProperty . Isso significa que o acesso solicitado para a primeira operação aberta em um subobjecto é o acesso fornecido para todas as operações abertas subsequentes, independentemente do acesso solicitado pelas operações.

O procedimento correto para colocar uma mensagem em um anexo é chamar o método IMAPIProp::OpenProperty com um identificador de interface de IID_IMessage. O OpenProperty atualmente também dá suporte à criação de anexos de mensagem disponíveis diretamente na interface OLE IStorage , ou seja, usando o identificador de interface IID_IStorage. Há suporte para o acesso ao IStorage para permitir uma maneira fácil de colocar um documento do Microsoft Word em um anexo sem convertê-lo em ou na interface OLE IStream. No entanto, o IMessage pode não se comportar de maneira previsível se OpenIMsgOnIStg for passado um ponteiro IStorage para os dados de anexo e, em seguida, os objetos forem liberados na ordem errada.

Referência do MFCMAPI

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

Arquivo Função Comentário
File.cpp
 LoadMSGToMessage
 O MFCMAPI usa o método OpenIMsgOnIStg para abrir uma interface IMessage na parte superior do . Arquivo MSG para que o arquivo possa ser manipulado com MAPI.

Confira também