IMessage::OpenAttach

The IMessage::OpenAttach method opens an attachment.

Quick Info

See IMessage : IMAPIProp.

HRESULT OpenAttach(
  ULONG ulAttachmentNum,   
  LPCIID lpInterface,   
  ULONG ulFlags,        
  LPATTACH FAR * lppAttach  
);
 

Parameters

ulAttachmentNum

[in] Index number of the attachment to open, as stored in the attachment's PR_ATTACH_NUM property. This index number uniquely identifies the attachment in the message and is valid only in the context of the message.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the attachment. Passing NULL results in the attachment's standard interface, or IAttach, being returned.

ulFlags

[in] Bitmask of flags that controls how the attachment is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the attachment be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the attachment should be opened with read/write access; if the client has read-only access, the attachment should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenAttach to return successfully, possibly before the attachment is fully accessible to the calling client. If the attachment is not accessible, making a subsequent call to it can result in an error.

MAPI_MODIFY

Requests read/write access. By default, attachments are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.

lppAttach

[out] Pointer to a pointer to the open attachment.

Return Value

S_OK

The attachment was successfully opened.

Remarks

The IMessage::OpenAttach method opens a message's attachment.

Notes to Callers

To open an attachment, you must have access to its attachment number — or PR_ATTACH_NUM property. Call IMessage::GetAttachmentTable to retrieve the message's attachment table and locate the row that represents the attachment to be opened. See Opening an Attachment for more information.

Do not try to open one attachment multiple times; the results are undefined and dependent on the message store provider.

You can request that the attachment be opened in read/write mode, rather than the default read-only mode. However, whether or not the attachment will actually be opened in read/write mode is up to the message store provider. You can either attempt to modify the attachment, preparing to handle possible failure, or check the level of access that was granted by retrieving the attachment's PR_ACCESS_LEVEL property, if it is available.