MAPIClientLibraries 2.0 API Documentation

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

- File List
- Globals

Functions
IMAPIContainer.c File Reference

Containers and tables related operations. More...

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

## Functions
_PUBLIC_ enum MAPISTATUS | GetContentsTable (mapi_object_t *obj_container, mapi_object_t *obj_table, uint8_t TableFlags, uint32_t *RowCount)
_PUBLIC_ enum MAPISTATUS | GetHierarchyTable (mapi_object_t *obj_container, mapi_object_t *obj_table, uint8_t TableFlags, uint32_t *RowCount)
_PUBLIC_ enum MAPISTATUS | GetPermissionsTable (mapi_object_t *obj_container, uint8_t flags, mapi_object_t *obj_table)
_PUBLIC_ enum MAPISTATUS | GetRulesTable (mapi_object_t *obj_folder, mapi_object_t *obj_table, uint8_t TableFlags)
_PUBLIC_ enum MAPISTATUS | GetSearchCriteria (mapi_object_t *obj_container, struct mapi_SRestriction *res, uint32_t *SearchFlags, uint16_t *FolderIdCount, uint64_t **FolderIds)
_PUBLIC_ enum MAPISTATUS | ModifyPermissions (mapi_object_t *obj_table, uint8_t flags, struct mapi_PermissionsData *permsdata)
_PUBLIC_ enum MAPISTATUS | SetSearchCriteria (mapi_object_t *obj_container, struct mapi_SRestriction *res, uint32_t SearchFlags, mapi_id_array_t *lpContainerList)

## Detailed Description

Containers and tables related operations.

## Function Documentation

_PUBLIC_ enum MAPISTATUS GetContentsTable | ( | mapi_object_t * | obj_container,
|  | mapi_object_t * | obj_table,
|  | uint8_t | TableFlags,
|  | uint32_t * | RowCount
| ) |  |

Returns a pointer to a container's table object

This function takes a pointer to a container object and returns a pointer to its associated contents

Parameters

  obj_container | the object to get the contents of
  obj_table | the resulting table containing the container's contents.
  TableFlags | flags controlling the type of table
  RowCount | the number of rows in the hierarchy table

TableFlags possible values:

- TableFlags_Associated (0x2): Get the contents table for "Folder Associated Information" messages, rather than normal messages.

- TableFlags_DeferredErrors (0x8): The call response can return immediately, possibly before the call execution is complete and in this case the ReturnValue as well the RowCount fields in the return buffer might not be accurate. Only retval reporting failure can be considered valid in this case.

- TableFlags_NoNotifications (0x10): Disables all notifications on .this Table object.

- TableFlags_SoftDeletes (0x20): Enables the client to get a list of the soft deleted folders.

- TableFlags_UseUnicode (0x40): Requests that the columns that contain string data be returned in Unicode format.

- TableFlags_SuppressNotifications (0x80): Suppresses notifications generated by this client’s actions on this Table object.

Developers can either set RowCount to a valid pointer on uint32_t or set it to NULL. In this last case, GetHierarchyTable won't return any value to the calling function.

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, GetHierarchyTable, GetLastError

Examples:
  fetchappointment.c, and fetchmail.c.

References mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), mapi_object_set_session(), and mapi_object_table_init().

Referenced by GetUserFreeBusyData().

_PUBLIC_ enum MAPISTATUS GetHierarchyTable | ( | mapi_object_t * | obj_container,
|  | mapi_object_t * | obj_table,
|  | uint8_t | TableFlags,
|  | uint32_t * | RowCount
| ) |  |

Returns a pointer to a container's table object

This function takes a pointer to a container object and returns a pointer to its associated hierarchy table

Parameters

  obj_container | the object to get the contents of
  obj_table | the resulting table containing the container's hierarchy
  TableFlags | flags controlling the type of table
  RowCount | the number of rows in the hierarchy table

TableFlags possible values:

- TableFlags_Depth (0x4): Fills the hierarchy table with containers from all levels. If this flag is not set, the hierarchy table contains only the container's immediate child containers.

- TableFlags_DeferredErrors (0x8): The call response can return immediately, possibly before the call execution is complete and in this case the ReturnValue as well the RowCount fields in the return buffer might not be accurate. Only retval reporting failure can be considered valid in this case.

- TableFlags_NoNotifications (0x10): Disables all notifications on .this Table object.

- TableFlags_SoftDeletes (0x20): Enables the client to get a list of the soft deleted folders.

- TableFlags_UseUnicode (0x40): Requests that the columns that contain string data be returned in Unicode format.

- TableFlags_SuppressNotifications (0x80): Suppresses notifications generated by this client’s actions on this Table object.

Developers can either set RowCount to a valid pointer on uint32_t or set it to NULL. In this last case, GetHierarchyTable won't return any value to the calling function.

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, GetContentsTable, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), mapi_object_set_session(), and mapi_object_table_init().

Referenced by GetUserFreeBusyData().

_PUBLIC_ enum MAPISTATUS GetPermissionsTable | ( | mapi_object_t * | obj_container,
|  | uint8_t | flags,
|  | mapi_object_t * | obj_table
| ) |  |

Returns a pointer to the permission's table object.

This function takes a pointer to a container object and returns a pointer to its associated permission table

Parameters

  obj_container | the object to get the contents of
  flags | any special flags to pass
  obj_table | the resulting table containing the container's permissions

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

The only meaningful value for flags is IncludeFreeBusy (0x02). This should be set when getting permissions on the Calendar folder when using Exchange 2007 and later. It should not be set in other situations.

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
  ModifyPermissions

References mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), mapi_object_set_session(), and mapi_object_table_init().

Referenced by ModifyUserPermission(), and RemoveUserPermission().

_PUBLIC_ enum MAPISTATUS GetRulesTable | ( | mapi_object_t * | obj_folder,
|  | mapi_object_t * | obj_table,
|  | uint8_t | TableFlags
| ) |  |

Gets the rules table of a folder

Parameters

  obj_folder | the folder we want to retrieve the rules table from
  obj_table | the rules table
  TableFlags | bitmask associated to the rules table

Possible values for TableFlags:

- RulesTableFlags_Unicode (0x40): Set if the client is requesting that string values in the table to be returned as Unicode strings.

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(), mapi_object_get_session(), mapi_object_set_handle(), mapi_object_set_logon_id(), mapi_object_set_session(), and mapi_object_table_init().

_PUBLIC_ enum MAPISTATUS GetSearchCriteria | ( | mapi_object_t * | obj_container,
|  | struct mapi_SRestriction * | res,
|  | uint32_t * | SearchFlags,
|  | uint16_t * | FolderIdCount,
|  | uint64_t ** | FolderIds
| ) |  |

Obtains the search criteria for a container

Parameters

  obj_container | the object we retrieve search criteria from
  res | pointer to a mapi_SRestriction structure defining the search criteria
  SearchFlags | bitmask of flags that controls how the search is performed
  FolderIdCount | number of FolderIds entries
  FolderIds | pointer to a list of identifiers representing containers included in the 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
  SetSearchCriteria

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

_PUBLIC_ enum MAPISTATUS ModifyPermissions | ( | mapi_object_t * | obj_table,
|  | uint8_t | flags,
|  | struct mapi_PermissionsData * | permsdata
| ) |  |

Modify the entries of a permission table

This function takes a pointer to a table object, a list of entries to modify and alter the permission table of its associated container. This function can be used to add, modify or remove permissions.

Parameters

  obj_table | the table containing the container's permissions
  flags | any special flags to use
  permsdata | the list of permissions table entries to modify

Possible values for flags:

- 0x02 for IncludeFreeBusy. This should be set when modifying permissions on the Calendar folder when using Exchange 2007 and later. It should not be set in other situations.
- 0x01 for ReplaceRows. This means "remove all current permissions and use this set instead", so the permsdata must consist of ROW_ADD operations.

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
  GetPermissionsTable, AddUserPermission, ModifyUserPermission, RemoveUserPermission

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

Referenced by AddUserPermission(), ModifyUserPermission(), and RemoveUserPermission().

_PUBLIC_ enum MAPISTATUS SetSearchCriteria | ( | mapi_object_t * | obj_container,
|  | struct mapi_SRestriction * | res,
|  | uint32_t | SearchFlags,
|  | mapi_id_array_t * | lpContainerList
| ) |  |

Establishes search criteria for the container

Parameters

  obj_container | the object we apply search criteria to
  res | pointer to a mapi_SRestriction structure defining the search criteria
  SearchFlags | bitmask of flags that controls how the search is performed
  lpContainerList | pointer to a list of identifiers representing containers to be included in the search

SearchFlags can take the following values:

- BACKGROUND_SEARCH: Search run at normal priority relative to other searches. This flag is mutually exclusive with the FOREGROUND_SEARCH one.
- FOREGROUND_SEARCH: Search run at high priority relative to other searches. This flag is mutually exclusive with the BACKGROUND_SEARCH one.
- RECURSIVE_SEARCH: The search should include the containers specified in the lpContainerList parameter and all of their child container. This flag is mutually exclusive with the SHALLOW_SEARCH one.
- RESTART_SEARCH: The search should be initiated, if this is the first call to SetSearchCriteria, or restarted, if the search is inactive. This flag is mutually exclusive with the STOP_SEARCH flag.
- SHALLOW_SEARCH: The search should only look in the containers specified in the lpContainerList parameter for matching entries. This flag is mutually exclusive with the RECURSIVE_SEARCH one.
- STOP_SEARCH: The search should be aborted. This flag is mutually exclusive with the RESTART_SEARCH one.

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: One or more parameters were invalid (usually null pointer)
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  GetSearchCriteria

References get_mapi_SRestriction_size(), mapi_id_array_get(), 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/