IMAPIProp::OpenProperty

The IMAPIProp::OpenProperty method returns a pointer to an interface to be used to access a property.

Quick Info

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

Parameters

ulPropTag

[in] Property tag for the property to be accessed. Both the identifier and the type must be included in the property tag.

lpiid

[in] Pointer to the identifier for the interface to be used to access the property. The lpiid parameter must not be NULL.

ulInterfaceOptions

[in] Data that relates to the interface identified by the lpiid parameter.

ulFlags

[in] Bitmask of flags that controls access to the property. The following flags can be set:

MAPI_CREATE: If the property does not exist, it should be created. If the property does exist, the current value of the property should be discarded. When a caller sets the MAPI_CREATE flag, it should also set the MAPI_MODIFY flag.
MAPI_DEFERRED_ERRORS: Allows OpenProperty to return successfully, possibly before the object is fully accessible to the caller. If the object is not accessible, making a subsequent object call can result in an error.
MAPI_MODIFY: Requests read/write access to the property. The default access is read-only. MAPI_MODIFY must be set when MAPI_CREATE is set.

lppUnk

[out] Pointer to the requested interface to be used for property access.

Return Values

S_OK: The requested interface pointer was successfully returned.
MAPI_E_INTERFACE_NOT_SUPPORTED: The requested interface is not supported for this property.
MAPI_E_NO_ACCESS: The caller has insufficient permissions to access the property.
MAPI_E_NO_SUPPORT: The object cannot provide access to this property through the requested interface.
MAPI_E_NOT_FOUND: The requested property does not exist and MAPI_CREATE was not set in the ulFlags parameter.
MAPI_E_INVALID_PARAMETER: The property type in the tag is set to PT_UNSPECIFIED.

Remarks

The IMAPIProp::OpenProperty method provides access to a property through a particular interface. OpenProperty is an alternate to GetProps and SetProps. When either GetProps or SetProps fails because the property is too large or too complex, call OpenProperty. OpenProperty is commonly used to access properties of type PT_OBJECT.

Notes to Callers

To access message attachments, open the PR_ATTACH_DATA_OBJ 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	IID_IStreamDocfile

IStreamDocfile is a derivative of IStream that is based on an OLE 2 compound file. IStreamDocfile is the best choice for accessing OLE 2 attachments because it involves the least amount of overhead. IID_IStreamDocFile can be used for those properties that contain data stored in structured storage accessible through the IStorage interface.

For more information about using OpenProperty with attachments, see PR_ATTACH_DATA_OBJ 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 methods such as SetProps or 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 if the object supports the property but 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 appropriate for the interface specified in the lpiid parameter. You must also use the returned pointer to call its IUnknown::Release method when you have 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 place 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 opening a property to be modified with IStream, set the STGM_WRITE flag in the ulInterfaceOptions parameter in addition to MAPI_MODIFY. When opening a table using IMAPITable, you can set ulInterfaceOptions to MAPI_UNICODE to indicate whether or not the columns in the table that hold string properties should be in Unicode format.