IMAPIProp::OpenProperty
Applies to: Office 2010 | Outlook 2010 | Visual Studio
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
);
Parameters
ulPropTag
[in] The property tag for the property to be accessed. Both the identifier and the type must be included in the property tag.lpiid
[in] A 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] A 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 available to the caller. If the object is not available, making a subsequent object call can raise an error.MAPI_MODIFY
MAPI_MODIFY is required in these situations:When opening a stream property, such as IID_IStream, to modify it.
When opening an embedded message attachment, such as PR_ATTACH_DATA_OBJ opened with IID_IMessage, to modify it.
lppUnk
[out] A pointer to the requested interface to be used for property access.
Return Value
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 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.
Notes to Callers
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.
MFCMAPI Reference
For MFCMAPI sample code, see the following table.
File |
Function |
Comment |
|---|---|---|
StreamEditor.cpp |
CStreamEditor::ReadTextStreamFromProperty |
MFCMAPI uses the IMAPIProp::OpenProperty method to retrieve a stream interface for large text and binary properties. |
See Also
Reference
IMAPISupport::IStorageFromStream