libmapi/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 get_utf8_utf16_conv_length(), mapi_object_get_handle(), mapi_object_get_id(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 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(), and mapi_object_set_session().

_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 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(), and mapi_object_set_session().

_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 mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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_get(), mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 get_utf8_utf16_conv_length(), mapi_object_get_handle(), mapi_object_get_id(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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 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/