inc/gcal_parser.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 #ifndef __GCAL_PARSER__
  30 #define __GCAL_PARSER__
  31 /**
  32  * @file   gcal_parser.h
  33  * @author Adenilson Cavalcanti da Silva <adenilson.silva@indt.org.br>
  34  * @date   Mon Mar 31 11:17:02 2008
  35  *
  36  * @brief  A thin layer over \ref atom_parser.h, so I can plug another
  37  * XML parser to libgcal if required.
  38  * It creates a DOM document from libgcal atom stream and provides functions
  39  * wrappers to extract data.
  40  */
  41
  42 #include <libxml/parser.h>
  43 #include "internal_gcal.h"
  44 #include "gcal.h"
  45 #include "gcontact.h"
  46
  47 /** Parses the returned HTML page and extracts the redirection URL
  48  * that has the Atom feed.
  49  *
  50  * \todo Save the xmlDoc structure for future reuse (maybe within
  51  * structure \ref gcal_resource).
  52  *
  53  * @param data Raw data (the HTML page).
  54  * @param length Data buffer length.
  55  * @param url Pointer to the pointer (ouch!) that will receive the URL
  56  * (you should cleanup its memory). It will point to NULL if there is
  57  * not a URL in the raw data buffer.
  58  *
  59  * @return Returns 0 on success, -1 otherwise.
  60  */
  61 int get_the_url(char *data, int length, char **url);
  62
  63 /** Parses an entry XML (being calendar or contact) and extracts the edit
  64  * URL field (required for edit/delete operations).
  65  *
  66  * @param data Raw XML (an entry).
  67  * @param length Data buffer lenght.
  68  * @param url Pointer to the pointer (ouch!) that will receive the edit URL
  69  * (you should cleanup its memory). It will point to NULL if there is
  70  * not a URL in the raw XML buffer.
  71  *
  72  * @return Returns 0 on success, -1 otherwise.
  73  */
  74 int get_edit_url(char *data, int length, char **url);
  75
  76 /** Parses an entry XML (being calendar or contacts) and extracts the ETag
  77  * (gd:etag) attribute required to do some operations using Google
  78  * Data API 2.0.
  79  *
  80  * @param data Raw XML (an entry).
  81  * @param length Data buffer lenght.
  82  * @param url Pointer to the pointer (ouch!) that will receive the ETag
  83  * (you should cleanup its memory). It will point to NULL if there is
  84  * not an etag attribute in the raw XML buffer.
  85  *
  86  * @return Returns 0 on success, -1 otherwise.
  87  */
  88 int get_edit_etag(char *data, int length, char **url);
  89
  90 /** Builds a DOM tree from a XML string.
  91  *
  92  * This is a thin wrapper to \ref build_doc_tree.
  93  *
  94  * @param xml_data A pointer to a string with XML content.
  95  *
  96  * @return NULL on error, a pointer to a document in sucess.
  97  */
  98 dom_document *build_dom_document(char *xml_data);
  99
 100
 101 /** Clean up a DOM tree.
 102  *
 103  * This is a thin wrapper to \ref clean_doc_tree.
 104  * @param doc A pointer to a document data type.
 105  */
 106 void clean_dom_document(dom_document *doc);
 107
 108 /** Return the number of calendar entries in the document.
 109  *
 110  * This is a thin wrapper to \ref clean_doc_tree.
 111  * @param doc A pointer to a document data type.
 112  *
 113  * @return -1 on error or the number of entries.
 114  */
 115 int get_entries_number(dom_document *doc);
 116
 117
 118 /** Receiving a DOM document of the Atom stream, it will extract all the event
 119  * entries and parse then, storing each entry field in a vector of
 120  * \ref gcal_event.
 121  *
 122  * It depends on \ref atom_extract_data and \ref atom_get_entries.
 123  *
 124  * @param doc A document pointer with the Atom stream.
 125  *
 126  * @param data_extract A pointer to a pre-allocated vector \ref gcal_event.
 127  *
 128  * @param length Its length, should be the same as the number of entries. See
 129  * also \ref get_entries_number.
 130  *
 131  * @return 0 on success, -1 on error.
 132  */
 133 int extract_all_entries(dom_document *doc,
 134                         struct gcal_event *data_extract, int length);
 135
 136
 137 /** Creates the XML for a new calendar entry.
 138  *
 139  * It depends on \ref xmlentry_init_resources and
 140  * \ref xmlentry_destroy_resources.
 141  *
 142  * @param entry A pointer to an calendar entry event (see \ref gcal_event).
 143  *
 144  * @param xml_entry Pointer to pointer string (you must free its memory!).
 145  *
 146  * @param length A pointer to a variable that will have its length.
 147  *
 148  * @return 0 on sucess, -1 on error.
 149  */
 150 int xmlentry_create(struct gcal_event *entry, char **xml_entry, int *length);
 151
 152
 153 /** Receiving a DOM document of the Atom stream, it will extract all the
 154  * contacts and parse then, storing each contact in a vector of
 155  * \ref gcal_contact.
 156  *
 157  * It depends on \ref atom_extract_data and \ref atom_get_entries.
 158  *
 159  * @param doc A document pointer with the Atom stream.
 160  *
 161  * @param data_extract A pointer to a pre-allocated vector \ref gcal_contact.
 162  *
 163  * @param length Its length, should be the same as the number of entries. See
 164  * also \ref get_entries_number.
 165  *
 166  * @return 0 on success, -1 on error.
 167  */
 168 int extract_all_contacts(dom_document *doc,
 169                          struct gcal_contact *data_extract, int length);
 170
 171
 172 /** Creates the XML for a new contact entry.
 173  *
 174  * It depends on \ref xmlentry_init_resources and
 175  * \ref xmlentry_destroy_resources.
 176  *
 177  * @param contact A pointer to a contact (see \ref gcal_contact).
 178  *
 179  * @param xml_contact Pointer to pointer string (you must free its memory!).
 180  *
 181  * @param length A pointer to a variable that will have its length.
 182  *
 183  * @return 0 on sucess, -1 on error.
 184  */
 185 int xmlcontact_create(struct gcal_contact *contact, char **xml_contact,
 186                       int *length);
 187
 188 #endif