Initial import

1 files changed, 407 insertions, 0 deletions

diff --git a/src/caldav.h b/src/caldav.h
new file mode 100644
index 0000000..5734404
--- /dev/null
+++ b/src/caldav.h
@@ -0,0 +1,407 @@
+/* vim: set textwidth=80 tabstop=4: */
+
+/**
+ * @file caldav.h
+ * @brief interface to the caldav library.
+ * The library conforms to RFC4791. For further information follow this
+ * link http://www.ietf.org/rfc/rfc4791.txt
+ */
+
+/** 
+ * @mainpage
+ * This document is the documentation for the public interface to libcaldav.
+ * If you want to study the implementation look for the developers API.
+ *
+ * The libray and documentation is Copyright (c) 2008 Michael Rasmussen
+ * (mir@datanom.net)
+ *
+ * License for the source code.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ * License for the documentation.
+ *
+ * Permission is granted to copy, distribute and/or modify this document
+ * under the terms of the GNU Free Documentation License, Version 1.2
+ * or any later version published by the Free Software Foundation;
+ * with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ * Texts.
+ */
+
+#ifndef __CALDAV_H__
+#define __CALDAV_H__
+
+#include <time.h>
+
+/* For debug purposes */
+/**
+ * @typedef struct debug_curl
+ * A struct used to set internal options in the library
+ */
+typedef struct {
+  int		trace_ascii; /** @var int trace_ascii
+					 	  * 0 or 1
+					 	  */
+  int		debug;       /** @var int debug
+					 	  * 0 or 1
+					 	  */
+  int		verify_ssl_certificate;
+  int		use_locking;
+  char*		custom_cacert; 
+} debug_curl;
+
+/**
+ * @typedef struct _caldav_error caldav_error
+ * Pointer to a caldav_error structure
+ */
+typedef struct _caldav_error caldav_error;
+
+/**
+ * @struct _caldav_error
+ * A struct for storing error codes and messages
+ */
+struct _caldav_error {
+	long code; /**
+				* @var long code
+				* if < 0 internal error > 0 CalDAV protocol error.
+				*/
+	char* str; /** @var char* str
+				* For storing human readable error message
+				*/
+};
+
+/**
+ * @typedef struct runtime_info
+ * Pointer to a runtime structure holding debug and error information
+ */
+typedef struct {
+    caldav_error*   error;
+    debug_curl*	    options;
+} runtime_info;
+
+/* CalDAV is defined in RFC4791 */
+
+/* Buffer to hold response */
+/**
+ * @typedef struct _response response
+ * Pointer to a _response structure
+ */
+typedef struct _response response;
+
+/**
+ * @struct _response
+ * A struct used for returning messages from the library to users
+ */
+struct _response {
+	char* msg; /** @var char* msg
+				* String for storing response
+				*/
+};
+
+/**
+ * @enum CALDAV_ACTION specifies supported CalDAV actions.
+ * UNKNOWN. An unknown action.
+ * ADD. Add a CalDAV calendar object.
+ * DELETE. Delete a CalDAV calendar object.
+ * MODIFY. Modify a CalDAV calendar object.
+ * GET. Get one or more CalDAV calendar object(s).
+ * GETALL. Get all CalDAV calendar objects.
+ */
+typedef enum {
+	UNKNOWN,
+	ADD,
+	DELETE,
+	FREEBUSY,
+	MODIFY,
+	GET,
+	GETALL,
+	GETCALNAME,
+	ISCALDAV,
+	OPTIONS,
+	DELETETASKS,
+	MODIFYTASKS,
+	GETTASKS,
+	GETALLTASKS,
+} CALDAV_ACTION;
+
+/**
+ * @enum CALDAV_RESPONSE specifies CalDAV 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 CalDAV collection
+ * and request. Client must solve the conflict and then resend request.
+ * LOCKED (HTTP 423). Locking failed.
+ */
+typedef enum {
+	OK,
+	FORBIDDEN,
+	CONFLICT,
+	LOCKED,
+	NOTIMPLEMENTED
+} CALDAV_RESPONSE;
+
+
+#ifndef __CALDAV_USERAGENT
+#define __CALDAV_USERAGENT "libcurl-agent/0.1"
+#endif
+
+
+/**
+ * Function for adding a new event.
+ * @param object Appointment following ICal format (RFC2445). Receiver is
+ * responsible for freeing the memory.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_add_object(const char* object,
+				  const char* URL,
+				  runtime_info* info);
+
+/**
+ * Function for deleting an event.
+ * @param object Appointment following ICal format (RFC2445). Receiver is
+ * responsible for freeing the memory.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_delete_object(const char* object,
+				     const char* URL,
+				     runtime_info* info);
+
+/**
+ * Function for modifying an event.
+ * @param object Appointment following ICal format (RFC2445). Receiver is
+ * responsible for freeing the memory.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_modify_object(const char* object,
+				     const char* URL,
+				     runtime_info* info);
+
+/**
+ * Function for getting a collection of events determined by time range.
+ * @param result A pointer to struct _response where the result is to stored.
+ * @see response. Caller is responsible for freeing the memory.
+ * @param start time_t variable specifying start for range. Included in search.
+ * @param end time_t variable specifying end for range. Included in search.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_get_object(response* result,
+				  time_t start,
+				  time_t end,
+				  const char* URL,
+				  runtime_info* info);
+
+/**
+ * Function for getting all events from the collection.
+ * @param result A pointer to struct _response where the result is to stored.
+ * @see response. Caller is responsible for freeing the memory.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_getall_object(response* result,
+				     const char* URL,
+				     runtime_info* info);
+
+/**
+ * Function for deleting a task.
+ * @param object Appointment following ICal format (RFC2445). Receiver is
+ * responsible for freeing the memory.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_tasks_delete_object(const char* object,
+				     const char* URL,
+				     runtime_info* info);
+
+/**
+ * Function for modifying a task.
+ * @param object Appointment following ICal format (RFC2445). Receiver is
+ * responsible for freeing the memory.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_tasks_modify_object(const char* object,
+				     const char* URL,
+				     runtime_info* info);
+
+/**
+ * Function for getting a collection of tasks determined by time range.
+ * @param result A pointer to struct _response where the result is to stored.
+ * @see response. Caller is responsible for freeing the memory.
+ * @param start time_t variable specifying start for range. Included in search.
+ * @param end time_t variable specifying end for range. Included in search.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_tasks_get_object(response* result,
+				  time_t start,
+				  time_t end,
+				  const char* URL,
+				  runtime_info* info);
+
+/**
+ * Function for getting all tasks from the collection.
+ * @param result A pointer to struct _response where the result is to stored.
+ * @see response. Caller is responsible for freeing the memory.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_tasks_getall_object(response* result,
+				     const char* URL,
+				     runtime_info* info);
+
+/**
+ * Function for getting the stored display name for the collection.
+ * @param result A pointer to struct _response where the result is to stored.
+ * @see response. Caller is responsible for freeing the memory.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_get_displayname(response* result,
+				       const char* URL,
+				       runtime_info* info);
+
+/**
+ * Function to test wether a calendar resource is CalDAV enabled or not.
+ * @param URL Defines CalDAV resource. Receiver is responsible for
+ * freeing the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @result 0 (zero) means no CalDAV support, otherwise CalDAV support
+ * detechted.
+ */
+int caldav_enabled_resource(const char* URL, runtime_info* info);
+
+/**
+ * Function for getting free/busy information.
+ * @param result A pointer to struct _response where the result is to stored.
+ * @see response. Caller is responsible for freeing the memory.
+ * @param start time_t variable specifying start and end for range. Both
+ * are included in range.
+ * @param end time_t variable specifying start and end for range. Both
+ * are included in range.
+ * @param URL Defines CalDAV resource. Receiver is responsible for freeing
+ * the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @return Ok, FORBIDDEN, or CONFLICT. @see CALDAV_RESPONSE
+ */
+CALDAV_RESPONSE caldav_get_freebusy(response *result,
+				  					time_t start,
+				  					time_t end,
+				  					const char* URL,
+				  					runtime_info* info);
+
+/** 
+ * @deprecated Always returns an initialized empty caldav_error
+ * Function to call in case of errors.
+ * Caller provides a pointer to a local caldav_error structure.
+ * Caldav_get_error will initialize pointer if NULL.
+ * Caller is responsible for freeing returned memory.
+ * After the first call the internal error buffer is reset.
+ * @param lib_error A pointer to a struct _caldav_error. @see _caldav_error
+ * @return An initialized caldav_error pointer to memory where error
+ * messages can be found from the last call to the library.
+ */
+caldav_error* caldav_get_error(caldav_error* lib_error);
+
+/** 
+ * Function for freeing memory for a previous initialization of a
+ * caldav_error. @see caldav_get_error()
+ * Caller provides a pointer to a local caldav_error structure.
+ * @param lib_error A pointer to a struct _caldav_error. @see _caldav_error
+ */
+void caldav_free_error(caldav_error* lib_error);
+
+/* Setting various options in library */
+
+/**
+ * @deprecated Does nothing
+ * Function which supports sending various options inside the library.
+ * @param curl_options A struct debug_curl. See debug_curl.
+ */
+void caldav_set_options(debug_curl curl_options);
+
+/**
+ * Function to call to get a list of supported CalDAV options for a server
+ * @param URL Defines CalDAV resource. Receiver is responsible for
+ * freeing the memory. [http://][username[:password]@]host[:port]/url-path.
+ * See (RFC1738).
+ * @param info Pointer to a runtime_info structure. @see runtime_info
+ * @result A list of available options or NULL in case of any error.
+ */
+char** caldav_get_server_options(const char* URL, runtime_info* info);
+
+/**
+ * Function for getting an initialized runtime_info structure
+ * @return runtime_info. @see runtime_info
+ */
+runtime_info* caldav_get_runtime_info();
+
+/**
+ * Function for freeing memory for a previous initialization of an info
+ * structure
+ * @param info Address to a pointer to a runtime_info structure. @see 
+ * runtime_info
+ */
+void caldav_free_runtime_info(runtime_info** info);
+
+/**
+ * Function for getting an initialized response structure
+ * @return response. @see _response
+ */
+response* caldav_get_response();
+
+/**
+ * Function for freeing memory for a previous initialization of an response
+ * structure
+ * @param info Address to a pointer to a response structure. @see 
+ * _response
+ */
+void caldav_free_response(response** info);
+
+#endif