MAPIClientLibraries 2.0 API Documentation

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

- File List
- Globals

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