libmapi/IMAPIFolder.c File Reference

Folder related functions. More...

#include <libmapi/libmapi.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_folder the folder to copy
obj_src source object where the folder to copy is stored
obj_dst destination object where the folder will be copied
NewFolderName the new folder name in the destination folder
UseUnicode whether the folder name is unicode encoded or not
WantRecursive whether 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_parent the folder to create the new folder in
ulFolderType the type of the folder
name the name of the new folder
comment the comment associated with the new folder
ulFlags flags associated with folder creation
obj_child pointer 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_folder the folder to create the message in.
obj_message pointer 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_parent the folder containing the folder to be deleted
FolderId the ID of the folder to delete
DeleteFolderFlags control DeleteFolder operation behavior
PartialCompletion pointer 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_folder the folder to delete messages from
id_messages the list of ids
cn_messages the 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_folder the 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_folder the folder where the message is located
msgid the message ID
ulStatus the 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_folder the folder to hard delete messages from
id_messages the list of ids
cn_messages the 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_folder the 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_src The source folder
obj_dst The destination folder
message_id pointer to container object for message ids.
WantCopy boolean 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, mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_folder the folder to move
obj_src source object where the folder to move is stored
obj_dst destination object where the folder will be moved
NewFolderName the new folder name in the destination folder
UseUnicode whether 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_folder the folder where the message is located
msgid the message ID
ulNewStatus the new status to be assigned
ulNewStatusMask bitmask of flags hat is applied to the new status indicating the flags to be set
ulOldStatus pointer 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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_folder the folder containing the messages to change
ReadFlags a bitmap of flags controlling the changes to PR_PROPERTY_FLAGS
MessageIdCount the number of messages in the MessageIds array
MessageIds an 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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/