inc/gcalendar.h

   1 /*
   2   Copyright (c) 2008 Instituto Nokia de Tecnologia
   3   All rights reserved.
   4
   5   Redistribution and use in source and binary forms, with or without modification,
   6   are permitted provided that the following conditions are met:
   7
   8   * Redistributions of source code must retain the above copyright notice,
   9   this list of conditions and the following disclaimer.
  10   * Redistributions in binary form must reproduce the above copyright notice,
  11   this list of conditions and the following disclaimer in the documentation
  12   and/or other materials provided with the distribution.
  13   * Neither the name of the INdT nor the names of its contributors
  14   may be used to endorse or promote products derived from this software
  15   without specific prior written permission.
  16
  17   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  18   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  21   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27   POSSIBILITY OF SUCH DAMAGE.
  28 */
  29 /**
  30  * @file   gcalendar.h
  31  * @author Adenilson Cavalcanti da Silva <adenilson.silva@indt.org.br>
  32  * @date   Tue Jun 24 16:17:25 2008
  33  *
  34  * @brief  libgcal calendar user public API.
  35  *
  36  * Use this functions to handle common tasks when dealing with google calendar.
  37  */
  38
  39 #ifndef __GCALENDAR_LIB__
  40 #define __GCALENDAR_LIB__
  41
  42 #include "gcal.h"
  43
  44 /** Since user cannot create an static instance of it, it entitles itself
  45  * to be a completely abstract data type. See \ref gcal_event.
  46  */
  47 typedef struct gcal_event* gcal_event_t;
  48
  49
  50 /** Structure to hold events array, use it as a parameter for
  51  * \ref gcal_get_events.
  52  *
  53  * This structure will contain the number of retrieved entries, as also
  54  * the pointer to an array of \ref gcal_event structures.
  55  */
  56 struct gcal_event_array {
  57         /** See \ref gcal_event. */
  58         gcal_event_t entries;
  59         /** The number of entries */
  60         size_t length;
  61 };
  62
  63 /** Creates a new gcal object (you need then to talk with google
  64  * servers).
  65  *
  66  * @param mode Which google service to handle (GCONTACT and GCALENDAR)
  67  *
  68  * @return The new object on success or NULL otherwise.
  69  */
  70 gcal_t gcal_new(gservice mode);
  71
  72 /** Deletes a gcal object.
  73  *
  74  * @param gcal_obj A gcal object created with \ref gcal_new.
  75  */
  76 void gcal_delete(gcal_t gcal_obj);
  77
  78 /** Creates a new google calendar event object.
  79  *
  80  * If you are going to add new event, see also \ref gcal_add_event.
  81  *
  82  * @param raw_xml A string with google data XML of this entry.
  83  *
  84  * @return A gcal_event_t object on success or NULL otherwise.
  85  */
  86 gcal_event_t gcal_event_new(char *raw_xml);
  87
  88 /** Free an gcal event object.
  89  *
  90  *
  91  * @param event An gcal event object, see also \ref gcal_event_new.
  92  */
  93 void gcal_event_delete(gcal_event_t event);
  94
  95
  96 /** Helper function, does all calendar events dump and parsing, returning
  97  * the data as an array of \ref gcal_event. See too \ref gcal_event_array.
  98  *
  99  * @param gcalobj A libgcal object, must be previously authenticated with
 100  * \ref gcal_get_authentication.
 101  *
 102  * @param events_array Pointer to an events array structure. See
 103  * \ref gcal_event_array.
 104  *
 105  * @return 0 on success, -1 otherwise.
 106  */
 107 int gcal_get_events(gcal_t gcalobj, struct gcal_event_array *events_array);
 108
 109
 110 /** Use this function to cleanup an array of calendar events.
 111  *
 112  * See also \ref gcal_get_events.
 113  *
 114  * @param events A pointer to an events array structure. See
 115  * \ref gcal_event_array.
 116  */
 117 void gcal_cleanup_events(struct gcal_event_array *events);
 118
 119 /** Create a new event in user's calendar.
 120  *
 121  * You should have authenticate before using \ref gcal_get_authentication.
 122  *
 123  * @param gcal_obj A gcal object, see \ref gcal_new.
 124  *
 125  * @param event An event object, see \ref gcal_event_new.
 126  *
 127  * @return 0 on sucess, -1 otherwise.
 128  */
 129 int gcal_add_event(gcal_t gcal_obj, gcal_event_t event);
 130
 131 /** Updates an already existant event.
 132  *
 133  * Use it to update an event, but pay attention that you neeed to have
 134  * a valid event object (i.e. that has at least the edit_url to this entry).
 135  * See also \ref gcal_get_edit_url and \ref gcal_event_get_xml).
 136  *
 137  * A common use case is when you added a new event using \ref gcal_add_event
 138  * and later whant to edit it.
 139  *
 140  * @param gcal_obj A gcal object, see \ref gcal_new.
 141  *
 142  * @param event An event object.
 143  *
 144  * @return 0 on sucess, -1 otherwise.
 145  */
 146 int gcal_update_event(gcal_t gcal_obj, gcal_event_t event);
 147
 148 /** Deletes an event (pay attention that google server will mark this
 149  * event as 'cancelled').
 150  *
 151  * Being cancelled still makes possible to retrieve all the data of this
 152  * event (for a timeframe of a few weeks).
 153  *
 154  * The event object must be valid (i.e. has at least the edit_url to this
 155  * entry). See also \ref gcal_get_edit_url and \ref gcal_event_get_xml).
 156  *
 157  * @param gcal_obj A gcal object, see \ref gcal_new.
 158  *
 159  * @param event An event object.
 160  *
 161  * @return 0 on sucess, -1 otherwise.
 162  */
 163 int gcal_erase_event(gcal_t gcal_obj, gcal_event_t event);
 164
 165 /** Query for updated events (added/edited/deleted).
 166  *
 167  * Its going to retrieve only updated events from user's calendar, its
 168  * useful if you implementing sync software and have downloaded all events
 169  * at least one time.
 170  *
 171  * Use this function to get only the changed data.
 172  *
 173  * @param gcal_obj A gcal object, see \ref gcal_new.
 174  *
 175  * @param events A pointer to a struct of type \ref gcal_event_array.
 176  *
 177  * @param timestamp A timestamp in format RFC 3339 format
 178  * (e.g. 2008-09-10T21:00:00Z) (see \ref TIMESTAMP_MAX_SIZE and
 179  * \ref get_mili_timestamp). It can include timezones too.
 180  * If you just want to get the updated events starting from today at 06:00Z,
 181  * use NULL as parameter.
 182  *
 183  * @return 0 on sucess, -1 otherwise.
 184  */
 185 int gcal_get_updated_events(gcal_t gcal_obj, struct gcal_event_array *events,
 186                             char *timestamp);
 187
 188
 189 /** Helper function, extracts the edit URL in a XML entry
 190  *
 191  * The use of this function is a corner case: say that you just added an event
 192  * (so you dont have the gevent object for some reason) and want to load a
 193  * completely different event (say from a XML file) and want to update the
 194  * event with the new data.
 195  * You need to being able to access the older edit_url from the raw XML (that
 196  * I hope its still available somewhere) and that is when this function can
 197  * save your ass.
 198  *
 199  * A better approach would just create a new event object out from the older
 200  * XML data and use \ref gcal_event_get_url.
 201  * \todo: revise the real need of this function (at least as a public function).
 202  *
 203  * @param entry A pointer to a string that represents an event as raw XML.
 204  *
 205  * @param extracted_url This will be loaded with the edit_url, remember to free
 206  * it up.
 207  *
 208  * @return 0 on sucess, -1 otherwise.
 209  */
 210 int gcal_get_edit_url(char *entry, char **extracted_url);
 211
 212 /** Helper function, extracts the ETag code in a XML entry, required by
 213  * (Google Data API 2.0).
 214  *
 215  * The use of this function is a corner case: say that you just added an event
 216  * (so you dont have the gevent object for some reason) and want to load a
 217  * completely different event (say from a XML file) and want to update the
 218  * event with the new data.
 219  * You need to being able to access the older ETag from the raw XML (that
 220  * I hope its still available somewhere) and that is when this function can
 221  * save your ass.
 222  *
 223  * A better approach would just create a new event object out from the older
 224  * XML data and use \ref gcal_event_get_url. See also \ref gcal_get_edit_url.
 225  * \todo: revise the real need of this function (at least as a public function).
 226  *
 227  * @param entry A pointer to a string that represents an event as raw XML.
 228  *
 229  * @param extracted_etag This will be loaded with the edit_url, remember to free
 230  * it up.
 231  *
 232  * @return 0 on sucess, -1 otherwise.
 233  */
 234 int gcal_get_extract_etag(char *entry, char **extracted_etag);
 235
 236 /* Raw XML base functions: common for both calendar/contacts */
 237
 238 /** Adds a new entry (event or contact) in to user's feed, using raw xml.
 239  *
 240  * Use this if you already have the input data as a valid atom entry
 241  * XML data.  You don't need to create an entry object (gcal_event or
 242  * gcal_contact).
 243  *
 244  * A context where this function is handy is if you are going to load the
 245  * entries from XML files. Another context is if you use XSLT to convert
 246  * from another XML format (e.g. opensync) to create the gdata format.
 247  *
 248  * @param gcal_obj A gcal object, see \ref gcal_new.
 249  *
 250  * @param xml_entry A pointer to a string with XML representing the entry.
 251  *
 252  * @param xml_updated A pointer to pointer to string, it will have the updated
 253  * entry with new fields (updated, edit_url, ID). Remember to clean up this
 254  * memory. If you don't care about getting this information, just pass NULL.
 255  *
 256  * @return 0 on sucess, -1 otherwise.
 257  */
 258 int gcal_add_xmlentry(gcal_t gcal_obj, char *xml_entry, char **xml_updated);
 259
 260
 261 /** Updates an entry (event or contact) using raw xml.
 262  *
 263  * For rationale of xml functions, see \ref gcal_add_xmlentry. Use it to update
 264  * (i.e. change) an entry.
 265  *
 266  * @param gcal_obj A gcal object, see \ref gcal_new.
 267  *
 268  * @param xml_entry A pointer to a string with XML representing the entry.
 269  *
 270  * @param xml_updated A pointer to pointer to string, it will have the updated
 271  * entry with new fields (updated, edit_url, ID). Remember to clean up this
 272  * memory. If you don't care about getting this information, just pass NULL.
 273  *
 274  * @param edit_url Common case, pass NULL (it assumes that 'xml_entry' has
 275  * a valid edit_url field). Case negative, you can supply the edit_url using
 276  * this parameter.
 277  *
 278  * @param etag Common case, pass NULL (it assumes that 'xml_entry' has
 279  * a valid etag field). Case negative, you can supply the etag using
 280  * this parameter. Required by Google Data protocols 2.0.
 281  *
 282  * @return 0 on sucess, -1 otherwise.
 283  */
 284 int gcal_update_xmlentry(gcal_t gcal_obj, char *xml_entry, char **xml_updated,
 285                          char *edit_url, char *etag);
 286
 287
 288 /** Deletes an entry (event or contact) using raw xml.
 289  *
 290  * For rationale of xml functions, see \ref gcal_add_xmlentry. Use it to update
 291  * (i.e. change) an entry.
 292  *
 293  * @param gcal_obj A gcal object, see \ref gcal_new.
 294  *
 295  * @param xml_entry A pointer to a string with XML representing the entry. It
 296  * has to have a valid edit_url field or operation will fail (i.e. you must
 297  * have created this xml out of an pre-existant entry).
 298  *
 299  * @return 0 on sucess, -1 otherwise.
 300  */
 301 int gcal_erase_xmlentry(gcal_t gcal_obj, char *xml_entry);
 302
 303
 304 /** Returns an event element from an event array.
 305  *
 306  * Since to final user events are abstract types, even if is possible to access
 307  * internal \ref gcal_event_array vector of events, its not possible to do
 308  * pointer arithmetic with it. Use this function as an
 309  * accessor to them.
 310  * A context where this function is useful is when downloading all events
 311  * from user calendar using \ref gcal_get_events.
 312  *
 313  * @param events An array of events, see \ref gcal_event_array.
 314  *
 315  * @param _index Index of element (is zero based).
 316  *
 317  * @return Either a pointer to the event object or NULL.
 318  */
 319 gcal_event_t gcal_event_element(struct gcal_event_array *events, size_t _index);
 320
 321
 322 /* Here starts gcal_event accessors */
 323
 324 /** Access event ID.
 325  *
 326  * Each entry has a unique ID assigned by google server.
 327  *
 328  * @param event An event object, see \ref gcal_event.
 329  *
 330  * @return Pointer to internal object field (dont free it!) or NULL (in error
 331  * case or if the field is not set). If the entry hasn't this field in the
 332  * atom stream, it will be set to an empty string (i.e. "").
 333  */
 334 char *gcal_event_get_id(gcal_event_t event);
 335
 336 /** Access last updated timestamp.
 337  *
 338  * Each operation (add/edit/delete) will set a timestamp to the entry.
 339  *
 340  * @param event An event object, see \ref gcal_event.
 341  *
 342  * @return Pointer to internal object field (dont free it!) or NULL (in error
 343  * case or if the field is not set). If the entry hasn't this field in the
 344  * atom stream, it will be set to an empty string (i.e. "").
 345  */
 346 char *gcal_event_get_updated(gcal_event_t event);
 347
 348 /** Access event title.
 349  *
 350  * All entries have a title, with semantic depending on the entry type:
 351  * events (event title) or contact (contact name).
 352  *
 353  * @param event An event object, see \ref gcal_event.
 354  *
 355  * @return Pointer to internal object field (dont free it!) or NULL (in error
 356  * case or if the field is not set). If the entry hasn't this field in the
 357  * atom stream, it will be set to an empty string (i.e. "").
 358  */
 359 char *gcal_event_get_title(gcal_event_t event);
 360
 361 /** Access the edit_url field.
 362  *
 363  * All entries have an edit_url field (which is the combo of ID+cookie) that
 364  * must be used to do operations (edit/delete).
 365  *
 366  * @param event An event object, see \ref gcal_event.
 367  *
 368  * @return Pointer to internal object field (dont free it!) or NULL (in error
 369  * case or if the field is not set). If the entry hasn't this field in the
 370  * atom stream, it will be set to an empty string (i.e. "").
 371  */
 372 char *gcal_event_get_url(gcal_event_t event);
 373
 374 /** Access the etag field.
 375  *
 376  * All entries have an etag field (required by Google Data API 2.0) that
 377  * must be used to do operations (edit/delete).
 378  *
 379  * @param event An event object, see \ref gcal_event.
 380  *
 381  * @return Pointer to internal object field (dont free it!) or NULL (in error
 382  * case or if the field is not set). If the entry hasn't this field in the
 383  * atom stream, it will be set to an empty string (i.e. "").
 384  */
 385 char *gcal_event_get_etag(gcal_event_t event);
 386
 387 /** Access the raw XML representation of the entry.
 388  *
 389  * Besides having the more important information already parsed, its still
 390  * possible to access the raw xml of the entry if and *only* if you set
 391  * this mode in \ref gcal_t object using \ref gcal_set_store_xml function
 392  * *before* getting the data (using \ref gcal_get_events).
 393  *
 394  * @param event An event object, see \ref gcal_event.
 395  *
 396  * @return Pointer to internal object field (dont free it!) or NULL (in error
 397  * case or if the field is not set).
 398  */
 399 char *gcal_event_get_xml(gcal_event_t event);
 400
 401
 402 /** Checks if the current event was deleted or not.
 403  *
 404  * When parsing the entry, the respective element used to represent deleted or
 405  * cancelled status (for calendar events) is stored internally of event object.
 406  *
 407  * @param event An event object, see \ref gcal_event.
 408  *
 409  * @return 1 for deleted, 0 for not deleted, -1 for error case (f the event
 410  * object is invalid).
 411  */
 412 char gcal_event_is_deleted(gcal_event_t event);
 413
 414
 415 /* This are the fields unique to calendar events */
 416
 417 /** Access event description.
 418  *
 419  * Events have an extra field for description (like: "Meeting with someone and
 420  * remember to discuss whatever targeting do something").
 421  *
 422  * @param event An event object, see \ref gcal_event.
 423  *
 424  * @return Pointer to internal object field (dont free it!) or NULL (in error
 425  * case or if the field is not set). If the entry hasn't this field in the
 426  * atom stream, it will be set to an empty string (i.e. "").
 427  */
 428 char *gcal_event_get_content(gcal_event_t event);
 429
 430 /** Checks if this is a recurrent event.
 431  *
 432  * Case positive, it will return the string with the representation of recurrence
 433  * rule. Google calendar uses a subset of iCalendar to represent this (yeah, brain
 434  * f*ked in my opinion put another text format inside of XML...). See more
 435  * information here: http://code.google.com/apis/calendar/developers_guide_protocol.html#CreatingRecurring
 436  *
 437  * @param event An event object, see \ref gcal_event.
 438  *
 439  * @return Pointer to internal object field (dont free it!) or NULL (in error
 440  * case or if the field is not set). If the entry hasn't this field in the
 441  * atom stream, it will be set to an empty string (i.e. "").
 442  */
 443 char *gcal_event_get_recurrent(gcal_event_t event);
 444
 445 /** Access event start timestamp.
 446  *
 447  * Google calendar uses RFC 3339 format (e.g. "2008-09-11T21:00:00Z") to represent
 448  * when an event will start. It can have the timezone information too
 449  * (e.g. "2008-09-11T12:39:00-04:00" for a -4hours from UTC timezone, a.k.a. Manaus).
 450  *
 451  * @param event An event object, see \ref gcal_event.
 452  *
 453  * @return Pointer to internal object field (dont free it!) or NULL (in error
 454  * case or if the field is not set). If the entry hasn't this field in the
 455  * atom stream, it will be set to an empty string (i.e. "").
 456  */
 457 char *gcal_event_get_start(gcal_event_t event);
 458
 459 /** Access event end timestamp.
 460  *
 461  * See too \ref gcal_event_get_start for further discussion.
 462  *
 463  * @param event An event object, see \ref gcal_event.
 464  *
 465  * @return Pointer to internal object field (dont free it!) or NULL (in error
 466  * case or if the field is not set). If the entry hasn't this field in the
 467  * atom stream, it will be set to an empty string (i.e. "").
 468  */
 469 char *gcal_event_get_end(gcal_event_t event);
 470
 471 /** Access event location/place.
 472  *
 473  * Google calendar allows to store any string as the place where the event
 474  * will happen (even GPS coordinates).
 475  *
 476  * @param event An event object, see \ref gcal_event.
 477  *
 478  * @return Pointer to internal object field (dont free it!) or NULL (in error
 479  * case or if the field is not set). If the entry hasn't this field in the
 480  * atom stream, it will be set to an empty string (i.e. "").
 481  */
 482 char *gcal_event_get_where(gcal_event_t event);
 483
 484
 485 /** Access event status.
 486  *
 487  * An event can have some status (confirmed/cancelled) and its possible to
 488  * access then. For while, libgcal store the whole URL with the description
 489  * of event status (e.g. "http://schemas.google.com/g/2005#event.confirmed").
 490  * \todo Use enumeration to represent status.
 491  *
 492  * @param event An event object, see \ref gcal_event.
 493  *
 494  * @return Pointer to internal object field (dont free it!) or NULL (in error
 495  * case or if the field is not set). If the entry hasn't this field in the
 496  * atom stream, it will be set to an empty string (i.e. "").
 497  */
 498 char *gcal_event_get_status(gcal_event_t event);
 499
 500
 501 /* Here starts the setters */
 502
 503 /** Sets event title.
 504  *
 505  * Use this to assign an event title (or to change it if you wish to update an
 506  * already existant calendar event).
 507  *
 508  * @param event An event object, see \ref gcal_event and \ref gcal_event_new.
 509  *
 510  * @param field String with event title (e.g. "Dinner with Mary").
 511  *
 512  * @return 0 for sucess, -1 otherwise.
 513  */
 514 int gcal_event_set_title(gcal_event_t event, const char *field);
 515
 516 /** Set event detailed description.
 517  *
 518  * See also \ref gcal_event_get_content for an example of valid description.
 519  *
 520  * @param event An event object, see \ref gcal_event and \ref gcal_event_new.
 521  *
 522  * @param field A string with event description.
 523  *
 524  * @return 0 for sucess, -1 otherwise.
 525  */
 526 int gcal_event_set_content(gcal_event_t event, const char *field);
 527
 528 /** Set event start time.
 529  *
 530  * See also \ref gcal_event_get_start.
 531  *
 532  * @param event An event object, see \ref gcal_event and \ref gcal_event_new.
 533  *
 534  * @param field A string with the timestamp for start time using RFC 3339 format
 535  * (e.g. "2008-09-11T21:00:00Z").
 536  *
 537  * @return 0 for sucess, -1 otherwise.
 538  */
 539 int gcal_event_set_start(gcal_event_t event, const char *field);
 540
 541
 542 /** Set event end time.
 543  *
 544  * See also \ref gcal_event_set_start.
 545  *
 546  * @param event An event object, see \ref gcal_event and \ref gcal_event_new.
 547  *
 548  * @param field A string with the timestamp for start time using RFC 3339 format
 549  * (e.g. "2008-09-11T22:00:00Z").
 550  *
 551  * @return 0 for sucess, -1 otherwise.
 552  */
 553 int gcal_event_set_end(gcal_event_t event, const char *field);
 554
 555 /** Set event location/place.
 556  *
 557  * See also \ref gcal_event_get_where.
 558  *
 559  * @param event An event object, see \ref gcal_event and \ref gcal_event_new.
 560  *
 561  * @param field The place where event is supposed to happen (e.g. "Nearby an
 562  * nice pub, close the church")
 563  *
 564  * @return 0 for sucess, -1 otherwise.
 565  */
 566 int gcal_event_set_where(gcal_event_t event, const char *field);
 567
 568 /* TODO: Not implemented */
 569
 570 /** Sets recurrence rule.
 571  *
 572  * \todo implement this method, its just stub now.
 573  * @param event An event object, see \ref gcal_event and \ref gcal_event_new.
 574  *
 575  * @param field A string with google invalid iCalendar format
 576  * to represent recurrence rules.
 577  *
 578  * @return 0 for sucess, -1 otherwise.
 579  */
 580 int gcal_event_set_recurrent(gcal_event_t event, const char *field);
 581
 582 /** Set event status (for while, all then were created as 'confirmed').
 583  *
 584  * \todo implement this method, its just stub now.
 585  * @param event An event object, see \ref gcal_event and \ref gcal_event_new.
 586  *
 587  * @param field Status description (should I use enums or string?).
 588  *
 589  * @return 0 for sucess, -1 otherwise.
 590  */
 591 int gcal_event_set_status(gcal_event_t event, const char *field);
 592
 593 /** Sets event edit url.
 594  *
 595  * This field is a hard requirement to edit/delete a event. Starting with
 596  * google data API 2.0, the ETag is also required.
 597  *
 598  * @param event A event object, see \ref gcal_event.
 599  *
 600  * @param field String with the edit url email
 601  * (e.g. "http://www.google.com/m8/feeds/events/user%40gmail.com/base/2").
 602  *
 603  * @return 0 for sucess, -1 otherwise.
 604  */
 605 int gcal_event_set_url(gcal_event_t event, const char *field);
 606
 607
 608 /** Sets event ID.
 609  *
 610  * Each event has an ID (but this can extracted from the edit_url).
 611  *
 612  * @param event A event object, see \ref gcal_event.
 613  *
 614  * @param field String with event ID (e.g. "joe.doe@nobody.com").
 615  *
 616  * @return 0 for sucess, -1 otherwise.
 617  */
 618 int gcal_event_set_id(gcal_event_t event, const char *field);
 619
 620
 621 /** Sets event ETag.
 622  *
 623  * Starting with google data API 2.0, the ETag is used for versioning the
 624  * entries. Is required for edit/delete.
 625  *
 626  * @param event A event object, see \ref gcal_event.
 627  *
 628  * @param field String with event ETag (e.g. "Q3c5eDVSLyp7ImA9WxRbFE0KRAY.").
 629  *
 630  * @return 0 for sucess, -1 otherwise.
 631  */
 632 int gcal_event_set_etag(gcal_event_t event, const char *field);
 633
 634
 635
 636
 637 #endif