Chapter 8. MythiCal backend API

Chapter 8. MythiCal backend API
Prev

The MythiCal architecture allows multiple backend providers to serve data from multiple sources via the libmythical client API. Therefore anyone wishing to provide a standard calendaring interface to their particular application need only implement the backend API to locate and serve calendar resources without the huge task of implementing an entire protocol such as CalDAV.

8.1. Backend API

void MythiBEInit()

Called once when the backend module has been succesfully loaded into MythiCal.

void MythiBEShutdown()

Called once when the backend module is being unloaded from MythiCal.

int MythiBEInstanceInit(MYTHIBEINSTANCE *instance)

Called once for each backend instance, e.g. whenever a backend is bound to a particular path in the MythiCal namespace. The MYTHIBEINSTANCE structure contains two main structures of interest:

config: Contains the parsed configuration block for this backend
private: A per-instance structure for holding private information

Generally a backend implementation will parse its parameters from the configuration file and then set up its own private data structures. The initialiser should return MYTHI_ERR_SUCCESS if a valid instance could be created with the given parameters, or MYTHI_ERR_FAIL otherwise.

int MythiBEInstanceShutdown(MYTHIBEINSTANCE *instance)

Called upon shutdown of the MythiCal server instance. This callback is typically used to free resources created by MythiBEInstanceInit(). The backend should returns MYTHI_ERR_SUCCESS if the shutdown was successful or MYTHI_ERR_FAIL otherwise.

int MythiBEOpenCollection(CONNSTATE *conn, MYTHIBEINSTANCE *instance, char *bepath, MYTHICOLLECTION **collection)

Called when a client requests opening of the named bepath for a given instance. MythiCal correctly routes paths in the MythiCal namespace to the appropriate backend instance, removing any namespace prefixes so that the provided path is relative to the instance path.

Backends should attempt to locate a collection at the given path, and create a new MYTHICOLLECTION with all properties set if it exists. The backend should return MYTHI_ERR_SUCCESS if the collection could be opened, or MYTHI_ERR_FAIL otherwise.

int MythiBESearchCollection(CONNSTATE *conn, MYTHIBEINSTANCE *instance, char *bepath, MYTHIAUTH *auth, char **properties, MYTHIRESOURCE ***items)

Called when a client requests a search of a collection at the given bepath.

Backends should attempt to locate a collection at the given path, and return all resources within the collection if it exists. The backend should return MYTHI_ERR_SUCCESS if the collection could be opened, or MYTHI_ERR_FAIL otherwise.

int MythiBEGetResources(CONNSTATE *conn, MYTHIBEINSTANCE *instance, char *bepath, MYTHIAUTH *auth, char **resourceids, char **properties, MYTHIRESOURCE ***items)

Called when a client requests the retrieval of a list of NULL-terminated resource ids from the collection located at bepath. MythiCal correctly routes paths in the MythiCal namespace to the appropriate backend instance, removing any namespace prefixes so that the provided path is relative to the instance path.

Backends should attempt to locate a collection at the given path, and return an array of MYTHIRESOURCEs containing the specified properties for the specified resourceids. The backend should return MYTHI_ERR_SUCCESS upon success and MYTHI_ERR_FAIL in the case of failure.

int MythiBEPutResources(CONNSTATE *conn, MYTHIBEINSTANCE *instance, char *bepath, MYTHIAUTH *auth, MYTHIRESOURCE **items)

Called when a client requests the upload of a list of NULL-terminated resources to the collection located at bepath. MythiCal correctly routes paths in the MythiCal namespace to the appropriate backend instance, removing any namespace prefixes so that the provided path is relative to the instance path.

Backends should attempt to locate a collection at the given path and either create or update resources represented by each individual MYTHIRESOURCE. The backend should return MYTHI_ERR_SUCCESS upon success and MYTHI_ERR_FAIL in the case of failure.

int MythiBEDeleteResources(CONNSTATE *conn, MYTHIBEINSTANCE *instance, char *bepath, MYTHIAUTH *auth, char **resourceids)

Called when a client requests the deletion of a list of NULL-terminated resourceids to the collection located at bepath. MythiCal correctly routes paths in the MythiCal namespace to the appropriate backend instance, removing any namespace prefixes so that the provided path is relative to the instance path.

Backends should attempt to locate a collection at the given path and delete resources represented by each individual resourceid. The backend should return MYTHI_ERR_SUCCESS upon success and MYTHI_ERR_FAIL in the case of failure.

int MythiBEGetCollectionRights(CONNSTATE *conn, MYTHIBEINSTANCE *instance, char *user, char *bepath, uint32_t *privmask)

Called when attempting to determine the access rights for a collection located at bepath for the given user. MythiCal correctly routes paths in the MythiCal namespace to the appropriate backend instance, removing any namespace prefixes so that the provided path is relative to the instance path.

Backends should attempt to locate a collection at the given path and set the bitmask given at *privmask to reflect the rights of the given user. The privmask should be a bitmask of the following values:

MYTHI_PRIV_READ: The specified user has read privileges on a collection located at the specified path
MYTHI_PRIV_WRITE: The specified user has write privileges on a collection located at the specified path
MYTHI_PRIV_DELETE: The specified user has delete privileges on a collection located at the specified path

The backend should return MYTHI_ERR_SUCCESS if the rights could be succesfully determined and MYTHI_ERR_FAIL otherwise.

int MythiBEAuthUser(CONNSTATE *conn, MYTHIBEINSTANCE *instance, MYTHIAUTH *auth)

Called when attempting to determine whether the credentials given in MYTHIAUTH are valid for the backend instance.

Backends should attempt to authenticate the user credentials give in MYTHIAUTH for this particular backend instance. As an example, a DaviCal module backend should attempt to authenticate the credentials against the internal DaviCal user principal database.

The backend should return MYTHI_ERR_SUCCESS if the authentication was successful and MYTHI_ERR_FAIL otherwise.