History

MAPIStore 1.0 backend.table structure

table.get_available_properties

This function retrieves all the properties available for the table given the type of objects it handles. It doesn't relate to table.set_columns and the set of properties it set, but instead return a generic list of properties that can potentially be set on the given object type the table handles: message, folder, fai, permissions.

The function takes in parameters:
  • void *table_object: the table object
  • TALLOC_CTX *: the memory context to allocate the struct SPropTagArray to return
  • struct SPropTagArray **properties: a pointer on pointer to the list of available properties to return

table.set_columns

This function sets the columns we want to retrieve when querying for table objects row. The function takes in parameters:
  • void *table_object: the table object on which we want to set columns
  • uint16_t count: the number of enum MAPITAGS *properties to be set
  • enum MAPITAGS *properties: an array of MAPITAGS to be used to set columns

table.set_restrictions

This function sets one or more filters on the table. When the table is queried again through get_row or get_row_count, filters will get applied and only filtered results returned.

The function takes in parameters:
  • void *table_object: the table object restrictions apply on
  • struct mapi_SRestriction *restrictions: the restrictions to apply
  • uint8_t *table_status: the status of the table. In theory, we should be able to return from the set_restriction even if the operation didn't yet complete (asynchronous mechanism). In practice, we just do the operation synchronously and return TBLSTAT_COMPLETE if the restrictions applied properly.

Regarding mapi_SRestriction, this structure defined a filter in Exchange world and should be detailed on the wiki. This is however already covered by Exchange specifications in [MS-OXCDATA] section 2.12.

table.set_sort_order

This function set the sorting order depending on the specified struct SSortOrderSet *sort_order. This function takes in parameters:
  • void *table_object: the table object on which sorting applies
  • struct SSortOrderSet *sort_oder: the sort to apply to the table
  • uint8_t *table_status: the table status to return (TBLSTAT_COMPLETE, see above subsection).

table.get_row

The function takes in parameters:
  • void *table_object: the table object to retrieve the row from
  • TALLOC_CTX : the memory context to user to allocate data to return
    enum table_query_type query_type: defines on which view the query occurs:
    • MAPISTORE_PREFILTERED_QUERY: has the table already been filtered using set_restrictions or set_sort_order etc. In this case, return the row in this filtered view
    • MAPISTORE_LIVEFILTERED_QUERY: only setcolumns was applied, return rows directly from the raw table results.
  • uint32_t row_id: the index of the row to fetch within the table
  • struct mapistore_property_data **data: the set of data for the row to return

mapistore_property_data is an abstracted way to return data. When OpenChange returns data to a client, it sends them within a DATA_BLOB where values (matching requested properties) are packed one to next,
sometimes prefixed by an error value to let the client know it didn't found the value or accessing the value was forbidden.

struct mapistore_property_data {
        void *data;
        int error;
};

This mapistore_property_data is just a data structure backends use to fill information. They put the value matching a property in void *data.
This is used to pass any kind of data back. If the value was found, set error to MAPISTORE_SUCCESS. If an error occurs, set data to NULL and set the error to MAPISTORE_ERR_NOT_FOUND or MAPI_E_NO_ACCESS depending on the status.

table.get_row_count

This function retrieves the number of row for the specific table given the query_type. The function takes in parameter:
  • void *table_object: the table object from which to retrieve the number of rows
  • enum table_type query_type: defines on which view the query occurs
  • uint32_t *count: the number of rows to return

handle_destructor

This is called automatically from OpenChange server when the table is destroyed or the associated folder is closed. It makes use of the talloc
hierarchy which creates a tree of memory contexts: parent, children.

When a parent gets deleted, all the children gets also deleted. the destructor function is a callback that can be associated to a TALLOC context and is called before the pointer is free'd.

In this case, the destructor receives the table object. So you know which table is associated and what to destroy. There is also the handle id passed down which let you know (remember the handle id / table object combination discussed earlier) which specific table to delete - if you followed this model.

The function takes in parameter:
  • void *table_object: the table object to destroy
  • unt32_t handle_id: the handle id that was associated to the specific table to delete

Also available in: HTML TXT