IMAPIProp::OpenProperty

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Retorna um ponteiro para uma interface que pode ser usada para acessar uma propriedade.

HRESULT OpenProperty(
  ULONG ulPropTag,
  LPCIID lpiid,
  ULONG ulInterfaceOptions,
  ULONG ulFlags,
  LPUNKNOWN FAR * lppUnk
);

Parâmetros

Ulproptag

[in] A marca de propriedade para a propriedade a ser acessada. O identificador e o tipo devem ser incluídos na marca de propriedade.

lpiid

[in] Um ponteiro para o identificador para que a interface seja usada para acessar a propriedade. O parâmetro lpiid não deve ser nulo.

ulInterfaceOptions

[in] Dados relacionados à interface identificada pelo parâmetro lpiid .

ulFlags

[in] Um bitmask de sinalizadores que controla o acesso à propriedade. Os seguintes sinalizadores podem ser definidos:

MAPI_CREATE

Se a propriedade não existir, ela deverá ser criada. Se a propriedade existir, o valor atual da propriedade deverá ser descartado. Quando um chamador define o sinalizador MAPI_CREATE, ele também deve definir o sinalizador MAPI_MODIFY.

MAPI_DEFERRED_ERRORS

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

MAPI_MODIFY

MAPI_MODIFY é necessário nessas situações:

Ao abrir uma propriedade de fluxo, como IID_IStream, para modificá-la.
Ao abrir um anexo de mensagem inserido, como PR_ATTACH_DATA_OBJ aberto com IID_IMessage, para modificá-lo.

Lppunk

[out] Um ponteiro para a interface solicitada a ser usada para acesso à propriedade.

Valor de retorno

S_OK

O ponteiro de interface solicitado foi retornado com êxito.

MAPI_E_INTERFACE_NOT_SUPPORTED

A interface solicitada não tem suporte para essa propriedade.

MAPI_E_NO_ACCESS

O chamador tem permissões insuficientes para acessar a propriedade.

MAPI_E_NO_SUPPORT

O objeto não pode fornecer acesso a essa propriedade por meio da interface solicitada.

MAPI_E_NOT_FOUND

A propriedade solicitada não existe e MAPI_CREATE não foi definida no parâmetro ulFlags .

MAPI_E_INVALID_PARAMETER

O tipo de propriedade na marca é definido como PT_UNSPECIFIED.

Comentários

O método IMAPIProp::OpenProperty fornece acesso a uma propriedade por meio de uma interface específica. OpenProperty é uma alternativa aos métodos IMAPIProp::GetProps e IMAPIProp::SetProps . Quando GetProps ou SetProps falharem porque a propriedade é muito grande ou muito complexa, chame OpenProperty. OpenProperty normalmente é usado para acessar propriedades do tipo PT_OBJECT.

Notas para chamadores

Para acessar anexos de mensagem, abra a propriedade PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) com um identificador de interface diferente, dependendo do tipo de anexo. A tabela a seguir descreve como chamar OpenProperty para os diferentes tipos de anexos:

Tipo de anexo	Identificador de interface a ser usado
Binário	IID_IStream
Cadeia de caracteres	IID_IStream
Mensagem	IID_IMessage
OLE 2.0	IID_IStreamDocfile

IStreamDocfile é um derivado da interface IStream baseada em um arquivo composto OLE 2.0. IStreamDocfile é a melhor opção para acessar anexos OLE 2.0 porque envolve a menor quantidade de sobrecarga. Você pode usar IID_IStreamDocFile para aquelas propriedades que contêm dados armazenados no armazenamento estruturado disponíveis por meio da interface IStorage .

Para obter mais informações sobre como usar o OpenProperty com anexos, consulte a propriedade PR_ATTACH_DATA_OBJ e Abrir um Anexo.

Não use o ponteiro IStream que você recebe para chamar o método Seek ou SetSize , a menos que você use uma variável de posição ou tamanho zero. Além disso, não dependa do valor do parâmetro de saída plibNewPosition retornado da chamada Seek .

Se você chamar OpenProperty para acessar uma propriedade com a interface IStream , use apenas essa interface para fazer alterações nela. Não tente atualizar a propriedade com nenhum dos outros métodos IMAPIProp : IUnknown , como SetProps ou IMAPIProp::D eleteProps.

Não tente abrir uma propriedade com OpenProperty mais de uma vez. Os resultados são indefinidos porque podem variar de provedor para provedor.

Se você precisar modificar a propriedade a ser aberta, defina o sinalizador MAPI_MODIFY. Se você não tiver certeza se o objeto dá suporte à propriedade, mas você acha que deve, defina os sinalizadores MAPI_CREATE e MAPI_MODIFY. Sempre que MAPI_CREATE estiver definido, MAPI_MODIFY também deve ser definido.

Você é responsável por reformular o ponteiro de interface retornado no parâmetro lppUnk para um que é apropriado para a interface especificada no parâmetro lpiid . Você também deve usar o ponteiro retornado para chamar o método IUnknown::Release quando terminar com ele.

Às vezes, definir os sinalizadores no parâmetro ulFlags não é suficiente para indicar o tipo de acesso à propriedade necessária. Você pode colocar dados adicionais, como sinalizadores, no parâmetro ulInterfaceOptions . Esses dados dependem da interface. Algumas interfaces (como iStream) a usam e outras não. Por exemplo, quando você abrir uma propriedade a ser modificada com o IStream, defina o sinalizador STGM_WRITE no parâmetro ulInterfaceOptions , além de MAPI_MODIFY. Ao abrir uma tabela usando a interface IMAPITable , você pode definir ulInterfaceOptions como MAPI_UNICODE para indicar se as colunas na tabela que contêm propriedades de cadeia de caracteres devem estar no formato Unicode.

Referência do MFCMAPI

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

Arquivo	Função	Comentário
StreamEditor.cpp	CStreamEditor::ReadTextStreamFromProperty	O MFCMAPI usa o método IMAPIProp::OpenProperty para recuperar uma interface de fluxo para grandes propriedades binárias e de texto.

Compartilhar via