IMAPIProp::OpenProperty
Published: July 16, 2012
Returns a pointer to an interface that can be used to access a property.
HRESULT OpenProperty( ULONG ulPropTag, LPCIID lpiid, ULONG ulInterfaceOptions, ULONG ulFlags, LPUNKNOWN FAR * lppUnk );
The IMAPIProp::OpenProperty method provides access to a property through a particular interface. OpenProperty is an alternative to the IMAPIProp::GetProps and IMAPIProp::SetProps methods. When either GetProps or SetProps fails because the property is too large or too complex, call OpenProperty. OpenProperty is typically used to access properties of type PT_OBJECT.
To access message attachments, open the PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) property with a different interface identifier, depending on the type of attachment. The following table describes how to call OpenProperty for the different types of attachments:
|
Type of attachment |
Interface identifier to use |
|---|---|
|
Binary |
IID_IStream |
|
String |
IID_IStream |
|
Message |
IID_IMessage |
|
OLE 2.0 |
IID_IStreamDocfile |
IStreamDocfile is a derivative of the IStream interface that is based on an OLE 2.0 compound file. IStreamDocfile is the best choice for accessing OLE 2.0 attachments because it involves the least amount of overhead. You can use IID_IStreamDocFile for those properties that contain data stored in structured storage available through the IStorage interface.
For more information about how to use OpenProperty with attachments, see the PR_ATTACH_DATA_OBJ property and Opening an Attachment.
Do not use the IStream pointer that you receive to call either its Seek or SetSize method unless you use a zero position or size variable. Also, do not rely on the value of the plibNewPosition output parameter returned from the Seek call.
If you call OpenProperty to access a property with the IStream interface, use only that interface to make changes to it. Do not attempt to update the property with any of the other IMAPIProp : IUnknown methods, such as SetProps or IMAPIProp::DeleteProps.
Do not try to open a property with OpenProperty more than once. The results are undefined because they can vary from provider to provider.
If you need to modify the property to be opened, set the MAPI_MODIFY flag. If you are not sure whether the object supports the property but you think it should, set the MAPI_CREATE and MAPI_MODIFY flags. Whenever MAPI_CREATE is set, MAPI_MODIFY must also be set.
You are responsible for recasting the interface pointer returned in the lppUnk parameter to one that is appropriate for the interface specified in the lpiid parameter. You must also use the returned pointer to call its IUnknown::Release method when you are finished with it.
Sometimes setting the flags in the ulFlags parameter is not enough to indicate the type of access to the property that is required. You can put additional data, such as flags, in the ulInterfaceOptions parameter. This data is interface dependent. Some interfaces (such as IStream) use it, and others do not. For example, when you open a property to be modified with IStream, set the STGM_WRITE flag in the ulInterfaceOptions parameter in addition to MAPI_MODIFY. When you open a table by using the IMAPITable interface, you can set ulInterfaceOptions to MAPI_UNICODE to indicate whether the columns in the table that hold string properties should be in Unicode format.
