carddav.h(3)

NAME
carddav.h - interface to the carddav library.

SYNOPSIS

#include <time.h>

  Data Structures
struct debug_curl
struct _carddav_error
A struct for storing error codes and messages.
struct runtime_info
struct _response
A struct used for returning messages from the library to users.

  Macros
#define __CARDDAV_USERAGENT 'libcurl-agent/0.1'

  Typedefs
typedef struct _carddav_error carddav_error
Pointer to a carddav_error structure.
typedef struct _response response
Pointer to a _response structure.

  Enumerations
enum CARDDAV_ACTION { UNKNOWN, ADD, DELETE, FREEBUSY, MODIFY, GET, GETALL, GETCALNAME, ISCARDDAV, OPTIONS }
specifies supported CardDAV actions.
enum CARDDAV_RESPONSE { OK, FORBIDDEN, CONFLICT, LOCKED, NOTIMPLEMENTED }
specifies CardDAV error states.

  Functions
CARDDAV_RESPONSE carddav_add_object (const char *object, const char *URL, runtime_info *info)
Function for adding a new card.
CARDDAV_RESPONSE carddav_delete_object (const char *object, const char *URL, runtime_info *info)
Function for deleting a card.
CARDDAV_RESPONSE carddav_delete_object_by_uri (const char *object, const char *URL, runtime_info *info)
Function for deleting a card by URI.
CARDDAV_RESPONSE carddav_modify_object (const char *object, const char *URL, runtime_info *info)
Function for modifying a card.
CARDDAV_RESPONSE carddav_modify_object_by_uri (const char *object, const char *URL, runtime_info *info)
Function for modifying a card by URI.
CARDDAV_RESPONSE carddav_get_object (response *result, time_t start, time_t end, const char *URL, runtime_info *info)
Function for getting a collection of cards determined by time range.
CARDDAV_RESPONSE carddav_getall_object (response *result, const char *URL, runtime_info *info)
Function for getting all cards from the collection.
CARDDAV_RESPONSE carddav_getall_object_by_uri (response *result, const char *URL, runtime_info *info)
Function for getting all cards from the collection.
CARDDAV_RESPONSE carddav_get_displayname (response *result, const char *URL, runtime_info *info)
Function for getting the stored display name for the collection.
int carddav_enabled_resource (const char *URL, runtime_info *info)
Function to test wether a calendar resource is CardDAV enabled or not.
CARDDAV_RESPONSE carddav_get_freebusy (response *result, time_t start, time_t end, const char *URL, runtime_info *info)
Function for getting free/busy information.
carddav_error * carddav_get_error (carddav_error *lib_error)
void carddav_free_error (carddav_error *lib_error)
Function for freeing memory for a previous initialization of a carddav_error.
void carddav_set_options (debug_curl curl_options)
Function which supports sending various options inside the library.
char ** carddav_get_server_options (const char *URL, runtime_info *info)
Function to call to get a list of supported CardDAV options for a server.
runtime_info * carddav_get_runtime_info ()
Function for getting an initialized runtime_info structure.
void carddav_free_runtime_info (runtime_info **info)
Function for freeing memory for a previous initialization of an info structure.
response * carddav_get_response ()
Function for getting an initialized response structure.
void carddav_free_response (response **info)
Function for freeing memory for a previous initialization of an response structure.

Detailed Description

interface to the carddav library. The library conforms to IETF carddav draft specification daboo-10. For further information follow this link http://tools.ietf.org/html/draft-ietf-vcarddav-carddav-10

Enumeration Type Documentation

  enum CARDDAV_ACTION

specifies supported CardDAV actions. UNKNOWN. An unknown action. ADD. Add a CardDAV calendar object. DELETE. Delete a CardDAV calendar object. MODIFY. Modify a CardDAV calendar object. GET. Get one or more CardDAV calendar object(s). GETALL. Get all CardDAV calendar objects.

  enum CARDDAV_RESPONSE

specifies CardDAV error states. OK (HTTP 200). Request was satisfied. FORBIDDEN (HTTP 403). Access not allowed. Dont repeat request. CONFLICT (HTTP 409). Conflict between current state of CardDAV collection and request. Client must solve the conflict and then resend request. LOCKED (HTTP 423). Locking failed.

Function Documentation

  CARDDAV_RESPONSE carddav_add_object (const char * object, const char * URL, runtime_info * info)

Function for adding a new card.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

Function for adding a new card.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  CARDDAV_RESPONSE carddav_delete_object (const char * object, const char * URL, runtime_info * info)

Function for deleting a card.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

Function for deleting a card.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  CARDDAV_RESPONSE carddav_delete_object_by_uri (const char * object, const char * URL, runtime_info * info)

Function for deleting a card by URI.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

Function for deleting a card by URI.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  int carddav_enabled_resource (const char * URL, runtime_info * info)

Function to test wether a calendar resource is CardDAV enabled or not.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    0 (zero) means no CardDAV support, otherwise CardDAV support detechted.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    0 (zero) means no CardDAV support, otherwise CardDAV support detechted.

  void carddav_free_error (carddav_error * lib_error)

Function for freeing memory for a previous initialization of a carddav_error.

See also
    carddav_get_error() Caller provides a pointer to a local carddav_error structure.

Parameters
    lib_error A pointer to a struct _carddav_error.

See also
    _carddav_error

  void carddav_free_response (response ** resp)

Function for freeing memory for a previous initialization of an response structure.

Parameters
    info Address to a pointer to a response structure.

See also
    _response

  void carddav_free_runtime_info (runtime_info ** info)

Function for freeing memory for a previous initialization of an info structure.

Parameters
    info Address to a pointer to a runtime_info structure.

See also
    runtime_info

  CARDDAV_RESPONSE carddav_get_displayname (response * result, const char * URL, runtime_info * info)

Function for getting the stored display name for the collection.

Parameters
    result A pointer to struct _response where the result is to stored.

See also
    response. Caller is responsible for freeing the memory.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

Parameters
    result A pointer to struct _response where the result is to stored.

See also
    response. Caller is responsible for freeing the memory.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  carddav_error * carddav_get_error (carddav_error * lib_error)

Deprecated
    Always returns an initialized empty carddav_error Function to call in case of errors. Caller provides a pointer to a local carddav_error structure. Carddav_get_error will initialize pointer if NULL. Caller is responsible for freeing returned memory. After the first call the internal error buffer is reset.

Parameters
    lib_error A pointer to a struct _carddav_error.

See also
    _carddav_error

Returns
    An initialized carddav_error pointer to memory where error messages can be found from the last call to the library.

Deprecated
    Function to call in case of errors. Caller provides a pointer to a local carddav_error structure. Carddav_get_error will initialize pointer if NULL. Caller is responsible for freeing returned memory. After the first call the internal error buffer is reset.

Parameters
    lib_error A pointer to a struct _carddav_error.

See also
    _carddav_error

Returns
    An initialized carddav_error pointer to memory where error messages can be found from the last call to the library.

  CARDDAV_RESPONSE carddav_get_freebusy (response * result, time_t start, time_t end, const char * URL, runtime_info * info)

Function for getting free/busy information.

Parameters
    result A pointer to struct _response where the result is to stored.

See also
    response. Caller is responsible for freeing the memory.

Parameters
    start time_t variable specifying start and end for range. Both are included in range.
    end time_t variable specifying start and end for range. Both are included in range.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  CARDDAV_RESPONSE carddav_get_object (response * result, time_t start, time_t end, const char * URL, runtime_info * info)

Function for getting a collection of cards determined by time range.

Parameters
    result A pointer to struct _response where the result is to stored.

See also
    response. Caller is responsible for freeing the memory.

Parameters
    start time_t variable specifying start for range. Included in search.
    end time_t variable specifying end for range. Included in search.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

Function for getting a collection of cards determined by time range.

Parameters
    result A pointer to struct _response where the result is to stored.

See also
    response. Caller is responsible for freeing the memory.

Parameters
    start time_t variable specifying start and end for range. Both are included in range.
    end time_t variable specifying start and end for range. Both are included in range.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  response * carddav_get_response ()

Function for getting an initialized response structure.

Returns
    response.

See also
    _response

  runtime_info * carddav_get_runtime_info ()

Function for getting an initialized runtime_info structure.

Returns
    runtime_info.

See also
    runtime_info

  char ** carddav_get_server_options (const char * URL, runtime_info * info)

Function to call to get a list of supported CardDAV options for a server.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    A list of available options or NULL in case of any error.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    A list of available options or NULL in case of any error.

  CARDDAV_RESPONSE carddav_getall_object (response * result, const char * URL, runtime_info * info)

Function for getting all cards from the collection.

Parameters
    result A pointer to struct _response where the result is to stored.

See also
    response. Caller is responsible for freeing the memory.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

Function for getting all cards from the collection.

Parameters
    result A pointer to struct _response where the result is to stored.

See also
    response. Caller is responsible for freeing the memory.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  CARDDAV_RESPONSE carddav_getall_object_by_uri (response * result, const char * URL, runtime_info * info)

Function for getting all cards from the collection. This version stores the URI as a VCARD parameter.

Parameters
    result A pointer to struct _response where the result is to stored.

See also
    response. Caller is responsible for freeing the memory.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

Function for getting all cards from the collection.

This version stores the URI as a VCARD parameter.

Parameters
    result A pointer to struct _response where the result is to stored.

See also
    response. Caller is responsible for freeing the memory.

Parameters
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  CARDDAV_RESPONSE carddav_modify_object (const char * object, const char * URL, runtime_info * info)

Function for modifying a card.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

Function for modifying a card.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  CARDDAV_RESPONSE carddav_modify_object_by_uri (const char * object, const char * URL, runtime_info * info)

Function for modifying a card by URI.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).
    info Pointer to a runtime_info structure.

See also
    runtime_info

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

Function for modifying a card by URI.

Parameters
    object Appointment following ICal format (RFC2445). Receiver is responsible for freeing the memory.
    URL Defines CardDAV resource. Receiver is responsible for freeing the memory. [http://][username[:password]@]host[:port]/url-path. See (RFC1738).

Returns
    Ok, FORBIDDEN, or CONFLICT.

See also
    CARDDAV_RESPONSE

  void carddav_set_options (debug_curl curl_options)

Function which supports sending various options inside the library.

Deprecated
    Does nothing Function which supports sending various options inside the library.

Parameters
    curl_options A struct debug_curl. See debug_curl.
    curl_options A struct debug_curl. See debug_curl.

Author

Generated automatically by Doxygen for libcarddav-0.6.1 from the source code.