OpenChange

h1. MAPIStore 1.0 backend.folder structure

h2. folder.open_folder

This function opens a folder in the backend. It should only perform an action when the folder is not a root/mapistore folder (referenced in openchange.ldb), since these specific root folders are opened during [[MAPIStore_10_backendbackend_structure#backendcreate_context-function|context creation]] and morphed/returned as a folder object when [[MAPIStore_10_backendcontext_structure#contextget_root_folder|context.get_root_folder]] returns.

For any folders within a backend and different from the root folder, the folder should be opened. The function takes in parameter:

* _void *parent_folder_: the parent folder object of the folder to open

* _TALLOC_CTX *_: the memory context to allocate folder_object with

* _uint64_t fid_: the folder identifier of the folder to open

* _void **folder_object_: the opened folder object to return

Folders are opened within a given context, which folder object is retrieved through [[MAPIStore_10_backendcontext_structure#contextget_root_folder|context.get_root_folder]] call. While this specifically apply to folder underneath the root folder, the same logic apply to sub folders which parent is not the root folder object within the context. It requires either to keep a reference to the root folder along newly created folder objects or be able to walk through the associated MAPIStore URI and figure out what the root folder URI is.

h2. folder.create_folder

This function only creates a folder within a existing context. The resulting created folder will have a URI using the same backend that the context it is using. Upon success, the folder is opened and returned within the _void **_ parameter. The function takes in parameter:

* _void *parent_folder_: the parent folder object of the folder to be created

* _TALLOC_CTX *_: the memory context to use to allocate the new folder upon success

* _uint64_t fid_: the folder identifier for this folder

* _struct SRow *aRow_: an Exchange data structures which must store PR_DISPLAY_NAME or PR_DISPLAY_NAME_UNICODE (the folder name to be created)

* _void **childfolder: the folder object for the newly created folder

The SRow structure may also supply the following Exchange properties:

* PR_COMMENT or PR_COMMENT_UNICODE: the folder description

* PR_PARENT_FID: the folder identifier of the parent folder object

* PR_CHANGE_NUM: the new change number

h2. folder.create_message

This function creates a temporary message object. Messages are a bit particular in Exchange, because they are not created through a single transaction. Creating message is the first operation of the process, but message doesn't get available/saved or sent until you respectively call save or submit backend methods. Between create and save/submit, MAPI clients can perform several operations such as:

* set or delete properties

* add or delete attachments

* add or delete recipients

Until save/submit is called, this message object remains virtual. However MAPI clients need a way to reference this object within current context until it's saved. This is why OpenChange generates a MID (message identifier) and requests the backend to temporarily create an associated MAPIStore URI. But this MID/MAPIStore URI couple is not stored within the user [[MAPIStore_10_Development_Guide#indexingtdb-URIFMID-wrapper|idexing.tdb]] database.

Remember that mapistore calls backend with MID/FID and expect the backend to lookup associated mapistore URI.

It is the backend's responsibility to virtual store this message until save/submit is called. If no such mechanism/API exist in your backend or if you want to speed up the process, you can use the ocpf (http://apidocs.openchange.org/libocpf/index.html) library which will store everything for you properly.