libmapi/IMessage.c File Reference

Operations on messages. More...

#include <libmapi/libmapi.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 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 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.
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 emsmdb_transaction(), mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 emsmdb_transaction(), 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, 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(), emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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/