MAPIClientLibraries 2.0 API Documentation

- Main Page
- Related Pages
- Data Structures
- Files
- Examples

- File List
- Globals

Functions
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_store | the store object
  obj_folder | the folder object where the message has been submitted
  obj_message | the 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_message | the message to attach to
  obj_attach | the 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_message | the message to operate on
  AttachmentID | the 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_message | the message
  obj_table | the 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_message | the message to receive recipients from
  SRowSet | pointer to the recipient table
  SPropTagArray | pointer 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_message | the message to operate on
  NumAttachments | the number of attachments for the message
  AttachmentIds | array 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

  aRow | pointer 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_message | the message to change the recipients for
  SRowSet | the 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_message | the message to operate on
  AttachmentID | the attachment number
  obj_attach | the 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_attach | the attachment object
  obj_embeddedmsg | the embedded message
  ulFlags | access 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_message | the message we want to read recipients from
  RowId | the row index we start reading recipients from
  RowCount | pointer on the number of recipients
  RecipientRows | pointer 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_message | the 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

  parent | the parent object for the message
  obj_message | the message to save
  SaveFlags | specify 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_folder | the folder to operate in
  obj_child | the message to set flags on
  flags | the 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

  aRow | the row to set
  RecipClass | the 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_message | the 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().

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