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_containerthe object to get the contents of
obj_tablethe resulting table containing the container's contents.
TableFlagsflags controlling the type of table
RowCountthe 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 emsmdb_transaction_wrapper(), 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(), mapi_object_table_init(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

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_containerthe object to get the contents of
obj_tablethe resulting table containing the container's hierarchy
TableFlagsflags controlling the type of table
RowCountthe 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 emsmdb_transaction_wrapper(), 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(), mapi_object_table_init(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

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_containerthe object to get the contents of
flagsany special flags to pass
obj_tablethe 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 emsmdb_transaction_wrapper(), 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(), mapi_object_table_init(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

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_folderthe folder we want to retrieve the rules table from
obj_tablethe rules table
TableFlagsbitmask 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 emsmdb_transaction_wrapper(), 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(), mapi_object_table_init(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_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_containerthe object we retrieve search criteria from
respointer to a mapi_SRestriction structure defining the search criteria
SearchFlagsbitmask of flags that controls how the search is performed
FolderIdCountnumber of FolderIds entries
FolderIdspointer 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_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_tablethe table containing the container's permissions
flagsany special flags to use
permsdatathe 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 emsmdb_transaction_wrapper(), get_mapi_property_size(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

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_containerthe object we apply search criteria to
respointer to a mapi_SRestriction structure defining the search criteria
SearchFlagsbitmask of flags that controls how the search is performed
lpContainerListpointer 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 mapi_id_array::count, emsmdb_transaction_wrapper(), get_mapi_SRestriction_size(), mapi_id_array_get(), 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/