4 #include <libgnomevfs/gnome-vfs.h>
5 #include <libxml/parser.h>
6 #include <libxml/tree.h>
7 #define GTODO_NO_DUE_DATE 99999999
9 #define LIBGTODO_ERROR g_quark_from_static_string("libgtodo-error-quark")
12 LIBGTODO_ERROR_OK
, /* no error */
13 LIBGTODO_ERROR_FAILED
,
14 LIBGTODO_ERROR_GENERIC
,
15 LIBGTODO_ERROR_NO_FILE
,
16 LIBGTODO_ERROR_NO_FILENAME
,
17 LIBGTODO_ERROR_READ_ONLY
,
18 LIBGTODO_ERROR_NO_PERMISSION
,
19 LIBGTODO_ERROR_GNOME_VFS
,
28 /* The structure used by the gtodo client, The user shouldnt have to use ANY
29 of the internal variables, NEVER */
31 typedef struct _GTodoClient
{
32 /* the function gtodo should call when the backend data changes */
33 void *(* function
)(gpointer cl
, gpointer data
);
34 /* the pointer it should pass to that function */
36 /* the last time the backend was edited */
38 /* the timeout UID that is used to check again every x ms. */
39 GnomeVFSMonitorHandle
*timeout
;
40 /* the path to the backend (in this case xml, should I make it more generic?) */
42 /* the pointer to the xml structure */
44 /* pointer to the first node */
46 /* number of categories */
47 gint number_of_categories
;
52 /* The GTodoList structure.. */
53 /* NO public fields */
54 typedef struct _GTodoList
{
59 /* The gtodo items, don't access the internal variables youreself, NEVER.
60 * Use the wrapper functions
61 * I should move this out of this .h file
64 typedef struct _GTotoItem
{
65 /* ID of todo item. This one should be unique */
66 /* for now I made it the time.. that should be unique enough for my purpose */
69 /* last edited, probly needed for syncing and stuff */
72 /* Creation Date. And possible end date */
75 /* if NULL no due date*/
81 /* if the item should notify when done */
87 /* due date if NULL no due date*/
90 /* due_time[0] houre due_time[1] minute */
91 /* see enumeration above */
94 /* Priority see enumeration*/
105 /* the three different priorities.. try to use this enumeration */
108 GTODO_PRIORITY_MEDIUM
,
112 /*** The functions **/
113 gboolean
gtodo_client_get_read_only(GTodoClient
*cl
);
114 /********************** GTodoItem *************************/
115 /* create an empty GTodoItem.. THIS HAS NO UID YET */
116 GTodoItem
* gtodo_client_create_empty_todo_item(void);
118 /* create a new unique GTodoItem,use this to add an todo item */
119 GTodoItem
* gtodo_client_create_new_todo_item(GTodoClient
*cl
);
121 /* free's an GTodoItem */
122 void gtodo_todo_item_free(GTodoItem
*item
);
124 /* Get the ID from the GTodoItem */
125 guint32
gtodo_todo_item_get_id(GTodoItem
*item
);
127 /* There is no set ID because the ID should always be unique.. if you got good reasons to want this.. mail me */
130 /* enable or disable the flag that says if this item may produce a notification event */
131 void gtodo_todo_item_set_notify(GTodoItem
*item
, gboolean notify
);
133 /* get the status of the notification flag */
134 gboolean
gtodo_todo_item_get_notify(GTodoItem
*item
);
137 /* get the priority. see enumeration for possible return values */
138 int gtodo_todo_item_get_priority(GTodoItem
*item
);
140 /* set the priority, for possible value's look at the enumeration for possible values*/
141 void gtodo_todo_item_set_priority(GTodoItem
*item
, int priority
);
144 /* get the summary, the returned value should NOT be FREED.*/
145 /* I return an empty string when there is no value. */
146 char *gtodo_todo_item_get_summary(GTodoItem
*item
);
148 /* set the summary, also setting to NULL, or changing is allowed */
149 void gtodo_todo_item_set_summary(GTodoItem
*item
, gchar
*summary
);
152 /* get the category name, the returned value should NOT be freed.*/
153 char *gtodo_todo_item_get_category(GTodoItem
*item
);
155 /* get the category id, this is only needed internal */
156 /* can be handy if you want to switch items. */
157 gint
gtodo_client_get_category_id_from_list(GTodoList
*list
);
159 /* move the category up in the category list */
160 gboolean
gtodo_client_category_move_up(GTodoClient
*cl
, gchar
*name
);
161 /* move the category down in the category list */
162 gboolean
gtodo_client_category_move_down(GTodoClient
*cl
, gchar
*name
);
164 /* set the category, or changing is allowed. */
165 /* FIXME: if category exists, if not.. create it. */
166 void gtodo_todo_item_set_category(GTodoItem
*item
, gchar
*category
);
169 /* get the comment, this can be a multi line string */
170 char *gtodo_todo_item_get_comment(GTodoItem
*item
);
173 /* set the comment, setting to NULL is allowed, or changing */
174 void gtodo_todo_item_set_comment(GTodoItem
*item
, gchar
*comment
);
177 /*get the done flag */
178 gboolean
gtodo_todo_item_get_done(GTodoItem
*item
);
180 /* set the done flag */
181 /* this also sets the stop date (or unsets it) */
182 void gtodo_todo_item_set_done(GTodoItem
*item
, gboolean done
);
185 /* check if the GTodoItem is allready due on a day bases. you only need to check for time if it returns 0*/
186 /* > 0 allready due */
188 /* <0 due in future */
189 gint
gtodo_todo_item_check_due(GTodoItem
*item
);
192 /*returns the time in minutes that is still left.. it will return 0 when there is nothing left or if it isnt today. */
193 int gtodo_todo_item_check_due_time_minutes_left(GTodoItem
*item
);
195 /* get the due date in severall format's */
196 /* returned value represents an julian date ... 1 = no date set */
197 guint32
gtodo_todo_item_get_due_date_as_julian(GTodoItem
*item
);
200 /* set due date returns false when not able to set */
201 gboolean
gtodo_todo_item_set_due_date_as_julian(GTodoItem
*item
, guint32 julian
);
203 /* get the due date as an GDate */
204 GDate
* gtodo_todo_item_get_due_date(GTodoItem
*item
);
207 /* get localized string.. this needs to be FREED! */
208 gchar
*gtodo_todo_item_get_due_date_as_string(GTodoItem
*item
);
211 /* return the houre of the due time */
212 gint
gtodo_todo_item_get_due_time_houre(GTodoItem
*item
);
215 /* return the houre of the due time */
216 gint
gtodo_todo_item_get_due_time_minute(GTodoItem
*item
);
219 /* return the houre of the due time */
220 gint
gtodo_todo_item_set_due_time_minute(GTodoItem
*item
, gint minute
);
223 /* return the houre of the due time */
224 gint
gtodo_todo_item_set_due_time_houre(GTodoItem
*item
, gint houre
);
226 /* Get the last edited date in severall dates. */
227 /* The last edited date entry is modified when saving the gtodo item. (or changing) */
229 /* The returned value represent an julian date ... -1 = no date set */
230 guint32
gtodo_todo_item_get_last_edited_date_as_julian(GTodoItem
*item
);
232 /* FIXME: more formats needed? */
234 /* get or set the start date in severall format's */
235 /* returned value represent an julian date ... -1 = no date set */
236 guint32
gtodo_todo_item_get_start_date_as_julian(GTodoItem
*item
);
239 /* set start date returns false when not able to set */
240 gboolean
gtodo_todo_item_set_start_date_as_julian(GTodoItem
*item
, guint32 julian
);
243 /* get an localized string representing the start date.. this needs to be FREED! */
244 gchar
*gtodo_todo_item_get_start_date_as_string(GTodoItem
*item
);
246 /* get the stop date in severall format's */
247 /* returned value represent an julian date ... 1 = no date set */
248 guint32
gtodo_todo_item_get_stop_date_as_julian(GTodoItem
*item
);
251 /* set stop date as a julian date. returns false when not able to set */
252 gboolean
gtodo_todo_item_set_stop_date_as_julian(GTodoItem
*item
, guint32 julian
);
255 /* Set the stop date to today.. this is a function added to stop duplicating of code.*/
256 /* You probly don't need to use this, because it's allready set by the gtodo_item_set_done */
257 gboolean
gtodo_todo_item_set_stop_date_today(GTodoItem
*item
);
260 /* get localized string.. this needs to be FREED! */
261 gchar
*gtodo_todo_item_get_stop_date_as_string(GTodoItem
*item
);
264 /**************************** GTodoClient functions ******************************/
266 /* this causes the client to save its xml file... */
267 /* Only in very special cases you want todo this, */
268 /* its done automatically. USE WITH CARE */
269 int gtodo_client_save_xml(GTodoClient
*cl
, GError
**error
);
271 /* The above function should never to be used, this can be usefull f.e. backups or incase of syncronising */
272 int gtodo_client_save_xml_to_file(GTodoClient
*cl
, gchar
*file
, GError
**error
);
274 /* reloads the client backend data*/
275 int gtodo_client_reload(GTodoClient
*cl
);
278 int gtodo_client_load(GTodoClient
*cl
, const gchar
*xml_path
);
280 /* creates a new GTodoClient that opens the default backend */
281 GTodoClient
* gtodo_client_new_default(GError
**error
);
283 /* creates a new GTodoClient that opens and alternative backend location*/
284 GTodoClient
* gtodo_client_new_from_file(char *filename
, GError
**error
);
286 /* quit the client, it makes sure everything is saved and free's the needed data */
287 void gtodo_client_quit(GTodoClient
*cl
);
289 /* set the fucntion it should call when the todo database has changed */
290 /* function should be of type void functionname(GTodoType *cl, gpointer data); */
291 void gtodo_client_set_changed_callback(GTodoClient
*cl
, void *(*function
)(gpointer cl
, gpointer data
), gpointer data
);
293 /* destroys the changed callback */
294 void gtodo_client_destroy_changed_callback(GTodoClient
*cl
, void *(*function
)(gpointer cl
, gpointer data
), gpointer data
);
296 /* block the signal from being emitted.. */
297 void gtodo_client_block_changed_callback(GTodoClient
*cl
);
299 /* unblock the callback.. if there was a change between the block and the unblock it will be called after this function */
300 void gtodo_client_unblock_changed_callback(GTodoClient
*cl
);
303 /* if you don't want to have the callback function to be called between a block and unblock call this function directly before unblocking */
304 void gtodo_client_reset_changed_callback(GTodoClient
*cl
);
307 /************** GTodoLists ******************/
309 /* function to step through the list */
310 /* it will return FALSE when no more itmes in the list.*/
311 /* otherwise it will let list point to the next item */
312 gboolean
gtodo_client_get_list_next(GTodoList
*list
);
314 /* set the GTodoList to the first item in the list */
315 void gtodo_client_get_list_first(GTodoList
*list
);
317 /* get the category list.. Makesure you don't mix a Category list with a todo item list.. */
318 /* they use the same GTodoList, but the internall data is different */
319 /* the returned list has to be freed when no longer needed.*/
320 /* the returned list isnt kept up to date.. */
322 GTodoList
* gtodo_client_get_category_list(GTodoClient
*cl
);
324 /* free the Category list and all the items it contains*/
325 void gtodo_client_free_category_list(GTodoClient
*cl
, GTodoList
*list
);
327 /* get the category from the list, use gtodo_client_get_list_next to cycle through them, Don't free the result */
328 gchar
* gtodo_client_get_category_from_list(GTodoList
*list
);
330 /* get a GTodoList with GtodoItem. */
331 /* make sure you don't mix this one with an category list */
332 /* if you Pass NULL for the category you get all items in all categories */
333 /* the returned list has to be freed when no longer needed.*/
334 /* the returned list isnt kept up to date.. */
335 GTodoList
*gtodo_client_get_todo_item_list(GTodoClient
*cl
, gchar
*category
);
337 /* get an GTodoItem from the list.. you dont need to free this */
338 /* use gtodo_client_get_list_next to cycle through them*/
339 GTodoItem
*gtodo_client_get_todo_item_from_list(GTodoList
*list
);
341 /* free the todo's items */
342 void gtodo_client_free_todo_item_list(GTodoClient
*cl
, GTodoList
*list
);
344 /* get an todo item from is UID. */
345 /* returns NULL when it doesnt exists.. */
346 /* make sure you free the result */
347 GTodoItem
*gtodo_client_get_todo_item_from_id(GTodoClient
*cl
, guint32 id
);
350 /* saves an GtodoItem.. Dont use this to modify an GtodoItem.. */
351 /* if the todo item doesnt have a existing category, it will be created */
352 gboolean
gtodo_client_save_todo_item(GTodoClient
*cl
, GTodoItem
*item
);;
354 /* You should get the todo item first.. then edit the item and pass it to this function apply the changes*/
355 gboolean
gtodo_client_edit_todo_item(GTodoClient
*cl
, GTodoItem
*item
);
357 /* Delete an todo item by its ID*/
358 void gtodo_client_delete_todo_by_id(GTodoClient
*cl
, guint32 id
);
361 /* change the name of a Category*/
362 /* returns TRUE is successfull */
363 gboolean
gtodo_client_category_edit(GTodoClient
*cl
, gchar
*old
, gchar
*newn
);
365 /* Check if an category allready exists */
366 gboolean
gtodo_client_category_exists(GTodoClient
*cl
, gchar
*name
);
368 /* create a new category */
369 gboolean
gtodo_client_category_new(GTodoClient
*cl
, gchar
*name
);
371 /* remove a category and ALL the todo items in it */
372 gboolean
gtodo_client_category_remove(GTodoClient
*cl
, gchar
*name
);
377 /* it checks two GToDo items to test witch one is the last edited. */
378 /* it returns positive when base is newer and negative when test.*/
379 long int gtodo_item_compare_latest(GTodoItem
*base
, GTodoItem
*test
);
382 /* make duplicate an exact copy of source */
383 /* could be usefull for syncronising */
384 void gtodo_client_save_client_to_client(GTodoClient
*source
, GTodoClient
*duplicate
);