IMAPIFolder.c File Reference

Folder related functions. More...

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

Functions

_PUBLIC_ enum MAPISTATUS CopyFolder (mapi_object_t *obj_folder, mapi_object_t *obj_src, mapi_object_t *obj_dst, char *NewFolderName, bool UseUnicode, bool WantRecursive)
 
_PUBLIC_ enum MAPISTATUS CreateFolder (mapi_object_t *obj_parent, enum FOLDER_TYPE ulFolderType, const char *name, const char *comment, uint32_t ulFlags, mapi_object_t *obj_child)
 
_PUBLIC_ enum MAPISTATUS CreateMessage (mapi_object_t *obj_folder, mapi_object_t *obj_message)
 
_PUBLIC_ enum MAPISTATUS DeleteFolder (mapi_object_t *obj_parent, mapi_id_t FolderId, uint8_t DeleteFolderFlags, bool *PartialCompletion)
 
_PUBLIC_ enum MAPISTATUS DeleteMessage (mapi_object_t *obj_folder, mapi_id_t *id_messages, uint32_t cn_messages)
 
_PUBLIC_ enum MAPISTATUS EmptyFolder (mapi_object_t *obj_folder)
 
_PUBLIC_ enum MAPISTATUS GetMessageStatus (mapi_object_t *obj_folder, mapi_id_t msgid, uint32_t *ulStatus)
 
_PUBLIC_ enum MAPISTATUS HardDeleteMessage (mapi_object_t *obj_folder, mapi_id_t *id_messages, uint16_t cn_messages)
 
_PUBLIC_ enum MAPISTATUS HardDeleteMessagesAndSubfolders (mapi_object_t *obj_folder)
 
_PUBLIC_ enum MAPISTATUS MoveCopyMessages (mapi_object_t *obj_src, mapi_object_t *obj_dst, mapi_id_array_t *message_id, bool WantCopy)
 
_PUBLIC_ enum MAPISTATUS MoveFolder (mapi_object_t *obj_folder, mapi_object_t *obj_src, mapi_object_t *obj_dst, char *NewFolderName, bool UseUnicode)
 
_PUBLIC_ enum MAPISTATUS SetMessageStatus (mapi_object_t *obj_folder, mapi_id_t msgid, uint32_t ulNewStatus, uint32_t ulNewStatusMask, uint32_t *ulOldStatus)
 
_PUBLIC_ enum MAPISTATUS SetReadFlags (mapi_object_t *obj_folder, uint8_t ReadFlags, uint16_t MessageIdCount, uint64_t *MessageIds)
 

Detailed Description

Folder related functions.

Function Documentation

_PUBLIC_ enum MAPISTATUS CopyFolder ( mapi_object_t obj_folder,
mapi_object_t obj_src,
mapi_object_t obj_dst,
char *  NewFolderName,
bool  UseUnicode,
bool  WantRecursive 
)

Copy a folder

Parameters
obj_folderthe folder to copy
obj_srcsource object where the folder to copy is stored
obj_dstdestination object where the folder will be copied
NewFolderNamethe new folder name in the destination folder
UseUnicodewhether the folder name is unicode encoded or not
WantRecursivewhether we should copy folder's subdirectories or not
Returns
MAPI_E_SUCCESS on success, otherwise MAPI error.
Note
Developer 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
OpenFolder, MoveFolder

References emsmdb_transaction_wrapper(), get_utf8_utf16_conv_length(), mapi_object_get_handle(), mapi_object_get_id(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS CreateFolder ( mapi_object_t obj_parent,
enum FOLDER_TYPE  ulFolderType,
const char *  name,
const char *  comment,
uint32_t  ulFlags,
mapi_object_t obj_child 
)

Create a folder

The function creates a folder (defined with its name, comment and type) within a specified folder.

Parameters
obj_parentthe folder to create the new folder in
ulFolderTypethe type of the folder
namethe name of the new folder
commentthe comment associated with the new folder
ulFlagsflags associated with folder creation
obj_childpointer to the newly created folder

ulFlags possible values:

  • MAPI_UNICODE: use UNICODE folder name and comment
  • OPEN_IF_EXISTS: open the folder if it already exists

ulFolderType possible values:

  • FOLDER_GENERIC
  • FOLDER_SEARCH
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
OpenFolder, DeleteFolder, EmptyFolder, GetLastError

References emsmdb_transaction_wrapper(), get_utf8_utf16_conv_length(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_init(), mapi_object_set_handle(), mapi_object_set_id(), mapi_object_set_logon_id(), mapi_object_set_session(), MAPI_UNICODE, OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS CreateMessage ( mapi_object_t obj_folder,
mapi_object_t obj_message 
)

The function creates a message in the specified folder, and returns a pointer on this message.

Parameters
obj_folderthe folder to create the message in.
obj_messagepointer to the newly created 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
OpenFolder, DeleteMessage, GetLastError

References emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_id(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), mapi_object_set_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS DeleteFolder ( mapi_object_t obj_parent,
mapi_id_t  FolderId,
uint8_t  DeleteFolderFlags,
bool *  PartialCompletion 
)

Delete a folder

The function deletes a specified folder.

Parameters
obj_parentthe folder containing the folder to be deleted
FolderIdthe ID of the folder to delete
DeleteFolderFlagscontrol DeleteFolder operation behavior
PartialCompletionpointer on a boolean value which specify whether the operation was partially completed or not

Possible values for DeleteFolderFlags are:

  1. DEL_MESSAGES Delete all the messages in the folder
  2. DEL_FOLDERS Delete the subfolder and all of its subfolders
  3. DELETE_HARD_DELETE Hard delete the folder
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
OpenFolder, CreateFolder, EmptyFolder, GetLastError

References emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS DeleteMessage ( mapi_object_t obj_folder,
mapi_id_t id_messages,
uint32_t  cn_messages 
)

Delete one or more messages

This function deletes one or more messages based on their ids from a specified folder.

Parameters
obj_folderthe folder to delete messages from
id_messagesthe list of ids
cn_messagesthe number of messages in the id list.
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
OpenFolder, CreateMessage, GetLastError

References emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS EmptyFolder ( mapi_object_t obj_folder)

Empty the contents of a folder

This function empties (clears) the contents of a specified folder.

Parameters
obj_folderthe folder to empty
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
OpenFolder, CreateFolder, DeleteFolder, GetLastError

References emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS GetMessageStatus ( mapi_object_t obj_folder,
mapi_id_t  msgid,
uint32_t *  ulStatus 
)

Obtain the status associated with a message

This function obtains the status associated with a message in the given folder.

Parameters
obj_folderthe folder where the message is located
msgidthe message ID
ulStatusthe message status
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

References emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS HardDeleteMessage ( mapi_object_t obj_folder,
mapi_id_t id_messages,
uint16_t  cn_messages 
)

Hard delete one or more messages

This function hard deletes one or more messages based on their ids from a specified folder.

Parameters
obj_folderthe folder to hard delete messages from
id_messagesthe list of ids
cn_messagesthe number of messages in the id list.
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: the parent folder was not valid
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See Also
OpenFolder, CreateMessage, GetLastError

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

_PUBLIC_ enum MAPISTATUS HardDeleteMessagesAndSubfolders ( mapi_object_t obj_folder)

Hard delete the contents of a folder, including subfolders

This function empties (clears) the contents of a specified folder.

Parameters
obj_folderthe folder to empty
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: obj_folder is not valid
  • MAPI_E_CALL_FAILED: A network problem was encountered during the transaction
See Also
DeleteFolder, EmptyFolder

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

_PUBLIC_ enum MAPISTATUS MoveCopyMessages ( mapi_object_t obj_src,
mapi_object_t obj_dst,
mapi_id_array_t message_id,
bool  WantCopy 
)

Copy or Move a message from a folder to another

Parameters
obj_srcThe source folder
obj_dstThe destination folder
message_idpointer to container object for message ids.
WantCopyboolean value, defines whether the operation is a copy or a move

Possible values for WantCopy:

  1. 0: Move
  2. 1: Copy
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
OpenFolder, GetLastError

References mapi_id_array::count, emsmdb_transaction_wrapper(), mapi_id_array_get(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS MoveFolder ( mapi_object_t obj_folder,
mapi_object_t obj_src,
mapi_object_t obj_dst,
char *  NewFolderName,
bool  UseUnicode 
)

Moves a folder

Parameters
obj_folderthe folder to move
obj_srcsource object where the folder to move is stored
obj_dstdestination object where the folder will be moved
NewFolderNamethe new folder name in the destination folder
UseUnicodewhether the folder name is unicode encoded or not
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
OpenFolder, CopyFolder

References emsmdb_transaction_wrapper(), get_utf8_utf16_conv_length(), mapi_object_get_handle(), mapi_object_get_id(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS SetMessageStatus ( mapi_object_t obj_folder,
mapi_id_t  msgid,
uint32_t  ulNewStatus,
uint32_t  ulNewStatusMask,
uint32_t *  ulOldStatus 
)

Set the status associated with a message

This function sets the status associated with a message in the given folder.

Parameters
obj_folderthe folder where the message is located
msgidthe message ID
ulNewStatusthe new status to be assigned
ulNewStatusMaskbitmask of flags hat is applied to the new status indicating the flags to be set
ulOldStatuspointer on the previous status of the message

ulNewStatusMask possible values:

  • MSGSTATUS_DELMARKED: the message is marked for deletion
  • MSGSTATUS_HIDDEN: the message is not to be displayed
  • MSGSTATUS_HIGHLIGHTED: the message is to be displayed highlighted
  • MSGSTATUS_REMOTE_DELETE: the message has been marked for deletion on the remote message store without downloading to the local client.
  • MSGSTATUS_REMOTE_DOWNLOAD: the message has been marked for downloading from the remote message store to the local client.
  • MSGSTATUS_TAGGED: The message has been tagged for a client-defined purpose.
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

References emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS SetReadFlags ( mapi_object_t obj_folder,
uint8_t  ReadFlags,
uint16_t  MessageIdCount,
uint64_t *  MessageIds 
)

Set the Read Flags on one or more messages

Parameters
obj_folderthe folder containing the messages to change
ReadFlagsa bitmap of flags controlling the changes to PR_PROPERTY_FLAGS
MessageIdCountthe number of messages in the MessageIds array
MessageIdsan array of message ids to set Read flags for

Note that the obj_folder argument is the object corresponding to the folder containing the messages (e.g. the result of CreateFolder() or OpenFolder(). It is not the content table of that folder (unlike SetMessageReadFlag().)

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
SetMessageReadFlags for a slightly different version, working on a single message

References emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.


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/