MAPIClientLibraries 2.0 API Documentation

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

- File List
- Globals

Functions
simple_mapi.c File Reference

Convenience functions. More...

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

## Functions
_PUBLIC_ enum MAPISTATUS | AddUserPermission (mapi_object_t *obj_folder, const char *username, enum ACLRIGHTS role)
_PUBLIC_ enum MAPISTATUS | GetBestBody (mapi_object_t *obj_message, uint8_t *format)
_PUBLIC_ enum MAPISTATUS | GetDefaultFolder (mapi_object_t *obj_store, uint64_t *folder, const uint32_t id)
_PUBLIC_ enum MAPISTATUS | GetDefaultPublicFolder (mapi_object_t *obj_store, uint64_t *folder, const uint32_t id)
_PUBLIC_ enum MAPISTATUS | GetFolderItemsCount (mapi_object_t *obj_folder, uint32_t *unread, uint32_t *total)
_PUBLIC_ bool | IsMailboxFolder (mapi_object_t *obj_store, uint64_t fid, uint32_t *olFolder)
_PUBLIC_ enum MAPISTATUS | ModifyUserPermission (mapi_object_t *obj_folder, const char *username, enum ACLRIGHTS role)
_PUBLIC_ enum MAPISTATUS | RemoveUserPermission (mapi_object_t *obj_folder, const char *username)

## Detailed Description

Convenience functions.

## Function Documentation

_PUBLIC_ enum MAPISTATUS AddUserPermission | ( | mapi_object_t * | obj_folder,
|  | const char * | username,
|  | enum ACLRIGHTS | role
| ) |  |

Adds permissions for a user on a given folder

Parameters

  obj_folder | the folder we add permission for
  username | the Exchange username we add permissions for
  role | the permission mask value

The following permissions and rights are supported:

- RightsNone
- RightsReadItems
- RightsCreateItems
- RightsEditOwn
- RightsDeleteOwn
- RightsEditAll
- RightsDeleteAll
- RightsCreateSubfolders
- RightsFolderOwner
- RightsFolderContact
- RoleNone
- RoleReviewer
- RoleContributor
- RoleNoneditingAuthor
- RoleAuthor
- RoleEditor
- RolePublishAuthor
- RolePublishEditor
- RightsAll
- RoleOwner

Returns
  MAPI_E_SUCCESS on success, otherwise a failure code (MAPISTATUS) indicating the 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: username is NULL

See Also
  ResolveNames, ModifyPermissions

References mapi_object_get_session(), MAPIFreeBuffer(), ModifyPermissions(), ResolveNames(), and set_SPropTagArray().

_PUBLIC_ enum MAPISTATUS GetBestBody | ( | mapi_object_t * | obj_message,
|  | uint8_t * | format
| ) |  |

Implement the BestBody algorithm and return the best body content type for a given message.

Parameters

  obj_message | the message we find the best body for
  format | the format - see below.

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI_E_NOT_FOUND. If MAPI_E_NOT_FOUND is returned then format is set to 0x0 (undefined). If MAPI_E_SUCCESS is returned, then format can have one of the following values:
  - olEditorText: format is plain text
  - olEditorHTML: format is HTML
  - olEditorRTF: format is RTF

References GetProps(), mapi_object_get_session(), MAPIFreeBuffer(), and set_SPropTagArray().

_PUBLIC_ enum MAPISTATUS GetDefaultFolder | ( | mapi_object_t * | obj_store,
|  | uint64_t * | folder,
|  | const uint32_t | id
| ) |  |

Retrieves the folder id for the specified default folder in a mailbox store

Parameters

  obj_store | the store to search
  id | the type of folder to search for
  folder | the resulting folder reference

The following types of folders are supported:

- olFolderTopInformationStore
- olFolderDeletedItems
- olFolderOutbox
- olFolderSentMail
- olFolderInbox
- olFolderCommonView
- olFolderCalendar
- olFolderContacts
- olFolderJournal
- olFolderNotes
- olFolderTasks
- olFolderDrafts
- olFolderReminders
- olFolderFinder

Note that this function will cache FID values for common accessed folders such as calendar, contact, journal, note, task and drafts until the store object got released.

Returns
  MAPI_E_SUCCESS on success, otherwise a failure code (MAPISTATUS) indicating the 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_store is undefined
  - MAPI_E_NOT_FOUND: The specified folder could not be found or is not yet supported.

See Also
  MAPIInitialize, OpenMsgStore, GetLastError

Examples:
  fetchappointment.c, and fetchmail.c.

_PUBLIC_ enum MAPISTATUS GetDefaultPublicFolder | ( | mapi_object_t * | obj_store,
|  | uint64_t * | folder,
|  | const uint32_t | id
| ) |  |

Retrieve the folder id for the specified default folder in a public folder store

Parameters

  obj_store | the store to search
  id | the type of folder to search for
  folder | the resulting folder reference

The following types of folders are supported:

- olFolderPublicRoot - the parent (directly or indirectly) for the folders below
- olFolderPublicIPMSubtree - Interpersonal Messages (IPM) folders
- olFolderPublicNonIPMSubtree - Non-interpersonal message folders
- olFolderPublicEFormsRoot - EForms Registry Root Folder
- olFolderPublicFreeBusyRoot - Free/busy root folder
- olFolderPublicOfflineAB - Offline address book root folder
- olFolderPublicEFormsRegistry - EForms Registry for the users locale
- olFolderPublicLocalFreeBusy - Site local free/busy folders
- olFolderPublicLocalOfflineAB - Site local Offline address book
- olFolderPublicNNTPArticle - NNTP article index folder

Returns
  MAPI_E_SUCCESS on success, otherwise a failure code (MAPISTATUS) indicating the 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_store is undefined
  - MAPI_E_NOT_FOUND: The specified folder could not be found or is not yet supported.

See Also
  MAPIInitialize, OpenPublicFolder, GetLastError

Referenced by GetUserFreeBusyData().

_PUBLIC_ enum MAPISTATUS GetFolderItemsCount | ( | mapi_object_t * | obj_folder,
|  | uint32_t * | unread,
|  | uint32_t * | total
| ) |  |

Retrieves the total and unread number of items for a specified folder.

Parameters

  obj_folder | the folder to get item counts for
  unread | the number of items in the folder (result)
  total | the number of items in the folder, including unread items (result)

Returns
  MAPI_E_SUCCESS on success, otherwise a failure code (MAPISTATUS) indicating the 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 undefined
  - MAPI_E_NOT_FOUND: The specified folder could not be found or is not yet supported.

See Also
  MAPIInitialize, OpenFolder, GetLastError

References GetProps(), mapi_object_get_session(), MAPIFreeBuffer(), and set_SPropTagArray().

_PUBLIC_ bool IsMailboxFolder | ( | mapi_object_t * | obj_store,
|  | uint64_t | fid,
|  | uint32_t * | olFolder
| ) |  |

Check if a given folder identifier matches with a system/default one and optionally returns the olFolder type

Parameters

  obj_store | pointer to the store object
  fid | reference to the folder identifier to check
  olFolder | pointer to the returned olFolder

Returns
  true on success, otherwise false

_PUBLIC_ enum MAPISTATUS ModifyUserPermission | ( | mapi_object_t * | obj_folder,
|  | const char * | username,
|  | enum ACLRIGHTS | role
| ) |  |

Modify permissions for a user on a given folder

Parameters

  obj_folder | the folder to modify permissions for
  username | the Exchange username to modify permissions for
  role | the permission mask value (see AddUserPermission)

Returns
  MAPI_E_SUCCESS on success, otherwise a failure code (MAPISTATUS) indicating the 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: username is NULL
  - MAPI_E_NOT_FOUND: couldn't find or change permissions for the given user

See Also
  AddUserPermission, ResolveNames, GetPermissionsTable, ModifyPermissions

References GetPermissionsTable(), mapi_object_get_session(), mapi_object_init(), mapi_object_release(), MAPIFreeBuffer(), ModifyPermissions(), QueryPosition(), QueryRows(), ResolveNames(), set_SPropTagArray(), and SetColumns().

_PUBLIC_ enum MAPISTATUS RemoveUserPermission | ( | mapi_object_t * | obj_folder,
|  | const char * | username
| ) |  |

Remove permissions for a user on a given folder

Parameters

  obj_folder | the folder to remove permission from
  username | the Exchange username to remove permissions for

Returns
  MAPI_E_SUCCESS on success, otherwise a failure code (MAPISTATUS) indicating the 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: username or obj_folder are NULL
  - MAPI_E_NOT_FOUND: couldn't find or remove permissions for the given user

See Also
  ResolveNames, GetPermissionsTable, ModifyPermissions

References GetPermissionsTable(), mapi_object_get_session(), mapi_object_init(), mapi_object_release(), MAPIFreeBuffer(), ModifyPermissions(), QueryPosition(), QueryRows(), ResolveNames(), set_SPropTagArray(), and SetColumns().

| This content is licensed under the Creative Commons Attribution ShareAlike License v. 3.0: http://creativecommons.org/licenses/by-sa/3.0/