inc/gcontact.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   gcontact.h
  31  * @author Adenilson Cavalcanti da Silva <adenilson.silva@indt.org.br>
  32  * @date   Thu Jun 26 07:25:35 2008
  33  *
  34  * @brief  libgcal contacts user public API.
  35  *
  36  * Use this functions to handle common tasks when dealing with google contacts.
  37  */
  38
  39 #ifndef __GCONTACT_LIB__
  40 #define __GCONTACT_LIB__
  41
  42 #include "gcal.h"
  43 #include "gcont.h"
  44
  45 /** Since user cannot create an static instance of it, it entitles itself
  46  * to be a completely abstract data type. See \ref gcal_contact.
  47  */
  48 typedef struct gcal_contact* gcal_contact_t;
  49
  50 typedef struct gcal_structured_subvalues *gcal_structured_subvalues_t;
  51
  52 /** Contact entries array. Its used to hold retrieved contacts
  53  * retrieved from google server.
  54  */
  55 struct gcal_contact_array {
  56         /** See \ref gcal_contact. */
  57         gcal_contact_t entries;
  58         /** The number of entries */
  59         size_t length;
  60 };
  61
  62 /** Phone number types allowed by Google API */
  63 typedef enum {
  64         P_INVALID = -1,
  65         P_ASSISTANT,
  66         P_CALLBACK,
  67         P_CAR,
  68         P_COMPANY_MAIN,
  69         P_FAX,
  70         P_HOME,
  71         P_HOME_FAX,
  72         P_ISDN,
  73         P_MAIN,
  74         P_MOBILE,
  75         P_OTHER,
  76         P_OTHER_FAX,
  77         P_PAGER,
  78         P_RADIO,
  79         P_TELEX,
  80         P_TTY_TDD,
  81         P_WORK,
  82         P_WORK_FAX,
  83         P_WORK_MOBILE,
  84         P_WORK_PAGER,
  85         P_ITEMS_COUNT                   // must be the last one!
  86 } gcal_phone_type;
  87
  88 /** Email types allowed by Google API */
  89 typedef enum {
  90         E_INVALID = -1,
  91         E_HOME,
  92         E_OTHER,
  93         E_WORK,
  94         E_ITEMS_COUNT                   // must be the last one!
  95 } gcal_email_type;
  96
  97 /** Address types allowed by Google API */
  98 typedef enum {
  99         A_INVALID = -1,
 100         A_HOME,
 101         A_WORK,
 102         A_OTHER,
 103         A_ITEMS_COUNT                   // must be the last one!
 104 } gcal_address_type;
 105
 106 /** IM types allowed by Google API */
 107 typedef enum {
 108         I_INVALID = -1,
 109         I_HOME,
 110         I_WORK,
 111         I_NETMEETING,
 112         I_OTHER,
 113         I_ITEMS_COUNT                   // must be the last one!
 114 } gcal_im_type;
 115
 116 /** Creates a new google contact object.
 117  *
 118  * If you are going to add new contact, see also \ref gcal_add_contact.
 119  *
 120  * @param raw_xml A string with google data XML of this entry.
 121  *
 122  * @return A gcal_contact object on success or NULL otherwise.
 123  */
 124 gcal_contact_t gcal_contact_new(char *raw_xml);
 125
 126 /** Free a gcal contact object.
 127  *
 128  *
 129  * @param contact An gcal contact object, see also \ref gcal_contact_new.
 130  */
 131 void gcal_contact_delete(gcal_contact_t contact);
 132
 133
 134 /** Helper function, does all contact dump and parsing, returning
 135  * the data as an array of \ref gcal_contact.
 136  *
 137  * @param gcalobj A libgcal object, must be previously authenticated with
 138  * \ref gcal_get_authentication. See also \ref gcal_new.
 139  *
 140  * @param contact_array Pointer to a contact array structure. See
 141  * \ref gcal_contact_array.
 142  *
 143  * @return 0 on success, -1 otherwise.
 144  */
 145 int gcal_get_contacts(gcal_t gcalobj, struct gcal_contact_array *contact_array);
 146
 147 /** Use this function to cleanup an array of contacts.
 148  *
 149  * See also \ref gcal_get_contacts.
 150  *
 151  * @param contacts A pointer to an contacts array structure. See
 152  * \ref gcal_contact_array.
 153  */
 154 void gcal_cleanup_contacts(struct gcal_contact_array *contacts);
 155
 156
 157 /** Returns a contact element from a contact array.
 158  *
 159  * Since to final user contacts are abstract types, even if is possible to
 160  * access internal \ref gcal_contact_array vector of contacts, its not
 161  * possible to do pointer arithmetic. Use this function as an
 162  * accessor to them.
 163  * A context where this function is useful is when downloading all contacts
 164  * from user account using \ref gcal_get_contacts.
 165  *
 166  * @param contacts An array of contacts, see \ref gcal_contact_array.
 167  *
 168  * @param _index Index of element (is zero based).
 169  *
 170  * @return Either a pointer to the event object or NULL.
 171  */
 172 gcal_contact_t gcal_contact_element(struct gcal_contact_array *contacts,
 173                                     size_t _index);
 174
 175 /** Add a new contat in user's account.
 176  *
 177  * You should have authenticate before using \ref gcal_get_authentication.
 178  *
 179  * @param gcalobj A gcal object, see \ref gcal_new.
 180  *
 181  * @param contact A contact object, see \ref gcal_contact.
 182  *
 183  * @return 0 on sucess, -1 otherwise.
 184  */
 185 int gcal_add_contact(gcal_t gcalobj, gcal_contact_t contact);
 186
 187
 188 /** Updates an already existant contact.
 189  *
 190  * Use it to update a contact, but pay attention that you neeed to have
 191  * a valid contact object (i.e. that has at least the edit_url to this entry).
 192  * See also \ref gcal_get_edit_url and \ref gcal_contact_get_xml).
 193  *
 194  * A common use case is when you added a new contact using \ref gcal_add_contact
 195  * and later whant to edit it.
 196  *
 197  * @param gcalobj A gcal object, see \ref gcal_new.
 198  *
 199  * @param contact A contact object, see \ref gcal_contact.
 200  *
 201  * @return 0 on sucess, -1 otherwise.
 202  */
 203 int gcal_update_contact(gcal_t gcalobj, gcal_contact_t contact);
 204
 205
 206 /** Deletes a contact (once you do this, is not possible to recover the
 207  * information from this contact, only the ID).
 208  *
 209  * The behavior is different from calendar events, where is possible to
 210  * retrieve all the data from a deleted event.
 211  *
 212  * @param gcalobj A gcal object, see \ref gcal_new.
 213  *
 214  * @param contact A contact object, see \ref gcal_contact.
 215  *
 216  * @return 0 on sucess, -1 otherwise.
 217  */
 218 int gcal_erase_contact(gcal_t gcalobj, gcal_contact_t contact);
 219
 220 /** Query for updated contacts (added/edited/deleted).
 221  *
 222  * Pay attention that by default, google server will hide deleted contacts.
 223  * If you need to access them, remember to set it using \ref gcal_deleted
 224  * *before* requesting the data.
 225  *
 226  * Use this function to get only the changed data. Somewhat related, see too
 227  * \ref gcal_get_updated_events.
 228  *
 229  * @param gcal_obj A libgcal object, must be previously authenticated with
 230  * \ref gcal_get_authentication. See also \ref gcal_new.
 231  *
 232  * @param contacts Pointer to a contact array structure. See
 233  * \ref gcal_contact_array.
 234  *
 235  * @param timestamp A timestamp in format RFC 3339 format
 236  * (e.g. 2008-09-10T21:00:00Z) (see \ref TIMESTAMP_MAX_SIZE and
 237  * \ref get_mili_timestamp). It can include timezones too.
 238  * If you just want to get the updated events starting from today at 06:00Z,
 239  * use NULL as parameter.
 240  *
 241  * @return 0 on success, -1 otherwise.
 242  */
 243 int gcal_get_updated_contacts(gcal_t gcal_obj,
 244                               struct gcal_contact_array *contacts,
 245                               char *timestamp);
 246
 247
 248 /* Here starts gcal_contact accessors */
 249
 250 /** Access contact ID.
 251  *
 252  * Each entry has a unique ID assigned by google server.
 253  *
 254  * @param contact A contact object, see \ref gcal_contact.
 255  *
 256  * @return Pointer to internal object field (dont free it!) or NULL (in error
 257  * case or if the field is not set). If the entry hasn't this field in the
 258  * atom stream, it will be set to an empty string (i.e. "").
 259  */
 260 char *gcal_contact_get_id(gcal_contact_t contact);
 261
 262 /** Access last updated timestamp.
 263  *
 264  * Not only each operation will change the updated timestamp of a contact,
 265  * but I *guess* that (in the case of a google account contact) your
 266  * contact can change this too.
 267  *
 268  * @param contact A contact object, see \ref gcal_contact.
 269  *
 270  * @return Pointer to internal object field (dont free it!) or NULL (in error
 271  * case or if the field is not set). If the entry hasn't this field in the
 272  * atom stream, it will be set to an empty string (i.e. "").
 273  */
 274 char *gcal_contact_get_updated(gcal_contact_t contact);
 275
 276 /** Access contact name.
 277  *
 278  * All entries have a title, with semantic depending on the entry type:
 279  * events (event title) or contact (contact name).
 280  *
 281  * @param contact A contact object, see \ref gcal_contact.
 282  *
 283  * @return Pointer to internal object field (dont free it!) or NULL (in error
 284  * case or if the field is not set). If the entry hasn't this field in the
 285  * atom stream, it will be set to an empty string (i.e. "").
 286  */
 287 char *gcal_contact_get_title(gcal_contact_t contact);
 288
 289 /** Access the edit_url field.
 290  *
 291  * All entries have an edit_url field (which is the combo of ID+cookie) that
 292  * must be used to do operations (edit/delete).
 293  * See also \ref gcal_get_edit_url.
 294  *
 295  * @param contact A contact object, see \ref gcal_contact.
 296  *
 297  * @return Pointer to internal object field (dont free it!) or NULL (in error
 298  * case or if the field is not set). If the entry hasn't this field in the
 299  * atom stream, it will be set to an empty string (i.e. "").
 300  */
 301 char *gcal_contact_get_url(gcal_contact_t contact);
 302
 303
 304 /** Access the ETag
 305  *
 306  * All entries have an etag field (Google Data API 2.0) that must be used
 307  * to do operations (edit/delete). See also \ref gcal_get_edit_etag.
 308  *
 309  * @param contact A contact object, see \ref gcal_contact.
 310  *
 311  * @return Pointer to internal object field (dont free it!) or NULL (in error
 312  * case or if the field is not set). If the entry hasn't this field in the
 313  * atom stream, it will be set to an empty string (i.e. "").
 314  */
 315 char *gcal_contact_get_etag(gcal_contact_t contact);
 316
 317 /** Access the raw XML representation of the entry.
 318  *
 319  * Besides having the more important information already parsed, its still
 320  * possible to access the raw xml of the entry if and *only* if you set
 321  * this mode in \ref gcal_t object using \ref gcal_set_store_xml function
 322  * *before* getting the data (using \ref gcal_get_contacts).
 323  *
 324  * @param contact A contact object, see \ref gcal_contact.
 325  *
 326  * @return Pointer to internal object field (dont free it!) or NULL (in error
 327  * case or if the field is not set). If the entry hasn't this field in the
 328  * atom stream, it will be set to an empty string (i.e. "").
 329  */
 330 char *gcal_contact_get_xml(gcal_contact_t contact);
 331
 332 /** Checks if the current event was deleted or not.
 333  *
 334  * When parsing the entry, the respective element used to represent deleted
 335  * is stored internally of contact object.
 336  *
 337  * @param contact A contact object, see \ref gcal_contact.
 338  *
 339  * @return 1 for deleted, 0 for not deleted, -1 for error case (f the event
 340  * object is invalid).
 341  */
 342 char gcal_contact_is_deleted(gcal_contact_t contact);
 343
 344
 345 /* This are the fields unique to contacts */
 346
 347 /** Access contact e-mail.
 348  *
 349  * Email has an important rule for google contacts, since its the only
 350  * really required field to being able to add a new entry in user's
 351  * contact list.
 352  * It needs to be unique, no 2 contacts can have the same e-mail.
 353  *
 354  * @param contact A contact object, see \ref gcal_contact.
 355  *
 356  * @return Pointer to internal object field (dont free it!) or NULL (in error
 357  * case or if the field is not set). If the entry hasn't this field in the
 358  * atom stream, it will be set to an empty string (i.e. "").
 359
 360  */
 361 /* TODO: document new functions */
 362 int gcal_contact_get_emails_count(gcal_contact_t contact);
 363 int gcal_contact_get_pref_email(gcal_contact_t contact);
 364 char *gcal_contact_get_email_address(gcal_contact_t contact, int i);
 365 gcal_email_type gcal_contact_get_email_address_type(gcal_contact_t contact, int i);
 366
 367 /** Access contact description.
 368  *
 369  * This the place where contacts notes can be retrieved.
 370  *
 371  * @param contact A contact object, see \ref gcal_contact.
 372  *
 373  * @return Pointer to internal object field (dont free it!) or NULL (in error
 374  * case or if the field is not set). If the entry hasn't this field in the
 375  * atom stream, it will be set to an empty string (i.e. "").
 376  */
 377 char *gcal_contact_get_content(gcal_contact_t contact);
 378
 379 /** Access contact nickname.
 380  *
 381  * @param contact A contact object, see \ref gcal_contact.
 382  *
 383  * @return  Pointer to internal object field
 384  */
 385 char *gcal_contact_get_nickname(gcal_contact_t contact);
 386
 387 /** Access contact organization name.
 388  *
 389  *
 390  * @param contact A contact object, see \ref gcal_contact.
 391  *
 392  * @return Pointer to internal object field (dont free it!) or NULL (in error
 393  * case or if the field is not set). If the entry hasn't this field in the
 394  * atom stream, it will be set to an empty string (i.e. "").
 395
 396  */
 397 char *gcal_contact_get_organization(gcal_contact_t contact);
 398
 399 /** Access contact organization title/profission.
 400  *
 401  *
 402  * @param contact A contact object, see \ref gcal_contact.
 403  *
 404  * @return Pointer to internal object field (dont free it!) or NULL (in error
 405  * case or if the field is not set). If the entry hasn't this field in the
 406  * atom stream, it will be set to an empty string (i.e. "").
 407
 408  */
 409 char *gcal_contact_get_profission(gcal_contact_t contact);
 410
 411 /** Access contact occupation/profession.
 412  *
 413  * @param contact A contact object, see \ref gcal_contact.
 414  *
 415  * @return Pointer to internal object field (dont free it!) or NULL (in error
 416  * case or if the field is not set). If the entry hasn't this field in the
 417  * atom stream, it will be set to an empty string (i.e. "").
 418
 419  */
 420 char *gcal_contact_get_occupation(gcal_contact_t contact);
 421
 422 /** Access contact website.
 423  *
 424  * @param contact A contact object, see \ref gcal_contact.
 425  *
 426  * @return Pointer to internal object field
 427  */
 428 char *gcal_contact_get_homepage(gcal_contact_t contact);
 429
 430 /** Access contact blog.
 431  *
 432  * @param contact A contact object, see \ref gcal_contact.
 433  *
 434  * @return Pointer to internal object field
 435  */
 436 char *gcal_contact_get_blog(gcal_contact_t contact);
 437
 438 /** Access contact telephone.
 439  *
 440  * @param contact A contact object, see \ref gcal_contact.
 441  *
 442  * @return Pointer to internal object field (dont free it!) or NULL (in error
 443  * case or if the field is not set). If the entry hasn't this field in the
 444  * atom stream, it will be set to an empty string (i.e. "").
 445
 446  */
 447 /* TODO: document new functions */
 448 int gcal_contact_get_phone_numbers_count(gcal_contact_t contact);
 449 char *gcal_contact_get_phone_number(gcal_contact_t contact, int i);
 450 gcal_phone_type gcal_contact_get_phone_number_type(gcal_contact_t contact, int i);
 451
 452 /** Access contact IM count.
 453  *
 454  * @param contact A contact object, see \ref gcal_contact.
 455  *
 456  * @return Number of IM entries.
 457  *
 458  */
 459 int gcal_contact_get_im_count(gcal_contact_t contact);
 460
 461 /** Access contact preferred IM account.
 462  *
 463  * @param contact A contact object, see \ref gcal_contact.
 464  *
 465  * @return Number of preferred IM account.
 466  *
 467  */
 468 int gcal_contact_get_pref_im(gcal_contact_t contact);
 469
 470 /** Access contact IM protocol.
 471  *
 472  * @param contact A contact object, see \ref gcal_contact.
 473  *
 474  * @param i Number of the IM entry
 475  *
 476  * @return Pointer to internal object field.
 477  */
 478 char *gcal_contact_get_im_protocol(gcal_contact_t contact, int i);
 479
 480 /** Access contact IM address.
 481  *
 482  * @param contact A contact object, see \ref gcal_contact.
 483  *
 484  * @param i Number of the IM entry
 485  *
 486  * @return Pointer to internal object field.
 487  */
 488 char *gcal_contact_get_im_address(gcal_contact_t contact, int i);
 489
 490 /** Access contact IM type.
 491  *
 492  * @param contact A contact object, see \ref gcal_contact.
 493  *
 494  * @param i Number of the IM entry
 495  *
 496  * @return Type of the IM account.
 497  */
 498 gcal_phone_type gcal_contact_get_im_type(gcal_contact_t contact, int i);
 499
 500 /** Access contact address (structuredPostalAddress.formattedAddress).
 501  *
 502  * @param contact A contact object, see \ref gcal_contact.
 503  *
 504  * @return Pointer to internal object field (dont free it!) or NULL (in error
 505  * case or if the field is not set). If the entry hasn't this field in the
 506  * atom stream, it will be set to an empty string (i.e. "").
 507
 508  */
 509 char *gcal_contact_get_address(gcal_contact_t contact);
 510
 511 /** Access structured address objects.
 512  *
 513  * @param contact A contact object, see \ref gcal_contact.
 514  *
 515  * @return Pointer to internal object field
 516  */
 517 gcal_structured_subvalues_t gcal_contact_get_structured_address(gcal_contact_t contact);
 518
 519 /** Access structured name object.
 520  *
 521  * @param contact A contact object, see \ref gcal_contact.
 522  *
 523  * @return Pointer to internal object field
 524  */
 525 gcal_structured_subvalues_t gcal_contact_get_structured_name(gcal_contact_t contact);
 526
 527 /** Get one structured entry.
 528  *
 529  * @param structured_entry A structured entry object, see \ref gcal_structured_subvalues.
 530  *
 531  * @param structured_entry_nr Index of the entry.
 532  *
 533  * @param structured_entry_count Number of all entries.
 534  *
 535  * @param field_key Key of the structured entry.
 536  *
 537  * @return Pointer to internal object field
 538  */
 539 char *gcal_contact_get_structured_entry(gcal_structured_subvalues_t structured_entry, int structured_entry_nr, int structured_entry_count, const char *field_key);
 540
 541 /** Access structured entry count.
 542  *
 543  * @param contact A contact object, see \ref gcal_contact.
 544  *
 545  * @return Number of structured entries
 546  */
 547 int gcal_contact_get_structured_address_count(gcal_contact_t contact);
 548
 549 /** Access structured address count object.
 550  *
 551  * @param contact A contact object, see \ref gcal_contact.
 552  *
 553  * @return Pointer to internal object field
 554  */
 555 int *gcal_contact_get_structured_address_count_obj(gcal_contact_t contact);
 556
 557 /** Access structured entry type.
 558  *
 559  * @param contact A contact object, see \ref gcal_contact.
 560  *
 561  * @param structured_entry_nr The number of the specific entry.
 562  *
 563  * @param structured_entry_count Number of all entries.
 564  *
 565  * @return Type of entry
 566  */
 567 gcal_address_type gcal_contact_get_structured_address_type(gcal_contact_t contact, int structured_entry_nr, int structured_entry_count);
 568
 569 /** Access structured address type object.
 570  *
 571  * @param contact A contact object, see \ref gcal_contact.
 572  *
 573  * @return Pointer to internal object field
 574  */
 575 char ***gcal_contact_get_structured_address_type_obj(gcal_contact_t contact);
 576
 577 /** Access Google group membership info.
 578  *
 579  * @param contact A contact object, see \ref gcal_contact.
 580  *
 581  * @return Pointer to internal object field (dont free it!) or NULL (in error
 582  * case or if the field is not set). If the entry hasn't this field in the
 583  * atom stream, it will be set to an empty string (i.e. "").
 584
 585  */
 586 int gcal_contact_get_groupMembership_count(gcal_contact_t contact);
 587 /* TODO: document new functions */
 588 char *gcal_contact_get_groupMembership(gcal_contact_t contact, int i);
 589
 590 /** Access contact birthday.
 591  *
 592  * @param contact A contact object, see \ref gcal_contact.
 593  *
 594  * @return Pointer to internal object field (dont free it!) or NULL (in error
 595  * case or if the field is not set). If the entry hasn't this field in the
 596  * atom stream, it will be set to an empty string (i.e. "").
 597  */
 598 char *gcal_contact_get_birthday(gcal_contact_t contact);
 599
 600 /** Access contact photo data.
 601  *
 602  * When no year is set in Google, Year is set to 1900 in KABC
 603  *
 604  * @param contact A contact object, see \ref gcal_contact.
 605  *
 606  * @return Pointer to internal object field (dont free it!) or NULL (in error
 607  * case or if the field is not set). If the entry hasn't this field in the
 608  * atom stream, it will be set to an empty string (i.e. "").
 609  */
 610 char *gcal_contact_get_photo(gcal_contact_t contact);
 611
 612 /** Access contact photo data length.
 613  *
 614  * It can required to known where the data ends (since is a binary blob
 615  * you cannot use strlen).
 616  *
 617  * @param contact A contact object, see \ref gcal_contact.
 618  *
 619  * @return 0 for no photo, 1 for photo link existence and > 1 when having the
 620  * photo data. -1 for error case.
 621  */
 622 unsigned int gcal_contact_get_photolength(gcal_contact_t contact);
 623
 624 /* Here starts the gcal_contact setters */
 625
 626 /** Sets contact name.
 627  *
 628  * Use this to assign a contact's name (or to change it if you wish to update an
 629  * already existant contact).
 630  *
 631  * @param contact A contact object, see \ref gcal_contact.
 632  *
 633  * @param field String with contact name (e.g. "Joe Doe").
 634  *
 635  * @return 0 for sucess, -1 otherwise.
 636  */
 637 int gcal_contact_set_title(gcal_contact_t contact, const char *field);
 638
 639 /** Sets contact email.
 640  *
 641  * This field is a hard requirement to create a new contact. Google server
 642  * supports more e-mails with special tags too.
 643  *
 644  * If you need to add a contact entry with all optional fields, an
 645  * alternative is to use \ref gcal_add_xmlentry.
 646  *
 647  * @param contact A contact object, see \ref gcal_contact.
 648  *
 649  * @param field Email address..
 650  *
 651  * @param type Email address type.
 652  *
 653  * @param pref Preferred email address (0=no, 1=yes).
 654  *
 655  * @return 0 for success, -1 otherwise
 656  */
 657
 658 int gcal_contact_add_email_address(gcal_contact_t contact, const char *field,
 659                                    gcal_email_type type, int pref);
 660
 661 /* TODO: document new functions */
 662 int gcal_contact_delete_email_addresses(gcal_contact_t contact);
 663
 664
 665 /** Sets contact edit url.
 666  *
 667  * This field is a hard requirement to edit/delete a contact. Starting with
 668  * google data API 2.0, the ETag is also required.
 669  *
 670  * @param contact A contact object, see \ref gcal_contact.
 671  *
 672  * @param field String with the edit url email
 673  * (e.g. "http://www.google.com/m8/feeds/contacts/user%40gmail.com/base/2").
 674  *
 675  * @return 0 for sucess, -1 otherwise.
 676  */
 677 int gcal_contact_set_url(gcal_contact_t contact, const char *field);
 678
 679
 680 /** Sets contact ID.
 681  *
 682  * Each contact has an ID (but this can extracted from the edit_url).
 683  *
 684  * @param contact A contact object, see \ref gcal_contact.
 685  *
 686  * @param field String with contact ID (e.g. "joe.doe@nobody.com").
 687  *
 688  * @return 0 for sucess, -1 otherwise.
 689  */
 690 int gcal_contact_set_id(gcal_contact_t contact, const char *field);
 691
 692
 693 /** Sets contact ETag.
 694  *
 695  * Starting with google data API 2.0, the ETag is used for versioning the
 696  * entries. Is required for edit/delete.
 697  *
 698  * @param contact A contact object, see \ref gcal_contact.
 699  *
 700  * @param field String with contact ETag (e.g. "Q3c5eDVSLyp7ImA9WxRbFE0KRAY.").
 701  *
 702  * @return 0 for sucess, -1 otherwise.
 703  */
 704 int gcal_contact_set_etag(gcal_contact_t contact, const char *field);
 705
 706
 707
 708 /** Sets the contact telephone.
 709  *
 710  * @param contact A contact object, see \ref gcal_contact.
 711  *
 712  * @param field Phone number.
 713  *
 714  * @param type Phone number type.
 715  *
 716  * @return 0 for success, -1 otherwise
 717  */
 718 int gcal_contact_add_phone_number(gcal_contact_t contact, const char *field,
 719                                   gcal_phone_type type);
 720
 721 /* TODO: document new functions */
 722 int gcal_contact_delete_phone_numbers(gcal_contact_t contact);
 723
 724 /** Sets contact IM.
 725  *
 726  * @param contact A contact object, see \ref gcal_contact.
 727  *
 728  * @param protcol IM protocol.
 729  *
 730  * @param address IM address.
 731  *
 732  * @param type IM type.
 733  *
 734  * @return 0 for success, -1 otherwise
 735  */
 736 int gcal_contact_add_im(gcal_contact_t contact, const char *protcol,
 737                         const char *address, gcal_im_type type, int pref);
 738
 739 /** Deletes contact IM.
 740  *
 741  * @param contact A contact object, see \ref gcal_contact.
 742  *
 743  * @return 0 for success, -1 otherwise
 744  */
 745 int gcal_contact_delete_im(gcal_contact_t contact);
 746
 747 /** Sets the contact address (Google API v2.0 gd:postalAddress).
 748  *
 749  * @param contact A contact object, see \ref gcal_contact.
 750  *
 751  * @param field Address string.
 752  *
 753  * @return 0 for success, -1 otherwise
 754  */
 755 int gcal_contact_set_address(gcal_contact_t contact, const char *field);
 756
 757 /** Sets the contact full address number (structuredPostalAddress).
 758  *
 759  * @param contact A contact object, see \ref gcal_contact.
 760  *
 761  * @param type Address type.
 762  *
 763  * @return 0 for success, -1 otherwise
 764  */
 765 int gcal_contact_set_structured_address_nr(gcal_contact_t contact,
 766                                            gcal_address_type type);
 767
 768 /** Sets a structured entry.
 769  *
 770  * @param structured_entry A structured entry object, see \ref gcal_structured_subvalues.
 771  *
 772  * @param structured_entry_nr Index of the entry.
 773  *
 774  * @param structured_entry_count Number of all entries.
 775  *
 776  * @param field_key Key of the structured entry.
 777  *
 778  * @param field_value Corresponding value.
 779  *
 780  * @param structured_entry_type Structured entry type.
 781  *
 782  * @return 0 for success, -1 otherwise
 783  */
 784 int gcal_contact_set_structured_entry(gcal_structured_subvalues_t structured_entry,
 785                                       int structured_entry_nr,
 786                                       int structured_entry_count,
 787                                       const char *field_key,
 788                                       const char *field_value );
 789
 790 /** Deletes a structured entry.
 791  *
 792  * @param structured_entry A structured entry object, see \ref gcal_structured_subvalues.
 793  *
 794  * @param *structured_entry_count Pointer to the structured entry count object.
 795  *
 796  * @param ***structured_entry_type Pointer to the structured entry type object.
 797  *
 798  * @return 0 for success, -1 otherwise
 799  */
 800 int gcal_contact_delete_structured_entry(gcal_structured_subvalues_t structured_entry,
 801                                          int *structured_entry_count,
 802                                          char ***structured_entry_type);
 803
 804 /** Sets the contact group membership info.
 805  *
 806  * @param contact A contact object, see \ref gcal_contact.
 807  *
 808  * @param field Group name.
 809  *
 810  * @return 0 for success, -1 otherwise
 811  */
 812 int gcal_contact_add_groupMembership(gcal_contact_t contact, char *field);
 813
 814 /* TODO: document new functions */
 815 int gcal_contact_delete_groupMembership(gcal_contact_t contact);
 816
 817
 818 /** Sets the contact birthday
 819  *
 820  * When no year is set in Google, Year is set to 1900 in KABC
 821  *
 822  * @param contact A contact object, see \ref gcal_contact.
 823  *
 824  * @param field birthday string.
 825  *
 826  * @return 0 for success, -1 otherwise
 827  */
 828 int gcal_contact_set_birthday(gcal_contact_t contact, const char *field);
 829
 830 /** Sets the organization title.
 831  *
 832  *
 833  * @param contact A contact object, see \ref gcal_contact.
 834  *
 835  * @param field Organization title string (i.e. "C++ programmer").
 836  *
 837  * @return 0 for success, -1 otherwise
 838  */
 839 int gcal_contact_set_profission(gcal_contact_t contact, const char *field);
 840
 841 /** Sets the organization name.
 842  *
 843  *
 844  * @param contact A contact object, see \ref gcal_contact.
 845  *
 846  * @param field Organization name string (i.e. "Foo Software Inc.").
 847  *
 848  * @return 0 for success, -1 otherwise
 849  */
 850 int gcal_contact_set_organization(gcal_contact_t contact, const char *field);
 851
 852 /** Sets the occupation/profession.
 853  *
 854  *
 855  * @param contact A contact object, see \ref gcal_contact.
 856  *
 857  * @param field occupation/profession name string (i.e. "Carpenter").
 858  *
 859  * @return 0 for success, -1 otherwise
 860  */
 861 int gcal_contact_set_occupation(gcal_contact_t contact, const char *field);
 862
 863 /** Sets contact description.
 864  *
 865  * @param contact A contact object, see \ref gcal_contact.
 866  *
 867  * @param field A note, description (i.e. "Really funny guy")
 868  *
 869  * @return 0 for success, -1 otherwise
 870  */
 871 int gcal_contact_set_content(gcal_contact_t contact, const char *field);
 872
 873 /** Sets contact nickname.
 874  *
 875  * @param contact A contact object, see \ref gcal_contact.
 876  *
 877  * @param field The nickname
 878  *
 879  * @return 0 for success, -1 otherwise
 880  */
 881 int gcal_contact_set_nickname(gcal_contact_t contact, const char *field);
 882
 883 /** Sets contact website.
 884  *
 885  * @param contact A contact object, see \ref gcal_contact.
 886  *
 887  * @param field URL
 888  *
 889  * @return 0 for success, -1 otherwise
 890  */
 891 int gcal_contact_set_homepage(gcal_contact_t contact, const char *field);
 892
 893 /** Sets contact blog.
 894  *
 895  * @param contact A contact object, see \ref gcal_contact.
 896  *
 897  * @param field URL
 898  *
 899  * @return 0 for success, -1 otherwise
 900  */
 901 int gcal_contact_set_blog(gcal_contact_t contact, const char *field);
 902
 903 /* TODO: document new functions */
 904 int gcal_contact_set_photo(gcal_contact_t contact, const char *field,
 905                            int length);
 906
 907
 908 #endif