libmapi/IMAPIContainer.c File Reference

Containers and tables related operations. More...

#include <libmapi/libmapi.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 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 GetTable (mapi_object_t *obj_container, mapi_object_t *obj_table)
_PUBLIC_ enum MAPISTATUS ModifyTable (mapi_object_t *obj_table, struct mapi_SRowList *rowList)
_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_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, GetHierarchyTable, GetLastError
Examples:
fetchappointment.c, and fetchmail.c.

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

_PUBLIC_ enum MAPISTATUS GetTable ( mapi_object_t *  obj_container,
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
obj_table the resulting table containing the container's permissions
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:
ModifyTable

References emsmdb_transaction(), 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 ModifyTable ( mapi_object_t *  obj_table,
struct mapi_SRowList *  rowList 
)

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
rowList the list of table entries to modify
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:
GetTable, AddUserPermission, ModifyUserPermission, RemoveUserPermission

References emsmdb_transaction(), 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 
)

Etablishes search criteria for the container

Parameters:
obj_container the object we apply search criteria on
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_CALL_FAILED: A network problem was encountered during the transaction
See also:
GetSearchCriteria

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