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 char *gcal_contact_get_email(gcal_contact_t contact);
 368
 369 /** Access contact description.
 370  *
 371  * This the place where contacts notes can be retrieved.
 372  *
 373  * @param contact A contact object, see \ref gcal_contact.
 374  *
 375  * @return Pointer to internal object field (dont free it!) or NULL (in error
 376  * case or if the field is not set). If the entry hasn't this field in the
 377  * atom stream, it will be set to an empty string (i.e. "").
 378  */
 379 char *gcal_contact_get_content(gcal_contact_t contact);
 380
 381 /** Access contact nickname.
 382  *
 383  * @param contact A contact object, see \ref gcal_contact.
 384  *
 385  * @return  Pointer to internal object field
 386  */
 387 char *gcal_contact_get_nickname(gcal_contact_t contact);
 388
 389 /** Access contact organization name.
 390  *
 391  *
 392  * @param contact A contact object, see \ref gcal_contact.
 393  *
 394  * @return Pointer to internal object field (dont free it!) or NULL (in error
 395  * case or if the field is not set). If the entry hasn't this field in the
 396  * atom stream, it will be set to an empty string (i.e. "").
 397
 398  */
 399 char *gcal_contact_get_organization(gcal_contact_t contact);
 400
 401 /** Access contact organization title/profission.
 402  *
 403  *
 404  * @param contact A contact object, see \ref gcal_contact.
 405  *
 406  * @return Pointer to internal object field (dont free it!) or NULL (in error
 407  * case or if the field is not set). If the entry hasn't this field in the
 408  * atom stream, it will be set to an empty string (i.e. "").
 409
 410  */
 411 char *gcal_contact_get_profission(gcal_contact_t contact);
 412
 413 /** Access contact occupation/profession.
 414  *
 415  * @param contact A contact object, see \ref gcal_contact.
 416  *
 417  * @return Pointer to internal object field (dont free it!) or NULL (in error
 418  * case or if the field is not set). If the entry hasn't this field in the
 419  * atom stream, it will be set to an empty string (i.e. "").
 420
 421  */
 422 char *gcal_contact_get_occupation(gcal_contact_t contact);
 423
 424 /** Access contact website.
 425  *
 426  * @param contact A contact object, see \ref gcal_contact.
 427  *
 428  * @return Pointer to internal object field
 429  */
 430 char *gcal_contact_get_homepage(gcal_contact_t contact);
 431
 432 /** Access contact blog.
 433  *
 434  * @param contact A contact object, see \ref gcal_contact.
 435  *
 436  * @return Pointer to internal object field
 437  */
 438 char *gcal_contact_get_blog(gcal_contact_t contact);
 439
 440 /** Access contact telephone.
 441  *
 442  * @param contact A contact object, see \ref gcal_contact.
 443  *
 444  * @return Pointer to internal object field (dont free it!) or NULL (in error
 445  * case or if the field is not set). If the entry hasn't this field in the
 446  * atom stream, it will be set to an empty string (i.e. "").
 447
 448  */
 449 /* TODO: document new functions */
 450 int gcal_contact_get_phone_numbers_count(gcal_contact_t contact);
 451 char *gcal_contact_get_phone_number(gcal_contact_t contact, int i);
 452 gcal_phone_type gcal_contact_get_phone_number_type(gcal_contact_t contact, int i);
 453 char *gcal_contact_get_phone(gcal_contact_t contact);
 454
 455 /** Access contact IM count.
 456  *
 457  * @param contact A contact object, see \ref gcal_contact.
 458  *
 459  * @return Number of IM entries.
 460  *
 461  */
 462 int gcal_contact_get_im_count(gcal_contact_t contact);
 463
 464 /** Access contact preferred IM account.
 465  *
 466  * @param contact A contact object, see \ref gcal_contact.
 467  *
 468  * @return Number of preferred IM account.
 469  *
 470  */
 471 int gcal_contact_get_pref_im(gcal_contact_t contact);
 472
 473 /** Access contact IM protocol.
 474  *
 475  * @param contact A contact object, see \ref gcal_contact.
 476  *
 477  * @param i Number of the IM entry
 478  *
 479  * @return Pointer to internal object field.
 480  */
 481 char *gcal_contact_get_im_protocol(gcal_contact_t contact, int i);
 482
 483 /** Access contact IM address.
 484  *
 485  * @param contact A contact object, see \ref gcal_contact.
 486  *
 487  * @param i Number of the IM entry
 488  *
 489  * @return Pointer to internal object field.
 490  */
 491 char *gcal_contact_get_im_address(gcal_contact_t contact, int i);
 492
 493 /** Access contact IM type.
 494  *
 495  * @param contact A contact object, see \ref gcal_contact.
 496  *
 497  * @param i Number of the IM entry
 498  *
 499  * @return Type of the IM account.
 500  */
 501 gcal_phone_type gcal_contact_get_im_type(gcal_contact_t contact, int i);
 502
 503 /** Access contact address (structuredPostalAddress.formattedAddress).
 504  *
 505  * @param contact A contact object, see \ref gcal_contact.
 506  *
 507  * @return Pointer to internal object field (dont free it!) or NULL (in error
 508  * case or if the field is not set). If the entry hasn't this field in the
 509  * atom stream, it will be set to an empty string (i.e. "").
 510
 511  */
 512 char *gcal_contact_get_address(gcal_contact_t contact);
 513
 514 /** Access structured address objects.
 515  *
 516  * @param contact A contact object, see \ref gcal_contact.
 517  *
 518  * @return Pointer to internal object field
 519  */
 520 gcal_structured_subvalues_t gcal_contact_get_structured_address(gcal_contact_t contact);
 521
 522 /** Access structured name object.
 523  *
 524  * @param contact A contact object, see \ref gcal_contact.
 525  *
 526  * @return Pointer to internal object field
 527  */
 528 gcal_structured_subvalues_t gcal_contact_get_structured_name(gcal_contact_t contact);
 529
 530 /** Get one structured entry.
 531  *
 532  * @param structured_entry A structured entry object, see \ref gcal_structured_subvalues.
 533  *
 534  * @param structured_entry_nr Index of the entry.
 535  *
 536  * @param structured_entry_count Number of all entries.
 537  *
 538  * @param field_key Key of the structured entry.
 539  *
 540  * @return Pointer to internal object field
 541  */
 542 char *gcal_contact_get_structured_entry(gcal_structured_subvalues_t structured_entry, int structured_entry_nr, int structured_entry_count, const char *field_key);
 543
 544 /** Access structured entry count.
 545  *
 546  * @param contact A contact object, see \ref gcal_contact.
 547  *
 548  * @return Number of structured entries
 549  */
 550 int gcal_contact_get_structured_address_count(gcal_contact_t contact);
 551
 552 /** Access structured address count object.
 553  *
 554  * @param contact A contact object, see \ref gcal_contact.
 555  *
 556  * @return Pointer to internal object field
 557  */
 558 int *gcal_contact_get_structured_address_count_obj(gcal_contact_t contact);
 559
 560 /** Access structured entry type.
 561  *
 562  * @param contact A contact object, see \ref gcal_contact.
 563  *
 564  * @param structured_entry_nr The number of the specific entry.
 565  *
 566  * @param structured_entry_count Number of all entries.
 567  *
 568  * @return Type of entry
 569  */
 570 gcal_address_type gcal_contact_get_structured_address_type(gcal_contact_t contact, int structured_entry_nr, int structured_entry_count);
 571
 572 /** Access structured address type object.
 573  *
 574  * @param contact A contact object, see \ref gcal_contact.
 575  *
 576  * @return Pointer to internal object field
 577  */
 578 char ***gcal_contact_get_structured_address_type_obj(gcal_contact_t contact);
 579
 580 /** Access preferred structured address number.
 581  *
 582  * @param contact A contact object, see \ref gcal_contact.
 583  *
 584  * @return Number of preferred structured address.
 585  *
 586  */
 587 int gcal_contact_get_pref_structured_address(gcal_contact_t contact);
 588
 589 /** Access Google group membership info.
 590  *
 591  * @param contact A contact object, see \ref gcal_contact.
 592  *
 593  * @return Pointer to internal object field (dont free it!) or NULL (in error
 594  * case or if the field is not set). If the entry hasn't this field in the
 595  * atom stream, it will be set to an empty string (i.e. "").
 596
 597  */
 598 int gcal_contact_get_groupMembership_count(gcal_contact_t contact);
 599 /* TODO: document new functions */
 600 char *gcal_contact_get_groupMembership(gcal_contact_t contact, int i);
 601
 602 /** Access contact birthday.
 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_birthday(gcal_contact_t contact);
 611
 612 /** Access contact photo data.
 613  *
 614  * When no year is set in Google, Year is set to 1900 in KABC
 615  *
 616  * @param contact A contact object, see \ref gcal_contact.
 617  *
 618  * @return Pointer to internal object field (dont free it!) or NULL (in error
 619  * case or if the field is not set). If the entry hasn't this field in the
 620  * atom stream, it will be set to an empty string (i.e. "").
 621  */
 622 char *gcal_contact_get_photo(gcal_contact_t contact);
 623
 624 /** Access contact photo data length.
 625  *
 626  * It can required to known where the data ends (since is a binary blob
 627  * you cannot use strlen).
 628  *
 629  * @param contact A contact object, see \ref gcal_contact.
 630  *
 631  * @return 0 for no photo, 1 for photo link existence and > 1 when having the
 632  * photo data. -1 for error case.
 633  */
 634 unsigned int gcal_contact_get_photolength(gcal_contact_t contact);
 635
 636 /* Here starts the gcal_contact setters */
 637
 638 /** Sets contact name.
 639  *
 640  * Use this to assign a contact's name (or to change it if you wish to update an
 641  * already existant contact).
 642  *
 643  * @param contact A contact object, see \ref gcal_contact.
 644  *
 645  * @param field String with contact name (e.g. "Joe Doe").
 646  *
 647  * @return 0 for sucess, -1 otherwise.
 648  */
 649 int gcal_contact_set_title(gcal_contact_t contact, const char *field);
 650
 651 /** Sets contact email.
 652  *
 653  * This field is a hard requirement to create a new contact. Google server
 654  * supports more e-mails with special tags too.
 655  *
 656  * If you need to add a contact entry with all optional fields, an
 657  * alternative is to use \ref gcal_add_xmlentry.
 658  *
 659  * @param contact A contact object, see \ref gcal_contact.
 660  *
 661  * @param field Email address.
 662  *
 663  * @param type Email address type.
 664  *
 665  * @param pref Preferred email address (0=no, 1=yes).
 666  *
 667  * @return 0 for success, -1 otherwise
 668  */
 669
 670 int gcal_contact_add_email_address(gcal_contact_t contact, const char *field,
 671                                    gcal_email_type type, int pref);
 672
 673 /** Sets the prefered email.
 674  *
 675  * This is a convenience function, it is implemented internally using
 676  * \ref gcal_contact_add_email_address.
 677  *
 678  * The email type defauls to HOME.
 679  *
 680  * @param contact A contact object, see \ref gcal_contact.
 681  *
 682  * @param pref_email Email address.
 683  *
 684  * @return 0 for success, -1 otherwise
 685  */
 686 int gcal_contact_set_email(gcal_contact_t contact, const char *pref_email);
 687
 688
 689 /* TODO: document new functions */
 690 int gcal_contact_delete_email_addresses(gcal_contact_t contact);
 691
 692
 693 /** Sets contact edit url.
 694  *
 695  * This field is a hard requirement to edit/delete a contact. Starting with
 696  * google data API 2.0, the ETag is also required.
 697  *
 698  * @param contact A contact object, see \ref gcal_contact.
 699  *
 700  * @param field String with the edit url email
 701  * (e.g. "http://www.google.com/m8/feeds/contacts/user%40gmail.com/base/2").
 702  *
 703  * @return 0 for sucess, -1 otherwise.
 704  */
 705 int gcal_contact_set_url(gcal_contact_t contact, const char *field);
 706
 707
 708 /** Sets contact ID.
 709  *
 710  * Each contact has an ID (but this can extracted from the edit_url).
 711  *
 712  * @param contact A contact object, see \ref gcal_contact.
 713  *
 714  * @param field String with contact ID (e.g. "joe.doe@nobody.com").
 715  *
 716  * @return 0 for sucess, -1 otherwise.
 717  */
 718 int gcal_contact_set_id(gcal_contact_t contact, const char *field);
 719
 720
 721 /** Sets contact ETag.
 722  *
 723  * Starting with google data API 2.0, the ETag is used for versioning the
 724  * entries. Is required for edit/delete.
 725  *
 726  * @param contact A contact object, see \ref gcal_contact.
 727  *
 728  * @param field String with contact ETag (e.g. "Q3c5eDVSLyp7ImA9WxRbFE0KRAY.").
 729  *
 730  * @return 0 for sucess, -1 otherwise.
 731  */
 732 int gcal_contact_set_etag(gcal_contact_t contact, const char *field);
 733
 734
 735
 736 /** Sets the contact telephone.
 737  *
 738  * @param contact A contact object, see \ref gcal_contact.
 739  *
 740  * @param field Phone number.
 741  *
 742  * @param type Phone number type.
 743  *
 744  * @return 0 for success, -1 otherwise
 745  */
 746 int gcal_contact_add_phone_number(gcal_contact_t contact, const char *field,
 747                                   gcal_phone_type type);
 748
 749
 750 /** Sets contact prefered phone.
 751  *
 752  * This is a convenience function, it is implemented internally using
 753  * \ref gcal_contact_add_phone_number. Pay attention that when this
 754  * function is called, it will destroy all the contact's phone list
 755  * to ensure that the prefered email will be the first to be added.
 756  *
 757  * The phone type default to P_MOBILE.
 758  *
 759  * @param contact A contact object, see \ref gcal_contact.
 760  *
 761  * @param phone A phone number (e.g. "+551132314412")
 762  *
 763  * @return 0 for success, -1 otherwise
 764  */
 765 int gcal_contact_set_phone(gcal_contact_t contact, const char *phone);
 766
 767
 768 /* TODO: document new functions */
 769 int gcal_contact_delete_phone_numbers(gcal_contact_t contact);
 770
 771 /** Sets contact IM.
 772  *
 773  * @param contact A contact object, see \ref gcal_contact.
 774  *
 775  * @param protcol IM protocol.
 776  *
 777  * @param address IM address.
 778  *
 779  * @param type IM type.
 780  *
 781  * @return 0 for success, -1 otherwise
 782  */
 783 int gcal_contact_add_im(gcal_contact_t contact, const char *protcol,
 784                         const char *address, gcal_im_type type, int pref);
 785
 786 /** Deletes contact IM.
 787  *
 788  * @param contact A contact object, see \ref gcal_contact.
 789  *
 790  * @return 0 for success, -1 otherwise
 791  */
 792 int gcal_contact_delete_im(gcal_contact_t contact);
 793
 794 /** Sets the contact address (Google API v2.0 gd:postalAddress).
 795  *
 796  * @param contact A contact object, see \ref gcal_contact.
 797  *
 798  * @param field Address string.
 799  *
 800  * @return 0 for success, -1 otherwise
 801  */
 802 int gcal_contact_set_address(gcal_contact_t contact, const char *field);
 803
 804 /** Sets the contact full address number (structuredPostalAddress).
 805  *
 806  * @param contact A contact object, see \ref gcal_contact.
 807  *
 808  * @param type Address type.
 809  *
 810  * @return 0 for success, -1 otherwise
 811  */
 812 int gcal_contact_set_structured_address_nr(gcal_contact_t contact,
 813                                            gcal_address_type type);
 814
 815 /** Sets the contact preferred address number (structuredPostalAddress).
 816  *
 817  * @param contact A contact object, see \ref gcal_contact.
 818  *
 819  * @param pref_address Number of preferred address.
 820  *
 821  * @return 0 for success, -1 otherwise
 822  */
 823 int gcal_contact_set_pref_structured_address(gcal_contact_t contact, int pref_address);
 824
 825 /** Sets a structured entry.
 826  *
 827  * @param structured_entry A structured entry object, see \ref gcal_structured_subvalues.
 828  *
 829  * @param structured_entry_nr Index of the entry.
 830  *
 831  * @param structured_entry_count Number of all entries.
 832  *
 833  * @param field_key Key of the structured entry.
 834  *
 835  * @param field_value Corresponding value.
 836  *
 837  * @param structured_entry_type Structured entry type.
 838  *
 839  * @return 0 for success, -1 otherwise
 840  */
 841 int gcal_contact_set_structured_entry(gcal_structured_subvalues_t structured_entry,
 842                                       int structured_entry_nr,
 843                                       int structured_entry_count,
 844                                       const char *field_key,
 845                                       const char *field_value );
 846
 847 /** Deletes a structured entry.
 848  *
 849  * @param structured_entry A structured entry object, see \ref gcal_structured_subvalues.
 850  *
 851  * @param *structured_entry_count Pointer to the structured entry count object.
 852  *
 853  * @param ***structured_entry_type Pointer to the structured entry type object.
 854  *
 855  * @return 0 for success, -1 otherwise
 856  */
 857 int gcal_contact_delete_structured_entry(gcal_structured_subvalues_t structured_entry,
 858                                          int *structured_entry_count,
 859                                          char ***structured_entry_type);
 860
 861 /** Sets the contact group membership info.
 862  *
 863  * @param contact A contact object, see \ref gcal_contact.
 864  *
 865  * @param field Group name.
 866  *
 867  * @return 0 for success, -1 otherwise
 868  */
 869 int gcal_contact_add_groupMembership(gcal_contact_t contact, char *field);
 870
 871 /* TODO: document new functions */
 872 int gcal_contact_delete_groupMembership(gcal_contact_t contact);
 873
 874
 875 /** Sets the contact birthday
 876  *
 877  * When no year is set in Google, Year is set to 1900 in KABC
 878  *
 879  * @param contact A contact object, see \ref gcal_contact.
 880  *
 881  * @param field birthday string.
 882  *
 883  * @return 0 for success, -1 otherwise
 884  */
 885 int gcal_contact_set_birthday(gcal_contact_t contact, const char *field);
 886
 887 /** Sets the organization title.
 888  *
 889  *
 890  * @param contact A contact object, see \ref gcal_contact.
 891  *
 892  * @param field Organization title string (i.e. "C++ programmer").
 893  *
 894  * @return 0 for success, -1 otherwise
 895  */
 896 int gcal_contact_set_profission(gcal_contact_t contact, const char *field);
 897
 898 /** Sets the organization name.
 899  *
 900  *
 901  * @param contact A contact object, see \ref gcal_contact.
 902  *
 903  * @param field Organization name string (i.e. "Foo Software Inc.").
 904  *
 905  * @return 0 for success, -1 otherwise
 906  */
 907 int gcal_contact_set_organization(gcal_contact_t contact, const char *field);
 908
 909 /** Sets the occupation/profession.
 910  *
 911  *
 912  * @param contact A contact object, see \ref gcal_contact.
 913  *
 914  * @param field occupation/profession name string (i.e. "Carpenter").
 915  *
 916  * @return 0 for success, -1 otherwise
 917  */
 918 int gcal_contact_set_occupation(gcal_contact_t contact, const char *field);
 919
 920 /** Sets contact description.
 921  *
 922  * @param contact A contact object, see \ref gcal_contact.
 923  *
 924  * @param field A note, description (i.e. "Really funny guy")
 925  *
 926  * @return 0 for success, -1 otherwise
 927  */
 928 int gcal_contact_set_content(gcal_contact_t contact, const char *field);
 929
 930 /** Sets contact nickname.
 931  *
 932  * @param contact A contact object, see \ref gcal_contact.
 933  *
 934  * @param field The nickname
 935  *
 936  * @return 0 for success, -1 otherwise
 937  */
 938 int gcal_contact_set_nickname(gcal_contact_t contact, const char *field);
 939
 940 /** Sets contact website.
 941  *
 942  * @param contact A contact object, see \ref gcal_contact.
 943  *
 944  * @param field URL
 945  *
 946  * @return 0 for success, -1 otherwise
 947  */
 948 int gcal_contact_set_homepage(gcal_contact_t contact, const char *field);
 949
 950 /** Sets contact blog.
 951  *
 952  * @param contact A contact object, see \ref gcal_contact.
 953  *
 954  * @param field URL
 955  *
 956  * @return 0 for success, -1 otherwise
 957  */
 958 int gcal_contact_set_blog(gcal_contact_t contact, const char *field);
 959
 960 /* TODO: document new functions */
 961 int gcal_contact_set_photo(gcal_contact_t contact, const char *field,
 962                            int length);
 963
 964
 965 #endif