plugins/gtodo/libgtodo.h

   1 #ifndef __LIBGTODO__
   2 #define __LIBGTODO__
   3
   4 #include <libgnomevfs/gnome-vfs.h>
   5 #include <libxml/parser.h>
   6 #include <libxml/tree.h>
   7 #define GTODO_NO_DUE_DATE 99999999
   8 /* the GError stuff */
   9 #define LIBGTODO_ERROR g_quark_from_static_string("libgtodo-error-quark")
  10
  11 enum{
  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,
  20         LIBGTODO_ERROR_XML
  21 }LibGTodoError;
  22
  23 enum {
  24         GTODO_DUE_TIME_HOURE,
  25         GTODO_DUE_TIME_MINUTE
  26 };
  27
  28 /* The structure used by the gtodo client, The user shouldnt have to use ANY
  29    of the internal variables, NEVER */
  30
  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 */
  35         gpointer data;
  36         /* the last time the backend was edited */
  37         time_t last_edit;
  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?) */
  41         gchar *xml_path;
  42         /* the pointer to the xml structure */
  43         xmlDocPtr gtodo_doc;
  44         /* pointer to the first node */
  45         xmlNodePtr root;
  46         /* number of categories */
  47         gint number_of_categories;
  48         /* permissions */
  49         gboolean read_only;
  50 } GTodoClient;
  51
  52 /* The GTodoList structure..  */
  53 /* NO public fields */
  54 typedef struct _GTodoList{
  55         GList *list;
  56         GList *first;
  57 } GTodoList;
  58
  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
  62  */
  63
  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 */
  67         GTime id;
  68
  69         /* last edited, probly needed for syncing and stuff */
  70         GTime last_edited;
  71
  72         /* Creation Date.  And possible end date */
  73         GDate *start;
  74
  75         /* if NULL no due date*/
  76         GDate *stop;
  77
  78         /* Done */
  79         gboolean done;
  80
  81         /* if the item should notify when done */
  82         gboolean notify;
  83
  84         /* Category name */
  85         gchar *category;
  86
  87         /* due date if NULL no due date*/
  88         GDate *due;
  89
  90         /* due_time[0] houre due_time[1] minute */
  91         /* see enumeration above */
  92         int due_time[2];
  93
  94         /* Priority  see enumeration*/
  95         gint priority;
  96
  97         /* summary */
  98         gchar *summary;
  99
 100         /* comment */
 101         gchar *comment;
 102
 103 } GTodoItem;
 104
 105 /* the three different priorities..   try to use this enumeration */
 106 enum    {
 107         GTODO_PRIORITY_LOW,
 108         GTODO_PRIORITY_MEDIUM,
 109         GTODO_PRIORITY_HIGH
 110 };
 111
 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);
 117
 118 /* create a new unique GTodoItem,use this to add an todo item */
 119 GTodoItem * gtodo_client_create_new_todo_item(GTodoClient *cl);
 120
 121 /* free's an GTodoItem */
 122 void gtodo_todo_item_free(GTodoItem *item);
 123
 124 /* Get the ID from the GTodoItem  */
 125 guint32 gtodo_todo_item_get_id(GTodoItem *item);
 126
 127 /* There is no set ID because the ID should always be unique.. if you got good reasons to want this.. mail me */
 128
 129
 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);
 132
 133 /* get the status of the notification flag */
 134 gboolean gtodo_todo_item_get_notify(GTodoItem *item);
 135
 136
 137 /* get the priority. see enumeration for possible return values */
 138 int gtodo_todo_item_get_priority(GTodoItem *item);
 139
 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);
 142
 143
 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);
 147
 148 /* set the summary, also setting to NULL, or changing is allowed */
 149 void gtodo_todo_item_set_summary(GTodoItem *item, gchar *summary);
 150
 151
 152 /* get the category name, the returned value should NOT be freed.*/
 153 char *gtodo_todo_item_get_category(GTodoItem *item);
 154
 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);
 158
 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);
 163
 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);
 167
 168
 169 /* get the comment, this can be a multi line string */
 170 char *gtodo_todo_item_get_comment(GTodoItem *item);
 171
 172
 173 /* set the comment, setting to NULL is allowed, or changing */
 174 void gtodo_todo_item_set_comment(GTodoItem *item, gchar *comment);
 175
 176
 177 /*get the done flag */
 178 gboolean gtodo_todo_item_get_done(GTodoItem *item);
 179
 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);
 183
 184
 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 */
 187 /* 0 due today */
 188 /* <0 due in future */
 189 gint gtodo_todo_item_check_due(GTodoItem *item);
 190
 191
 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);
 194
 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);
 198
 199
 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);
 202
 203 /* get the due date as an GDate */
 204 GDate * gtodo_todo_item_get_due_date(GTodoItem *item);
 205
 206
 207 /* get localized string.. this needs to be FREED! */
 208 gchar *gtodo_todo_item_get_due_date_as_string(GTodoItem *item);
 209
 210
 211 /* return the houre of the due time */
 212 gint gtodo_todo_item_get_due_time_houre(GTodoItem *item);
 213
 214
 215 /* return the houre of the due time */
 216 gint gtodo_todo_item_get_due_time_minute(GTodoItem *item);
 217
 218
 219 /* return the houre of the due time */
 220 gint gtodo_todo_item_set_due_time_minute(GTodoItem *item, gint minute);
 221
 222
 223 /* return the houre of the due time */
 224 gint gtodo_todo_item_set_due_time_houre(GTodoItem *item, gint houre);
 225
 226 /* Get the last edited date in severall dates. */
 227 /* The last edited date entry is modified when saving the gtodo item. (or changing) */
 228
 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);
 231
 232 /* FIXME: more formats needed? */
 233
 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);
 237
 238
 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);
 241
 242
 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);
 245
 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);
 249
 250
 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);
 253
 254
 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);
 258
 259
 260 /* get localized string.. this needs to be FREED! */
 261 gchar *gtodo_todo_item_get_stop_date_as_string(GTodoItem *item);
 262
 263
 264 /**************************** GTodoClient functions ******************************/
 265
 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);
 270
 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);
 273
 274 /* reloads the client backend data*/
 275 int gtodo_client_reload(GTodoClient *cl);
 276
 277 /* Loads a file */
 278 int gtodo_client_load(GTodoClient *cl, const gchar *xml_path);
 279
 280 /* creates a new GTodoClient that opens the default backend */
 281 GTodoClient * gtodo_client_new_default(GError **error);
 282
 283 /* creates a new GTodoClient that opens and alternative backend location*/
 284 GTodoClient * gtodo_client_new_from_file(char *filename, GError **error);
 285
 286 /* quit the client, it makes sure everything is saved and free's the needed data */
 287 void gtodo_client_quit(GTodoClient *cl);
 288
 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);
 292
 293 /* destroys the changed callback */
 294 void gtodo_client_destroy_changed_callback(GTodoClient *cl, void *(*function)(gpointer cl, gpointer data), gpointer data);
 295
 296 /* block the signal from being emitted.. */
 297 void gtodo_client_block_changed_callback(GTodoClient *cl);
 298
 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);
 301
 302 /* Deprecated now */
 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);
 305
 306
 307 /************** GTodoLists ******************/
 308
 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);
 313
 314 /* set the GTodoList to the first item in the list */
 315 void gtodo_client_get_list_first(GTodoList *list);
 316
 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.. */
 321
 322 GTodoList * gtodo_client_get_category_list(GTodoClient *cl);
 323
 324 /* free the Category list and all the items it contains*/
 325 void gtodo_client_free_category_list(GTodoClient *cl, GTodoList *list);
 326
 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);
 329
 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);
 336
 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);
 340
 341 /* free the todo's items */
 342 void gtodo_client_free_todo_item_list(GTodoClient *cl, GTodoList *list);
 343
 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);
 348
 349
 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);;
 353
 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);
 356
 357 /* Delete an todo item by its ID*/
 358 void gtodo_client_delete_todo_by_id(GTodoClient *cl, guint32 id);
 359
 360
 361 /* change the name of a Category*/
 362 /* returns TRUE is successfull */
 363 gboolean gtodo_client_category_edit(GTodoClient *cl, gchar *old, gchar *newn);
 364
 365 /* Check if an category allready exists */
 366 gboolean gtodo_client_category_exists(GTodoClient *cl, gchar *name);
 367
 368 /* create a new category */
 369 gboolean gtodo_client_category_new(GTodoClient *cl, gchar *name);
 370
 371 /* remove a category and ALL the todo items in it */
 372 gboolean gtodo_client_category_remove(GTodoClient *cl, gchar *name);
 373
 374
 375
 376
 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);
 380
 381
 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);
 385
 386 #endif