summaryrefslogtreecommitdiffstats
path: root/src/caldav.h
blob: 5734404e9ba53006f30a89ed1c39c4d6532e8200 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
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