Chapter 7. libmythical client API

Chapter 7. libmythical client API
Prev		Next

libmythical is the client API for connecting to the MythiCal server. It consists of a number of functions for connecting to a remote server, opening collections and retrieving/updating calendar items. Once installed, access to the libmythical client API is done through the inclusion of the libmythical.h header file.

7.1. Connection API

MYTHISTATE *mythi_connect(MYTHICONNECT *connection): Connect to a remote MythiCal server using the given connection information. Returns NULL on connection failure or a valid MYTHISTATE * upon success.
int mythi_disconnect(MYTHISTATE *state): Disconnect from a remote MythiCal server represented by state. Returns MYTHI_ERR_SUCCESS on success or MYTHI_ERR_FAIL on error.

7.2. Collection API

int mythi_open_collection(MYTHISTATE *state, MYTHIAUTH *auth, char *path, MYTHICOLLECTION **collection)

Open the specified collection at path using the connection state and the credentials from auth. If successful, collection will be set to point to a valid MYTHICOLLECTION structure and the function returns MYTHI_ERR_SUCCESS. If unsuccessful, collection will be set to NULL and the function will return one of either MYTHI_ERR_ACCESS_DENIED or MYTHI_ERR_FAIL.

char *mythi_get_collection_property(MYTHICOLLECTION *collection, char *propname)

Retrieve the named property from the given collection. Properties for collections can be one of the following:

MYTHIPROP_COLLECTION_TAG: Retrieve the unique tag for the given collection
MYTHIPROP_COLLECTION_DISPLAYNAME: Retrieve the display name for the given collection
MYTHIPROP_COLLECTION_OWNER: Retrieve the owner of the given collection
MYTHIPROP_COLLECTION_BACKENDPATH: Retrieve the backend path of the given collection
MYTHIPROP_COLLECTION_BACKENDROOT: Retrieve the backend root of the given collection

int mythi_close_collection(MYTHISTATE *state, MYTHICOLLECTION **collection)

Release all resources related to the collection given by collection. The function will return one of either MYTHI_ERR_SUCCESS or MYTHI_ERR_FAIL depending upon success or failure of the operation.

int mythi_search_collection(MYTHISTATE *state, MYTHICOLLECTION *collection, void *filters, char **properties, MYTHIRESOURCE ***items)

Search the specified collection using the set of filters given by filters, and retrieve the given properties for any matching resources as a NULL-terminated list in items. The function will return one of either MYTHI_ERR_SUCCESS or MYTHI_ERR_FAIL depending upon success or failure of the operation.

NOTE: filters is currently unimplemented and MUST be set to NULL to indicate that the server should return all resources within a collection.

7.3. Resource API

int mythi_get_resources(MYTHISTATE *state, MYTHICOLLECTION *collection, char **resourceids, char **properties, MYTHIRESOURCE ***items)

Get the specified list of NULL-terminated properties from the specified list of NULL-terminated resourceids and return them in items. If successful, items will be set to point to a valid NULL-terminated MYTHIRESOURCE array and the function returns MYTHI_ERR_SUCCESS. If unsuccessful, items will be set to NULL and the function will return MYTHI_ERR_FAIL.

int mythi_put_resources(MYTHISTATE *state, MYTHICOLLECTION *collection, MYTHIRESOURCE **items)

Put the specified list of NULL-terminated resources into the specified collection. If successful, the function returns MYTHI_ERR_SUCCESS. If unsuccessful, the function will return MYTHI_ERR_FAIL.

int mythi_delete_resources(MYTHISTATE *state, MYTHICOLLECTION *collection, char **resourceids)

Delete the specified list of NULL-terminated resource ids from the specified collection. If successful, the function returns MYTHI_ERR_SUCCESS. If unsuccessful, the function will return MYTHI_ERR_FAIL.

int mythi_resource_count(MYTHIRESOURCE **items)

Returns the number of resources in the NULL-terminated list items.

char *mythi_get_resource_property(MYTHIRESOURCE *searchitem, char *propname)

Retrieve the named property from the given resource. Properties for resources can be one of the following:

MYTHIPROP_RESOURCE_TAG: Retrieve the unique tag for the given resource
MYTHIPROP_RESOURCE_CALDATA: Retrieve the calendar entry in iCal format

int mythi_put_resource_property(MYTHIRESOURCE *searchitem, char *propname, char *value)

Set the named property for the given resource. Properties for resources are the same as those given above for mythi_get_resource_property().

MYTHIRESOURCE *mythi_create_resource(char *resourceid)

Create a new MYTHIRESOURCE with the specified resourceid. Returns NULL if resource creation failed. Note that all properties are optional, although backends may require a particular set of properties by returning a failure code when trying to upload the resulting resource to a server with mythi_put_resources().

7.4. Collection API

int mythi_free_resource(MYTHIRESOURCE *item): Frees the resource given by item. Returns MYTHI_ERR_SUCCESS on success.
int mythi_free_resources(MYTHIRESOURCE **items): Frees the NULL-terminated resource list given by items. Returns MYTHI_ERR_SUCCESS on success.

7.5. Authentication API

int mythi_auth_collection_path(MYTHISTATE *state, MYTHIAUTH *auth, char *path): Attempt to authenticate using the credentials given in auth to the backend path path. Returns either MYTHI_ERR_SUCCESS on authentication success or MYTHI_ERR_FAIL on authentication failure.

Prev		Next
Chapter 6. Apache mod_dav_mythical Configuration	Home	Chapter 8. MythiCal backend API