mrss.h

Go to the documentation of this file.
00001 /* mRss - Copyright (C) 2005-2007 bakunin - Andrea Marchesini 
00002  *                                    <bakunin@autistici.org>
00003  *
00004  * This library is free software; you can redistribute it and/or
00005  * modify it under the terms of the GNU Lesser General Public
00006  * License as published by the Free Software Foundation; either
00007  * version 2.1 of the License, or (at your option) any later version.
00008  * 
00009  * This library is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012  * Lesser General Public License for more details.
00013  * 
00014  * You should have received a copy of the GNU Lesser General Public
00015  * License along with this library; if not, write to the Free Software
00016  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00017  */
00018 
00019 #ifndef __M_RSS_H__
00020 #define __M_RSS_H__
00021 
00022 #include <sys/types.h>
00023 #include <curl/curl.h>
00024 
00025 #define LIBMRSS_VERSION_STRING  "0.19.2"
00026 
00027 #define LIBMRSS_MAJOR_VERSION   0
00028 #define LIBMRSS_MINOR_VERSION   19
00029 #define LIBMRSS_MICRO_VERSION   2
00030 
00031 #ifdef  __cplusplus
00032 extern "C" {
00033 #endif
00034 
00035 typedef struct mrss_t mrss_t;
00036 typedef struct mrss_options_t mrss_options_t;
00037 typedef struct mrss_item_t mrss_item_t;
00038 typedef struct mrss_category_t mrss_category_t;
00039 typedef struct mrss_hour_t mrss_hour_t;
00040 typedef struct mrss_day_t mrss_day_t;
00041 typedef struct mrss_tag_t mrss_tag_t;
00042 typedef struct mrss_attribute_t mrss_attribute_t;
00043 typedef void * mrss_generic_t;
00044 
00045 /** This enum describes the error type of libmrss */
00046 typedef enum {
00047   MRSS_OK = 0,                  /**< No error */
00048   MRSS_ERR_POSIX,               /**< For the correct error, use errno */
00049   MRSS_ERR_PARSER,              /**< Parser error */
00050   MRSS_ERR_DOWNLOAD,            /**< Download error */
00051   MRSS_ERR_VERSION,             /**< The RSS has a no compatible VERSION */
00052   MRSS_ERR_DATA                 /**< The parameters are incorrect */
00053 } mrss_error_t;
00054 
00055 typedef enum {
00056   MRSS_VERSION_0_91,            /**< 0.91 RSS version */
00057   MRSS_VERSION_0_92,            /**< 0.92 RSS version */
00058   MRSS_VERSION_1_0,             /**< 1.0 RSS version */
00059   MRSS_VERSION_2_0,             /**< 2.0 RSS version */
00060   MRSS_VERSION_ATOM_0_3,        /**< 0.3 Atom version */
00061   MRSS_VERSION_ATOM_1_0         /**< 1.0 Atom version */
00062 } mrss_version_t;
00063 
00064 /** Flag list for mrss_set and mrss_get functions */
00065 typedef enum {
00066   /* Generic */
00067 
00068   /** Set the ersion to a mrss_t element - the value is a mrss_version_t enum */
00069   MRSS_FLAG_VERSION = 1,
00070 
00071   /** Set the title to a mrss_t element - the value is a string */
00072   MRSS_FLAG_TITLE,
00073   /** Set the title type to a mrss_t element - the value is a string (ex: text, html, ...)*/
00074   MRSS_FLAG_TITLE_TYPE,
00075   /** Set the description to a mrss_t element - the value is a string */
00076   MRSS_FLAG_DESCRIPTION,
00077   /** Set the description type to a mrss_t element - the value is a string */
00078   MRSS_FLAG_DESCRIPTION_TYPE,
00079   /** Set the link to a mrss_t element - the value is a string */
00080   MRSS_FLAG_LINK,
00081   /** Set the id to a mrss_t element - the value is a string */
00082   MRSS_FLAG_ID,
00083   /** Set the language to a mrss_t element - the value is a string */
00084   MRSS_FLAG_LANGUAGE,
00085   /** Set the rating to a mrss_t element - the value is a string */
00086   MRSS_FLAG_RATING,
00087   /** Set the copyright to a mrss_t element - the value is a string */
00088   MRSS_FLAG_COPYRIGHT,
00089   /** Set the copyright type to a mrss_t element - the value is a string */
00090   MRSS_FLAG_COPYRIGHT_TYPE,
00091   /** Set the pubDate to a mrss_t element - the value is a string */
00092   MRSS_FLAG_PUBDATE,
00093   /** Set the lastBuildDate to a mrss_t element - the value is a string */
00094   MRSS_FLAG_LASTBUILDDATE,
00095   /** Set the docs to a mrss_t element - the value is a string */
00096   MRSS_FLAG_DOCS,
00097   /** Set the managingeditor to a mrss_t element - the value is a string */
00098   MRSS_FLAG_MANAGINGEDITOR,
00099   /** Set the managingeditor's email to a mrss_t element - the value is a string */
00100   MRSS_FLAG_MANAGINGEDITOR_EMAIL,
00101   /** Set the managingeditor's uri to a mrss_t element - the value is a string */
00102   MRSS_FLAG_MANAGINGEDITOR_URI,
00103   /** Set the webMaster to a mrss_t element - the value is a string */
00104   MRSS_FLAG_WEBMASTER,
00105   /** Set the generator to a mrss_t element - the value is a string */
00106   MRSS_FLAG_TTL,
00107   /** Set the about to a mrss_t element - the value is a string */
00108   MRSS_FLAG_ABOUT,
00109 
00110   /* Contributor */
00111 
00112   /** Set the contributor to a mrss_t element - the value is a string */
00113   MRSS_FLAG_CONTRIBUTOR,
00114   /** Set the contributor's email to a mrss_t element - the value is a string */
00115   MRSS_FLAG_CONTRIBUTOR_EMAIL,
00116   /** Set the contributor's uri to a mrss_t element - the value is a string */
00117   MRSS_FLAG_CONTRIBUTOR_URI,
00118 
00119   /* Generator */
00120 
00121   /** Set the generator to a mrss_t element - the value is a string */
00122   MRSS_FLAG_GENERATOR,
00123   /** Set the generator's email to a mrss_t element - the value is a string */
00124   MRSS_FLAG_GENERATOR_URI,
00125   /** Set the generator's uri to a mrss_t element - the value is a string */
00126   MRSS_FLAG_GENERATOR_VERSION,
00127 
00128   /* Image */
00129 
00130   /** Set the image_title to a mrss_t element - the value is a string */
00131   MRSS_FLAG_IMAGE_TITLE,
00132   /** Set the image_url to a mrss_t element - the value is a string */
00133   MRSS_FLAG_IMAGE_URL,
00134   /** Set the image_logo to a mrss_t element - the value is a string */
00135   MRSS_FLAG_IMAGE_LOGO,
00136   /** Set the image_link to a mrss_t element - the value is a string */
00137   MRSS_FLAG_IMAGE_LINK,
00138   /** Set the image_width to a mrss_t element - the value is a integer */
00139   MRSS_FLAG_IMAGE_WIDTH,
00140   /** Set the image_height to a mrss_t element - the value is a integer */
00141   MRSS_FLAG_IMAGE_HEIGHT,
00142   /** Set the image_description to a mrss_t element - the value is a string */
00143   MRSS_FLAG_IMAGE_DESCRIPTION,
00144 
00145   /* TextInput */
00146 
00147   /** Set the textinput_title to a mrss_t element - the value is a string */
00148   MRSS_FLAG_TEXTINPUT_TITLE,
00149   /** Set the textinput_description to a mrss_t element - the value is a string */
00150   MRSS_FLAG_TEXTINPUT_DESCRIPTION,
00151   /** Set the textinput_name to a mrss_t element - the value is a string */
00152   MRSS_FLAG_TEXTINPUT_NAME,
00153   /** Set the textinput_link to a mrss_t element - the value is a string */
00154   MRSS_FLAG_TEXTINPUT_LINK,
00155 
00156   /* Cloud */
00157 
00158   /** Set the cloud to a mrss_t element - the value is a string */
00159   MRSS_FLAG_CLOUD,
00160   /** Set the cloud_domain to a mrss_t element - the value is a string */
00161   MRSS_FLAG_CLOUD_DOMAIN,
00162   /** Set the cloud_port to a mrss_t element - the value is a string */
00163   MRSS_FLAG_CLOUD_PORT,
00164   /** Set the cloud_path to a mrss_t element - the value is a integer */
00165   MRSS_FLAG_CLOUD_PATH,
00166   /** Set the cloud_registerProcedure to a mrss_t element - 
00167    * the value is a string */
00168   MRSS_FLAG_CLOUD_REGISTERPROCEDURE,
00169   /** Set the cloud_protocol to a mrss_t element - the value is a string */
00170   MRSS_FLAG_CLOUD_PROTOCOL,
00171 
00172   /* SkipHours */
00173 
00174   /** Set the hour to a mrss_hour_t element - the value is a string */
00175   MRSS_FLAG_HOUR,
00176 
00177   /* SkipDays */
00178 
00179   /** Set the day to a mrss_day_t element - the value is a string */
00180   MRSS_FLAG_DAY,
00181 
00182   /* Category or Item/Category */
00183 
00184   /** Set the category to a mrss_category_t element - the value is a string */
00185   MRSS_FLAG_CATEGORY,
00186   /** Set the domain to a mrss_category_t element - the value is a string */
00187   MRSS_FLAG_CATEGORY_DOMAIN,
00188   /** Set the label to a mrss_category_t element - the value is a string */
00189   MRSS_FLAG_CATEGORY_LABEL,
00190 
00191   /* Item */
00192 
00193   /** Set the title to a mrss_item_t element - the value is a string */
00194   MRSS_FLAG_ITEM_TITLE,
00195   /** Set the title type to a mrss_item_t element - the value is a string */
00196   MRSS_FLAG_ITEM_TITLE_TYPE,
00197   /** Set the link to a mrss_item_t element - the value is a string */
00198   MRSS_FLAG_ITEM_LINK,
00199   /** Set the description to a mrss_item_t element - the value is a string */
00200   MRSS_FLAG_ITEM_DESCRIPTION,
00201   /** Set the description type to a mrss_item_t element - the value is a string */
00202   MRSS_FLAG_ITEM_DESCRIPTION_TYPE,
00203   /** Set the copyright to a mrss_item_t element - the value is a string */
00204   MRSS_FLAG_ITEM_COPYRIGHT,
00205   /** Set the copyright type to a mrss_item_t element - the value is a string */
00206   MRSS_FLAG_ITEM_COPYRIGHT_TYPE,
00207 
00208   /** Set the author to a mrss_item_t element - the value is a string */
00209   MRSS_FLAG_ITEM_AUTHOR,
00210   /** Set the author's uri to a mrss_item_t element - the value is a string */
00211   MRSS_FLAG_ITEM_AUTHOR_URI,
00212   /** Set the author's email to a mrss_item_t element - the value is a string */
00213   MRSS_FLAG_ITEM_AUTHOR_EMAIL,
00214 
00215   /** Set the contributor to a mrss_item_t element - the value is a string */
00216   MRSS_FLAG_ITEM_CONTRIBUTOR,
00217   /** Set the contributor's uri to a mrss_item_t element - the value is a string */
00218   MRSS_FLAG_ITEM_CONTRIBUTOR_URI,
00219   /** Set the contributor's email to a mrss_item_t element - the value is a string */
00220   MRSS_FLAG_ITEM_CONTRIBUTOR_EMAIL,
00221 
00222   /** Set the comments to a mrss_item_t element - the value is a string */
00223   MRSS_FLAG_ITEM_COMMENTS,
00224   /** Set the pubDate to a mrss_item_t element - the value is a string */
00225   MRSS_FLAG_ITEM_PUBDATE,
00226   /** Set the guid to a mrss_item_t element - the value is a string */
00227   MRSS_FLAG_ITEM_GUID,
00228   /** Set the guid_isPermaLink to a mrss_item_t element - 
00229    * the value is a integer */
00230   MRSS_FLAG_ITEM_GUID_ISPERMALINK,
00231   /** Set the source to a mrss_item_t element - the value is a string */
00232   MRSS_FLAG_ITEM_SOURCE,
00233   /** Set the source_url to a mrss_item_t element - the value is a string */
00234   MRSS_FLAG_ITEM_SOURCE_URL,
00235   /** Set the enclosure to a mrss_item_t element - the value is a string */
00236   MRSS_FLAG_ITEM_ENCLOSURE,
00237   /** Set the enclosure_url to a mrss_item_t element - the value is a string */
00238   MRSS_FLAG_ITEM_ENCLOSURE_URL,
00239   /** Set the enclosure_length to a mrss_item_t element - 
00240    * the value is a integer */
00241   MRSS_FLAG_ITEM_ENCLOSURE_LENGTH,
00242   /** Set the enclosure_type to a mrss_item_t element - the value is a string */
00243   MRSS_FLAG_ITEM_ENCLOSURE_TYPE,
00244 
00245   /* Item */
00246 
00247   /** Set the name to a mrss_tag_t element - the value is a string */
00248   MRSS_FLAG_TAG_NAME,
00249 
00250   /** Set the value to a mrss_tag_t element - the value is a string */
00251   MRSS_FLAG_TAG_VALUE,
00252 
00253   /** Set the namespace to a mrss_tag_t element - the value is a string */
00254   MRSS_FLAG_TAG_NS,
00255 
00256   /** Set the name to a mrss_attribute_t element - the value is a string */
00257   MRSS_FLAG_ATTRIBUTE_NAME,
00258 
00259   /** Set the value to a mrss_attribute_t element - the value is a string */
00260   MRSS_FLAG_ATTRIBUTE_VALUE,
00261 
00262   /** Set the namespace to a mrss_attribute_t element - the value is a string */
00263   MRSS_FLAG_ATTRIBUTE_NS,
00264 
00265   /** Set the terminetor flag */
00266   MRSS_FLAG_END = 0
00267 
00268 } mrss_flag_t;
00269 
00270 /** Enum for the casting of the libmrss data struct */
00271 typedef enum {
00272   /** The data struct is a mrss_t */
00273   MRSS_ELEMENT_CHANNEL,
00274   /** The data struct is a mrss_item_t */
00275   MRSS_ELEMENT_ITEM,
00276   /** The data struct is a mrss_hour_t */
00277   MRSS_ELEMENT_SKIPHOURS,
00278   /** The data struct is a mrss_day_t */
00279   MRSS_ELEMENT_SKIPDAYS,
00280   /** The data struct is a mrss_category_t */
00281   MRSS_ELEMENT_CATEGORY,
00282   /** The data struct is a mrss_tag_t */
00283   MRSS_ELEMENT_TAG,
00284   /** The data struct is a mrss_attribute_t */
00285   MRSS_ELEMENT_ATTRIBUTE
00286 } mrss_element_t;
00287 
00288 /** Data struct for any items of RSS. It contains a pointer to the list
00289  * of categories. 
00290  *
00291  * \brief 
00292  * Struct data for item elements */
00293 struct mrss_item_t {
00294 
00295   /** For internal use only: */
00296   mrss_element_t element;
00297   int allocated;
00298 
00299   /* Data: */
00300 
00301                                 /* 0.91 0.92    1.0     2.0     ATOM    */
00302   char *title;                  /* R    O       O       O       R       */
00303   char *title_type;             /* -    -       -       -       O       */
00304   char *link;                   /* R    O       O       O       O       */
00305   char *description;            /* R    O       -       O       O       */
00306   char *description_type;       /* -    -       -       -       0       */
00307   char *copyright;              /* -    -       -       -       O       */
00308   char *copyright_type;         /* -    -       -       -       O       */
00309   
00310   char *author;                 /* -    -       -       O       O       */
00311   char *author_uri;             /* -    -       -       -       O       */
00312   char *author_email;           /* -    -       -       -       O       */
00313 
00314   char *contributor;            /* -    -       -       -       O       */
00315   char *contributor_uri;        /* -    -       -       -       O       */
00316   char *contributor_email;      /* -    -       -       -       O       */
00317 
00318   char *comments;               /* -    -       -       O       -       */
00319   char *pubDate;                /* -    -       -       O       O       */
00320   char *guid;                   /* -    -       -       O       O       */
00321   int guid_isPermaLink;         /* -    -       -       O       -       */
00322 
00323   char *source;                 /* -    O       -       O       -       */
00324   char *source_url;             /* -    R       -       R       -       */
00325 
00326   char *enclosure;              /* -    O       -       O       -       */
00327   char *enclosure_url;          /* -    R       -       R       -       */
00328   int enclosure_length;         /* -    R       -       R       -       */
00329   char *enclosure_type;         /* -    R       -       R       -       */
00330 
00331   mrss_category_t *category;    /* -    O       -       O       O       */
00332 
00333   mrss_tag_t *other_tags;
00334 
00335   mrss_item_t *next;
00336 };
00337 
00338 /** Data struct for skipHours elements. 
00339  *
00340  * \brief 
00341  * Struct data for skipHours elements */
00342 struct mrss_hour_t {
00343   /** For internal use only: */
00344   mrss_element_t element;
00345   int allocated;
00346 
00347   /* Data: */
00348                                 /* 0.91 0.92    1.0     2.0     ATOM    */
00349   char *hour;                   /* R    R       -       R       -       */
00350   mrss_hour_t *next;
00351 };
00352 
00353 /** Data struct for skipDays elements. 
00354  *
00355  * \brief 
00356  * Struct data for skipDays elements */
00357 struct mrss_day_t {
00358   /** For internal use only: */
00359   mrss_element_t element;
00360   int allocated;
00361 
00362   /* Data: */
00363                                 /* 0.91 0.92    1.0     2.0     ATOM    */
00364   char *day;                    /* R    R       -       R       -       */
00365   mrss_day_t *next;
00366 };
00367 
00368 /** Data struct for category elements
00369  *
00370  * \brief 
00371  * Struct data for category elements */
00372 struct mrss_category_t {
00373   /** For internal use only: */
00374   mrss_element_t element;
00375   int allocated;
00376 
00377   /* Data: */
00378                                 /* 0.91 0.92    1.0     2.0     ATOM    */
00379   char *category;               /* -    R       -       R       R       */
00380   char *domain;                 /* -    O       -       O       O       */
00381   char *label;                  /* -    -       -       -       O       */
00382   mrss_category_t *next;
00383 };
00384 
00385 /** Principal data struct. It contains pointers to any other structures.
00386  *
00387  * \brief 
00388  * Principal data struct. It contains pointers to any other structures */
00389 struct mrss_t {
00390   /** For internal use only: */
00391   mrss_element_t element;
00392   int allocated;
00393   int curl_error;
00394 
00395   /* Data: */
00396 
00397   char *file;
00398   size_t size;
00399   char *encoding;
00400 
00401   mrss_version_t version;       /* 0.91 0.92    1.0     2.0     ATOM    */
00402 
00403   char *title;                  /* R    R       R       R       R       */
00404   char *title_type;             /* -    -       -       -       O       */
00405   char *description;            /* R    R       R       R       R       */
00406   char *description_type;       /* -    -       -       -       O       */
00407   char *link;                   /* R    R       R       R       O       */
00408   char *id;                     /*      -       -       -       -       O       */
00409   char *language;               /* R    O       -       O       O       */
00410   char *rating;                 /* O    O       -       O       -       */
00411   char *copyright;              /* O    O       -       O       O       */
00412   char *copyright_type;         /* -    -       -       -       O       */
00413   char *pubDate;                /* O    O       -       O       -       */
00414   char *lastBuildDate;          /* O    O       -       O       O       */
00415   char *docs;                   /* O    O       -       O       -       */
00416   char *managingeditor;         /* O    O       -       O       O       */
00417   char *managingeditor_email;   /* O    O       -       O       O       */
00418   char *managingeditor_uri;     /* O    O       -       O       O       */
00419   char *webMaster;              /* O    O       -       O       -       */
00420   int ttl;                      /* -    -       -       O       -       */
00421   char *about;                  /* -    -       R       -       -       */
00422   
00423   /* Contributor */             /* -    -       -       -       O       */
00424   char *contributor;            /* -    -       -       -       R       */
00425   char *contributor_email;      /* -    -       -       -       O       */
00426   char *contributor_uri;        /* -    -       -       -       O       */
00427 
00428   /* Generator */
00429   char *generator;              /* -    -       -       O       O       */
00430   char *generator_uri;          /* -    -       -       -       O       */
00431   char *generator_version;      /* -    -       -       -       O       */
00432 
00433   /* Tag Image: */              /* O    O       O       O       -       */
00434   char *image_title;            /* R    R       R       R       -       */
00435   char *image_url;              /* R    R       R       R       O       */
00436   char *image_logo;             /* -    -       -       -       O       */
00437   char *image_link;             /* R    R       R       R       -       */
00438   unsigned int image_width;     /* O    O       -       O       -       */
00439   unsigned int image_height;    /* O    O       -       O       -       */
00440   char *image_description;      /* O    O       -       O       -       */
00441 
00442   /* TextInput: */              /* O    O       O       O       -       */
00443   char *textinput_title;        /* R    R       R       R       -       */
00444   char *textinput_description;  /* R    R       R       R       -       */
00445   char *textinput_name;         /* R    R       R       R       -       */
00446   char *textinput_link;         /* R    R       R       R       -       */
00447 
00448   /* Cloud */
00449   char *cloud;                  /* -    O       -       O       -       */
00450   char *cloud_domain;           /* -    R       -       R       -       */
00451   int cloud_port;               /* -    R       -       R       -       */
00452   char *cloud_path;             /* -    R       -       R       -       */
00453   char *cloud_registerProcedure;/* -    R       -       R       -       */
00454   char *cloud_protocol;         /* -    R       -       R       -       */
00455 
00456   mrss_hour_t *skipHours;       /* O    O       -       O       -       */
00457   mrss_day_t *skipDays;         /* O    O       -       O       -       */
00458 
00459   mrss_category_t *category;    /* -    O       -       O       O       */
00460 
00461   mrss_item_t *item;            /* R    R       R       R       R       */
00462 
00463   mrss_tag_t *other_tags;
00464 
00465 #ifdef USE_LOCALE
00466   void *c_locale;
00467 #endif
00468 
00469 };
00470 
00471 /** Data struct for any other tag out of the RSS namespace.
00472  *
00473  * \brief 
00474  * Struct data for external tags */
00475 struct mrss_tag_t {
00476   /** For internal use only: */
00477   mrss_element_t element;
00478   int allocated;
00479 
00480   /*name of the tag */
00481   char *name;
00482 
00483   /* value */
00484   char *value;
00485 
00486   /* namespace */
00487   char *ns;
00488 
00489   /* list of attributes: */
00490   mrss_attribute_t *attributes;
00491 
00492   /* Sub tags: */
00493   mrss_tag_t *children;
00494 
00495   /* the next tag: */
00496   mrss_tag_t *next;
00497 };
00498 
00499 /** Data struct for the attributes of the tag
00500  *
00501  * \brief 
00502  * Struct data for external attribute */
00503 struct mrss_attribute_t {
00504   /** For internal use only: */
00505   mrss_element_t element;
00506   int allocated;
00507 
00508   /* name of the tag */
00509   char *name;
00510 
00511   /* value */
00512   char *value;
00513 
00514   /* namespace */
00515   char *ns;
00516   
00517   /* The next attribute: */
00518   mrss_attribute_t *next;
00519 };
00520 
00521 /** Options data struct. It contains some user preferences.
00522  *
00523  * \brief 
00524  * Options data struct. It contains some user preferences. */
00525 struct mrss_options_t {
00526   int timeout;
00527   char *proxy;
00528   char *proxy_authentication;
00529   char *certfile;
00530   char *cacert;
00531   char *password;
00532   int verifypeer;
00533   char *authentication;
00534   char *user_agent;
00535 };
00536 
00537 /** PARSE FUNCTIONS *********************************************************/
00538 
00539 /**
00540  * Parses a url and creates the data struct of the feed RSS url.
00541  * This function downloads your request if this is http or ftp.
00542  * \param url The url to be parsed
00543  * \param mrss the pointer to your data struct
00544  * \return the error code
00545  */
00546 mrss_error_t    mrss_parse_url          (char *         url,
00547                                          mrss_t **      mrss);
00548 
00549 /**
00550  * Like the previous function but with a options struct.
00551  * \param url The url to be parsed
00552  * \param mrss the pointer to your data struct
00553  * \param options a pointer to a options data struct
00554  * \return the error code
00555  */
00556 mrss_error_t    mrss_parse_url_with_options
00557                                         (char *         url,
00558                                          mrss_t **      mrss,
00559                                          mrss_options_t * options);
00560 
00561 /**
00562  * Like the previous function but with CURLcode error
00563  * \param url The url to be parsed
00564  * \param mrss the pointer to your data struct
00565  * \param options a pointer to a options data struct. It can be NULL
00566  * \param curlcode the error code from libcurl
00567  * \return the error code
00568  */
00569 mrss_error_t    mrss_parse_url_with_options_and_error
00570                                         (char *         url,
00571                                          mrss_t **      mrss,
00572                                          mrss_options_t * options,
00573                                          CURLcode *     curlcode);
00574 
00575 /**
00576  * Like the previous function but you take ownership of the downloaded buffer
00577  * in case of success
00578  * \param url The url to be parsed
00579  * \param mrss the pointer to your data struct
00580  * \param options a pointer to a options data struct
00581  * \param curlcode the error code from libcurl
00582  * \param feed_content a pointer to the buffer with the document. This is not NULL terminated
00583  * \param feed_size the size of the buffer above
00584  * \return the error code
00585  */
00586 mrss_error_t    mrss_parse_url_with_options_error_and_transfer_buffer
00587                                         (char *         url,
00588                                          mrss_t **      mrss,
00589                                          mrss_options_t * options,
00590                                          CURLcode *     curlcode,
00591                                          char **        feed_content,
00592                                          int  *         feed_size);
00593 
00594 /** 
00595  * Parses a file and creates the data struct of the feed RSS url
00596  * \param file The file to be parsed
00597  * \param mrss the pointer to your data struct
00598  * \return the error code
00599  */
00600 mrss_error_t    mrss_parse_file         (char *         file,
00601                                          mrss_t **      mrss);
00602 
00603 /** 
00604  * Parses a buffer and creates the data struct of the feed RSS url
00605  * \param buffer Pointer to the xml memory stream to be parsed
00606  * \param size_buffer The size of the array of char
00607  * \param mrss the pointer to your data struct
00608  * \return the error code
00609  */
00610 mrss_error_t    mrss_parse_buffer       (char *         buffer,
00611                                          size_t         size_buffer,
00612                                          mrss_t **      mrss);
00613 
00614 /** WRITE FUNCTIONS *********************************************************/
00615 
00616 /** 
00617  * Writes a RSS struct data in a local file
00618  * \param mrss the rss struct data
00619  * \param file the local file
00620  * \return the error code
00621  */
00622 mrss_error_t    mrss_write_file         (mrss_t *       mrss,
00623                                          char *         file);
00624 
00625 /**
00626  * Write a RSS struct data in a buffer.
00627  *
00628  * \code
00629  * char *buffer;
00630  * buffer=NULL; //<--- This is important!!
00631  * mrss_write_buffer (mrss, &buffer);
00632  * \endcode
00633  *
00634  * The buffer must be NULL.
00635  * \param mrss the rss struct data
00636  * \param buffer the buffer
00637  * \return the error code
00638  */
00639 mrss_error_t    mrss_write_buffer       (mrss_t *       mrss,
00640                                          char **        buffer);
00641 
00642 /** FREE FUNCTION ***********************************************************/
00643 
00644 /** 
00645  * This function frees any type of data struct of libmrss. If the element
00646  * is alloced by libmrss, it will be freed, else this function frees
00647  * only the internal data.
00648  *
00649  * \code
00650  * mrss_t *t=....;
00651  * mrss_item_t *item=...;
00652  *
00653  * mrss_free(t);
00654  * mrss_free(item);
00655  * \endcode
00656  *
00657  * \param element the data struct
00658  * \return the error code
00659  */
00660 mrss_error_t    mrss_free               (mrss_generic_t element);
00661 
00662 /** GENERIC FUNCTION ********************************************************/
00663 
00664 /** 
00665  * This function returns a static string with the description of error code
00666  * \param err the error code that you need as string
00667  * \return a string. Don't free this string!
00668  */
00669 char *          mrss_strerror           (mrss_error_t   err);
00670 
00671 /** 
00672  * This function returns a static string with the description of curl code
00673  * \param err the error code that you need as string
00674  * \return a string. Don't free this string!
00675  */
00676 char *          mrss_curl_strerror      (CURLcode       err);
00677 
00678 /**
00679  * This function returns the mrss_element_t of a mrss data struct.
00680  * \param element it is the element that you want check
00681  * \param ret it is a pointer to a mrss_element_t. It will be sets.
00682  * \return the error code
00683  */
00684 mrss_error_t    mrss_element            (mrss_generic_t element,
00685                                          mrss_element_t *ret);
00686 
00687 /**
00688  * This function returns the number of seconds sinze Jennuary 1st 1970 in the
00689  * UTC time zone, for the url that the urlstring parameter specifies.
00690  *
00691  * \param urlstring the url
00692  * \param lastmodified is a pointer to a time_t struct. The return value can
00693  * be 0 if the HEAD request does not return a Last-Modified value.
00694  * \return the error code
00695  */
00696 mrss_error_t    mrss_get_last_modified  (char *         urlstring,
00697                                          time_t *       lastmodified);
00698 
00699 /**
00700  * Like the previous function but with a options struct.
00701  *
00702  * \param urlstring the url
00703  * \param lastmodified is a pointer to a time_t struct. The return value can
00704  * be 0 if the HEAD request does not return a Last-Modified value.
00705  * \param options a pointer to a options struct
00706  * \return the error code
00707  */
00708 mrss_error_t    mrss_get_last_modified_with_options
00709                                         (char *         urlstring,
00710                                          time_t *       lastmodified,
00711                                          mrss_options_t * options);
00712 /**
00713  * Like the previous function but with a CURLcode pointer.
00714  *
00715  * \param urlstring the url
00716  * \param lastmodified is a pointer to a time_t struct. The return value can
00717  * be 0 if the HEAD request does not return a Last-Modified value.
00718  * \param options a pointer to a options struct
00719  * \param curl_code it will contain the error code of libcurl
00720  * \return the error code
00721  */
00722 mrss_error_t    mrss_get_last_modified_with_options_and_error
00723                                         (char *         urlstring,
00724                                          time_t *       lastmodified,
00725                                          mrss_options_t * options,
00726                                          CURLcode *     curl_code);
00727 
00728 /** EDIT FUNCTIONS **********************************************************/
00729 
00730 /** If you want create a new feed RSS from scratch, you need use
00731  * this function as the first.
00732  *
00733  * \code
00734  * mrss_t *d;
00735  * mrss_error_t err;
00736  * char *string;
00737  * int integer;
00738  *
00739  * d=NULL; // ->this is important! If d!=NULL, mrss_new doesn't alloc memory.
00740  * mrss_new(&d);
00741  *
00742  * err=mrss_set (d,
00743  *               MRSS_FLAG_VERSION, MRSS_VERSION_0_92,
00744  *               MRSS_FLAG_TITLE, "the title!",
00745  *               MRSS_FLAG_TTL, 12,
00746  *               MRSS_FLAG_END);
00747  *
00748  * if(err!=MRSS_OK) printf("%s\n",mrss_strerror(err));
00749  *
00750  * err=mrss_get (d,
00751  *               MRSS_FLAG_TITLE, &string,
00752  *               MRSS_FLAG_TTL, &integer,
00753  *               MRSS_FLAG_END);
00754  *
00755  * if(err!=MRSS_OK) printf("%s\n",mrss_strerror(err));
00756  * printf("The title is: '%s'\n", string);
00757  * printf("The ttl is: '%d'\n", integer);
00758  * free(string);
00759  * \endcode
00760  *
00761  * \param mrss is the pointer to the new data struct
00762  * \return the error code
00763  */
00764 mrss_error_t    mrss_new                (mrss_t **      mrss);
00765 
00766 /**
00767  * For insert/replace/remove a flags use this function as this example:
00768  * \code
00769  * mrss_set(mrss, MRSS_FLAG_TITLE, "hello world", MRSS_FLAG_END);
00770  * mrss_set(item, MRSS_FLAG_DESCRIPTION, NULL, MRSS_FLAG_END);
00771  * \endcode
00772  *
00773  * \param element it is the mrss data that you want changes the the next
00774  * list of elements. The list is composted by KEY - VALUES and as last
00775  * element MRSS_FLAG_END. The variable of value depends from key.
00776  * \see mrss_flag_t
00777  * \return the error code
00778  */
00779 mrss_error_t    mrss_set                (mrss_generic_t element,
00780                                          ...);
00781 
00782 /**
00783  * This function returns the request arguments. The syntax is the same of
00784  * mrss_set but the values of the list are pointer to data element (int *,
00785  * char **). If the key needs a char **, the value will be allocated.
00786  * \code
00787  * mrss_get(category, MRSS_FLAG_CATEGORY_DOMAIN, &string, MRSS_FLAG_END);
00788  * if(string) free(string);
00789  * \endcode
00790  * \param element it is any type of mrss data struct.
00791  * \return the error code
00792  */
00793 mrss_error_t    mrss_get                (mrss_generic_t element,
00794                                          ...);
00795 
00796 /**
00797  * This function adds an element to another element. For example you can
00798  * add a item to a channel, or a category to a item, and so on. Look this
00799  * example:
00800  * \code
00801  *  mrss_item_t *item = NULL;
00802  * mrss_hour_t *hour = NULL;
00803  * mrss_day_t day;              // If the element is no null, the function
00804  * mrss_category_t category,    // does not alloc it
00805  *
00806  * mrss_new_subdata(mrss, MRSS_ELEMENT_ITEM, &item);
00807  * mrss_new_subdata(mrss, MRSS_ELEMENT_SKIPHOURS, &hour);
00808  * mrss_new_subdata(mrss, MRSS_ELEMENT_SKIPDAYS, &day);
00809  * mrss_new_subdata(item, MRSS_ELEMENT_ITEM_CATEGORY, &category);
00810  * \endcode
00811  * \param element it is the parent element
00812  * \param subelement it is the type of the child (MRSS_ELEMENT_ITEM,
00813  * MRSS_ELEMENT_CATEGORY, ...)
00814  * \param subdata it is the pointer to the new struct. If the pointer
00815  * of *subdata exists, it will no alloced, else yes.
00816  * \return the error code
00817  * \see mrss_element_t
00818  */
00819 mrss_error_t    mrss_new_subdata        (mrss_generic_t element,
00820                                          mrss_element_t subelement,
00821                                          mrss_generic_t subdata);
00822 
00823 /**
00824  * This function removes a subdata element. As first argoment you must specify
00825  * the parent, and second argoment the child.
00826  * \code
00827  * mrss_remove_subdata(mrss, item);
00828  * \endcode
00829  * \param element it is the parent
00830  * \param subdata the child that you want remove. Remember: 
00831  * mrss_remove_subdata does not free the memory. So you can remove a item
00832  * and reinsert it after.
00833  * \return the error code
00834  */
00835 mrss_error_t    mrss_remove_subdata     (mrss_generic_t element,
00836                                          mrss_generic_t subdata);
00837 
00838 /* TAGS FUNCTIONS **********************************************************/
00839 
00840 /**
00841  * This function search a tag in a mrss_t, a mrss_item_t or a mrss_tag_t from
00842  *  name and a namespace.
00843  * \param element it is the parent node (mrss_t or mrss_item_t)
00844  * \param name the name of the element
00845  * \param ns the namespace. It can be null if the tag has a null namespace
00846  * \param tag the return pointer
00847  * \return the error code
00848  */
00849 mrss_error_t    mrss_search_tag         (mrss_generic_t element,
00850                                          char *         name,
00851                                          char *         ns,
00852                                          mrss_tag_t **  tag);
00853 
00854 /**
00855  * This function search an attribute from a mrss_tag_t, a name and a namespace
00856  * \param element it is the mrss_tag_t
00857  * \param name the name of the element
00858  * \param ns the namespace. It can be null if the tag has a null namespace
00859  * \param attribute the return pointer
00860  * \return the error code
00861  */
00862 mrss_error_t    mrss_search_attribute   (mrss_generic_t element,
00863                                          char *         name,
00864                                          char *         ns,
00865                                          mrss_attribute_t ** attribute);
00866 
00867 /* OPTIONS FUNCTIONS *******************************************************/
00868 
00869 /**
00870  * This function creates a options struct.
00871  * 
00872  * \param timeout timeout for the download procedure
00873  * \param proxy a proxy server. can be NULL
00874  * \param proxy_authentication a proxy authentication (user:pwd). can be NULL
00875  * \param certfile a certificate for ssl autentication connection
00876  * \param password the password of certfile
00877  * \param cacert CA certificate to verify peer against. can be NULL
00878  * \param verifypeer active/deactive the peer check
00879  * \param authentication an authentication login (user:pwd). can be NULL
00880  * \param user_agent a user_agent. can be NULL
00881  * \return a pointer to a new allocated mrss_options_t struct 
00882  */
00883 mrss_options_t *
00884                 mrss_options_new        (int timeout,
00885                                          char *proxy,
00886                                          char *proxy_authentication,
00887                                          char *certfile,
00888                                          char *password,
00889                                          char *cacert,
00890                                          int verifypeer,
00891                                          char *authentication,
00892                                          char *user_agent);
00893 
00894 /**
00895  * This function destroys a options struct.
00896  * \param options a pointer to a options struct
00897  */
00898 void            mrss_options_free       (mrss_options_t *options);
00899 
00900 #ifdef  __cplusplus
00901 }
00902 #endif
00903 
00904 #endif
00905 
00906 /* EOF */
00907 

Generated on Fri Aug 22 00:03:56 2008 for libmrss by  doxygen 1.5.5