libmapi/IMessage.c File Reference

Operations on messages. More...

#include "libmapi/libmapi.h"
#include "libmapi/libmapi_private.h"

Functions

_PUBLIC_ enum MAPISTATUS AbortSubmit (mapi_object_t *obj_store, mapi_object_t *obj_folder, mapi_object_t *obj_message)
_PUBLIC_ enum MAPISTATUS CreateAttach (mapi_object_t *obj_message, mapi_object_t *obj_attach)
_PUBLIC_ enum MAPISTATUS DeleteAttach (mapi_object_t *obj_message, uint32_t AttachmentID)
_PUBLIC_ enum MAPISTATUS GetAttachmentTable (mapi_object_t *obj_message, mapi_object_t *obj_table)
_PUBLIC_ enum MAPISTATUS GetRecipientTable (mapi_object_t *obj_message, struct SRowSet *SRowSet, struct SPropTagArray *SPropTagArray)
_PUBLIC_ enum MAPISTATUS GetValidAttach (mapi_object_t *obj_message, uint16_t *NumAttachments, uint32_t **AttachmentIds)
uint16_t mapi_recipients_RecipientFlags (struct SRow *aRow)
_PUBLIC_ enum MAPISTATUS ModifyRecipients (mapi_object_t *obj_message, struct SRowSet *SRowSet)
_PUBLIC_ enum MAPISTATUS OpenAttach (mapi_object_t *obj_message, uint32_t AttachmentID, mapi_object_t *obj_attach)
_PUBLIC_ enum MAPISTATUS OpenEmbeddedMessage (mapi_object_t *obj_attach, mapi_object_t *obj_embeddedmsg, enum OpenEmbeddedMessage_OpenModeFlags ulFlags)
_PUBLIC_ enum MAPISTATUS ReadRecipients (mapi_object_t *obj_message, uint32_t RowId, uint8_t *RowCount, struct ReadRecipientRow **RecipientRows)
_PUBLIC_ enum MAPISTATUS RemoveAllRecipients (mapi_object_t *obj_message)
_PUBLIC_ enum MAPISTATUS SaveChangesMessage (mapi_object_t *parent, mapi_object_t *obj_message, uint8_t SaveFlags)
_PUBLIC_ enum MAPISTATUS SetMessageReadFlag (mapi_object_t *obj_folder, mapi_object_t *obj_child, uint8_t flags)
_PUBLIC_ enum MAPISTATUS SetRecipientType (struct SRow *aRow, enum ulRecipClass RecipClass)
_PUBLIC_ enum MAPISTATUS SubmitMessage (mapi_object_t *obj_message)
_PUBLIC_ enum MAPISTATUS TransportSend (mapi_object_t *obj_message, struct mapi_SPropValue_array *lpProps)

Detailed Description

Operations on messages.


Function Documentation

_PUBLIC_ enum MAPISTATUS AbortSubmit ( mapi_object_t *  obj_store,
mapi_object_t *  obj_folder,
mapi_object_t *  obj_message 
)

Aborts a previous message submission.

Parameters:
obj_storethe store object
obj_folderthe folder object where the message has been submitted
obj_messagethe submitted message object
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
  • MAPI_E_UNABLE_TO_ABORT: The operation can not be aborted
  • MAPI_E_NOT_IN_QUEUE: The message is no longer in the message store's spooler queue
  • MAPI_E_NO_SUPPORT: the server object associated with the input handle index in the server object table is not of type Logon or the current logon session is a public logon.
See also:
SubmitMessage

References mapi_object_get_handle(), mapi_object_get_id(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS CreateAttach ( mapi_object_t *  obj_message,
mapi_object_t *  obj_attach 
)

Create a new attachment

This function creates a new attachment to an existing message.

Parameters:
obj_messagethe message to attach to
obj_attachthe attachment

Both objects need to exist before you call this message. obj_message should be a valid message on the server. obj_attach needs to be initialised.

   enum MAPISTATUS         retval;
   mapi_object_t           obj_message;
   mapi_object_t           obj_attach;

   ... open or create the obj_message ...

   mapi_object_init(&obj_attach);
   retval = CreateAttach(&obj_message, &obj_attach);
   ... check the return value ...

   ... use SetProps() to set the attachment up ...
   ... perhaps OpenStream() / WriteStream() / CommitStream() on obj_attach ...

   // Save the changes to the attachment and then the message
   retval = SaveChangesAttachment(&obj_message, &obj_attach, KeepOpenReadOnly);
   ... check the return value ...
   retval = SaveChangesMessage(&obj_folder, &obj_message, KeepOpenReadOnly);
   ... check the return value ...
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
CreateMessage, GetAttachmentTable, OpenAttach, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), and mapi_object_set_session().

_PUBLIC_ enum MAPISTATUS DeleteAttach ( mapi_object_t *  obj_message,
uint32_t  AttachmentID 
)

Delete an attachment from a message

This function deletes one attachment from a message. The attachment to be deleted is specified by its PR_ATTACH_NUM

Parameters:
obj_messagethe message to operate on
AttachmentIDthe attachment number
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
CreateMessage, GetAttachmentTable, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS GetAttachmentTable ( mapi_object_t *  obj_message,
mapi_object_t *  obj_table 
)

Retrieve the attachment table for a message

Parameters:
obj_messagethe message
obj_tablethe attachment table for the message
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
CreateMessage, OpenMessage, CreateAttach, OpenAttach, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), and mapi_object_set_session().

_PUBLIC_ enum MAPISTATUS GetRecipientTable ( mapi_object_t *  obj_message,
struct SRowSet *  SRowSet,
struct SPropTagArray *  SPropTagArray 
)

Returns the message recipient table

Parameters:
obj_messagethe message to receive recipients from
SRowSetpointer to the recipient table
SPropTagArraypointer to the array of properties listed in the recipient table
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
See also:
OpenMessage
_PUBLIC_ enum MAPISTATUS GetValidAttach ( mapi_object_t *  obj_message,
uint16_t *  NumAttachments,
uint32_t **  AttachmentIds 
)

Get the valid attachment IDs for a message

This function returns the list of valid attachment IDs for a message. You can then use these IDs with the OpenAttach and DeleteAttach functions.

Parameters:
obj_messagethe message to operate on
NumAttachmentsthe number of attachments for the message
AttachmentIdsarray of attachment Ids

The AttachmentIds array has NumAttachments elements.

Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_INVALID_PARAMETER: a parameter is incorrect (e.g. null pointer)
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
OpenAttach, DeleteAttach

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

uint16_t mapi_recipients_RecipientFlags ( struct SRow *  aRow)

RecipientFlags bitmask calculation for RecipientRows structure.

Parameters:
aRowpointer to the SRow structures with the properties to pass to ModifyRecipients.

According to MS-OXCDATA 2.9.3.1 RecipientFlags structure, the bitmask can be represented as the following:

0 3 4 5 6 7 8 9 10 11 15 16 +------+---+---+---+---+---+---+---+---+----------+---+ | Type | E | D | T | S | R | N | U | I | Reserved | O | +------+---+---+---+---+---+---+---+---+----------+---+

Type: (0x7 mask) 3-bit enumeration describing the Address Type (PR_ADDRTYPE) E: (0x8) Email address included (PR_SMTP_ADDRESS) D: (0x10) Display Name included (PR_DISPLAY_NAME) T: (0x20) Transmittable Display Name included (PR_TRANSMITTABLE_DISPLAY_NAME) S: (0x40) If Transmittable Display Name is the same than Display Name (D == T) R: (0x80) Different transport is responsible for delivery N: (0x100) Recipient does not support receiving Rich Text messages U: (0x200) If we are using Unicode properties I: (0x400) If Simple Display Name is included (PR_7BIT_DISPLAY_NAME) Reserved: Must be zero O: (0x8000) Non-standard address type is used

The PidTag property to bitmask mapping was unclear for some fields. mapiproxy between Outlook 2003 and Exchange 2010 has been used for this purpose.

For further information about PidTagAddressType, refer to [MS-OXCMAIL] section 2.1.1.9

Returns:
uint16_t holding the RecipientFlags value. 0 is returned when an inconsistency or a failure occurs

Referenced by ModifyRecipients().

_PUBLIC_ enum MAPISTATUS ModifyRecipients ( mapi_object_t *  obj_message,
struct SRowSet *  SRowSet 
)

Adds, deletes or modifies message recipients

Parameters:
obj_messagethe message to change the recipients for
SRowSetthe recipients to add
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.

When using this function, take care to ensure that the properties that are present on the first row in the rowset are also present in all the following rows. If any are missing, this function will suffer NDR errors. This includes making sure that any string properties are present in the same encoding (e.g. if you use PR_SMTP_ADDRESS_UNICODE on the first row, don't provide PR_SMTP_ADDRESS on subsequent rows).

Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
Bug:
ModifyRecipients can only add recipients.
See also:
CreateMessage, ResolveNames, SetRecipientType, GetLastError

References cast_mapi_SPropValue(), get_utf8_utf16_conv_length(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), and mapi_recipients_RecipientFlags().

_PUBLIC_ enum MAPISTATUS OpenAttach ( mapi_object_t *  obj_message,
uint32_t  AttachmentID,
mapi_object_t *  obj_attach 
)

Open an attachment to a message

This function opens one attachment from a message. The attachment to be opened is specified by its PR_ATTACH_NUM.

Parameters:
obj_messagethe message to operate on
AttachmentIDthe attachment number
obj_attachthe resulting attachment object
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
CreateMessage, CreateAttach, GetAttachmentTable, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), and mapi_object_set_session().

_PUBLIC_ enum MAPISTATUS OpenEmbeddedMessage ( mapi_object_t *  obj_attach,
mapi_object_t *  obj_embeddedmsg,
enum OpenEmbeddedMessage_OpenModeFlags  ulFlags 
)

Opens an embedded message object and retrieves a MAPI object that can be used to get or set properties on the embedded message.

This function essentially takes an attachment and gives you back a message.

Parameters:
obj_attachthe attachment object
obj_embeddedmsgthe embedded message
ulFlagsaccess rights on the embedded message

Possible ulFlags values:

  • 0x0: read only access
  • 0x1: Read / Write access
  • 0x2: Create
        ... assume we have a message - obj_message ...
        // Initialise the attachment object
        mapi_object_init(&obj_attach);

        // Create an attachment to the message
        retval = CreateAttach(&obj_message, &obj_attach);
        ... check the return value ...

        // use SetProps() to set the attachment up, noting the special PR_ATTACHM_METHOD property
        attach[0].ulPropTag = PR_ATTACH_METHOD;
        attach[0].value.l = ATTACH_EMBEDDED_MSG;
        attach[1].ulPropTag = PR_RENDERING_POSITION;
        attach[1].value.l = 0;
        retval = SetProps(&obj_attach, 0, attach, 2);
        ... check the return value ...

        // Initialise the embedded message object
        mapi_object_init(&obj_embeddedmsg);
        retval = OpenEmbeddedMessage(&obj_attach, &obj_embeddedmsg, MAPI_CREATE);
        ... check the return value ...

        // Fill in the embedded message properties, just like any other message (e.g. resulting from CreateMessage())

        // Save the changes to the embedded message
        retval = SaveChangesMessage(&obj_message, &obj_embeddedmsg, KeepOpenReadOnly);
        ... check the return value ...

        // Save the changes to the attachment
        retval = SaveChangesAttachment(&obj_message, &obj_attach, KeepOpenReadOnly);
        ... check the return value ...

        // Save the changes to the original message
        retval = SaveChangesMessage(&obj_folder, &obj_message, KeepOpenReadOnly);
        ... check the return value ...
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_INVALID_PARAMETER: obj_store is undefined
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code.
See also:
CreateAttach, OpenMessage, GetLastError

References emsmdb_get_SRow(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), mapi_object_set_session(), SPropTagArray_add(), and SRow_addprop().

_PUBLIC_ enum MAPISTATUS ReadRecipients ( mapi_object_t *  obj_message,
uint32_t  RowId,
uint8_t *  RowCount,
struct ReadRecipientRow **  RecipientRows 
)

Read Recipients from a message

Parameters:
obj_messagethe message we want to read recipients from
RowIdthe row index we start reading recipients from
RowCountpointer on the number of recipients
RecipientRowspointer on the recipients array
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
ModifyRecipients, RemoveAllRecipients, GetRecipientTable, OpenMessage

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS RemoveAllRecipients ( mapi_object_t *  obj_message)

Deletes all recipients from a message

Parameters:
obj_messagethe message we want to remove all recipients from
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
ModifyRecipients, ReadRecipients

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS SaveChangesMessage ( mapi_object_t *  parent,
mapi_object_t *  obj_message,
uint8_t  SaveFlags 
)

Saves all changes to the message

Parameters:
parentthe parent object for the message
obj_messagethe message to save
SaveFlagsspecify how the save operation behaves

Possible value for SaveFlags:

  1. KeepReadOnly Keep the Message object open with read-only access
  2. KeepOpenReadWrite Keep the Message object open with read-write access
  3. ForceSave Commit the changes and keep the message object open with read-write access
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
SetProps, ModifyRecipients, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), and mapi_object_set_id().

_PUBLIC_ enum MAPISTATUS SetMessageReadFlag ( mapi_object_t *  obj_folder,
mapi_object_t *  obj_child,
uint8_t  flags 
)

Clear or set the MSGFLAG_READ flag for a given message

This function clears or sets the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property of a given message.

Parameters:
obj_folderthe folder to operate in
obj_childthe message to set flags on
flagsthe new flags (MSGFLAG_READ) value
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
OpenMessage, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS SetRecipientType ( struct SRow *  aRow,
enum ulRecipClass  RecipClass 
)

Set the type of a recipient

The function sets the recipient type (RecipClass) in the aRow parameter. ResolveNames should be used to fill the SRow structure.

Parameters:
aRowthe row to set
RecipClassthe type of recipient to set on the specified row
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_INVALID_PARAMETER: The aRow parameter was not set properly.
See also:
ResolveNames, ModifyRecipients, GetLastError

References SRow_addprop().

_PUBLIC_ enum MAPISTATUS SubmitMessage ( mapi_object_t *  obj_message)

Saves all changes to the message and marks it as ready for sending.

This function saves all changes made to a message and marks it ready to be sent.

Parameters:
obj_messagethe message to mark complete
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note:
Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  • MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See also:
CreateMessage, SetProps, ModifyRecipients, SetRecipientType, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS TransportSend ( mapi_object_t *  obj_message,
struct mapi_SPropValue_array *  lpProps 
)

Sends the specified Message object out for message delivery.

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().


Creative Commons License
Creative Commons Attribution icon Creative Commons Share Alike icon
This content is licensed under the Creative Commons
Attribution ShareAlike License v. 3.0:
http://creativecommons.org/licenses/by-sa/3.0/