1 /* mRss - Copyright (C) 2005-2007 bakunin - Andrea Marchesini 2 * <bakunin@autistici.org> 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; if not, write to the Free Software 16 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 17 */ 18 /** 19 [mRss](http://www.autistici.org/bakunin/libmrss/doc/) is a C library for parsing, writing and creating RSS/ATOM files or streams. 20 21 Written 2014,2015,2016,2017 by Laeeth Isharc and Kaleidic Associates Advisory Limited 22 23 Authors: Laeeth Isharc and Ilya Yaroshenko 24 */ 25 module deimos.mrss; 26 27 import core.sys.posix.sys.types; 28 import etc.c.curl; 29 30 extern(C): 31 @system nothrow @nogc: 32 33 /// 34 enum LIBMRSS_VERSION_STRING = "0.19.2"; 35 36 /// 37 enum LIBMRSS_MAJOR_VERSION = 0; 38 /// 39 enum LIBMRSS_MINOR_VERSION = 19; 40 /// 41 enum LIBMRSS_MICRO_VERSION = 2; 42 43 /// 44 alias void* mrss_generic_t; 45 46 /// This enum describes the error type of libmrss 47 enum mrss_error_t { 48 /// No error 49 MRSS_OK = 0, 50 /// For the correct error, use errno 51 MRSS_ERR_POSIX, 52 /// Parser error 53 MRSS_ERR_PARSER, 54 /// Download error 55 MRSS_ERR_DOWNLOAD, 56 /// The RSS has incompatible version 57 MRSS_ERR_VERSION, 58 /// The parameters are incorrect 59 MRSS_ERR_DATA 60 } 61 62 /// 63 enum mrss_version_t { 64 /// 0.91 RSS version 65 MRSS_VERSION_0_91, 66 /// 0.92 RSS version 67 MRSS_VERSION_0_92, 68 /// 1.0 RSS version 69 MRSS_VERSION_1_0, 70 /// 2.0 RSS version 71 MRSS_VERSION_2_0, 72 /// 0.3 Atom version 73 MRSS_VERSION_ATOM_0_3, 74 /// 1.0 Atom version 75 MRSS_VERSION_ATOM_1_0 76 } 77 78 /// Flag list for mrss_set and mrss_get functions 79 enum mrss_flag_t { 80 /** 81 Generic: 82 */ 83 84 /** Set the version to a mrss_t element - the value is a mrss_version_t enum */ 85 MRSS_FLAG_VERSION = 1, 86 87 /** Set the title to a mrss_t element - the value is a string */ 88 MRSS_FLAG_TITLE, 89 /** Set the title type to a mrss_t element - the value is a string (ex: text, html, ...)*/ 90 MRSS_FLAG_TITLE_TYPE, 91 /** Set the description to a mrss_t element - the value is a string */ 92 MRSS_FLAG_DESCRIPTION, 93 /** Set the description type to a mrss_t element - the value is a string */ 94 MRSS_FLAG_DESCRIPTION_TYPE, 95 /** Set the link to a mrss_t element - the value is a string */ 96 MRSS_FLAG_LINK, 97 /** Set the id to a mrss_t element - the value is a string */ 98 MRSS_FLAG_ID, 99 /** Set the language to a mrss_t element - the value is a string */ 100 MRSS_FLAG_LANGUAGE, 101 /** Set the rating to a mrss_t element - the value is a string */ 102 MRSS_FLAG_RATING, 103 /** Set the copyright to a mrss_t element - the value is a string */ 104 MRSS_FLAG_COPYRIGHT, 105 /** Set the copyright type to a mrss_t element - the value is a string */ 106 MRSS_FLAG_COPYRIGHT_TYPE, 107 /** Set the pubDate to a mrss_t element - the value is a string */ 108 MRSS_FLAG_PUBDATE, 109 /** Set the lastBuildDate to a mrss_t element - the value is a string */ 110 MRSS_FLAG_LASTBUILDDATE, 111 /** Set the docs to a mrss_t element - the value is a string */ 112 MRSS_FLAG_DOCS, 113 /** Set the managingeditor to a mrss_t element - the value is a string */ 114 MRSS_FLAG_MANAGINGEDITOR, 115 /** Set the managingeditor's email to a mrss_t element - the value is a string */ 116 MRSS_FLAG_MANAGINGEDITOR_EMAIL, 117 /** Set the managingeditor's uri to a mrss_t element - the value is a string */ 118 MRSS_FLAG_MANAGINGEDITOR_URI, 119 /** Set the webMaster to a mrss_t element - the value is a string */ 120 MRSS_FLAG_WEBMASTER, 121 /** Set the generator to a mrss_t element - the value is a string */ 122 MRSS_FLAG_TTL, 123 /** Set the about to a mrss_t element - the value is a string */ 124 MRSS_FLAG_ABOUT, 125 126 /** 127 Contributor: 128 */ 129 130 /** Set the contributor to a mrss_t element - the value is a string */ 131 MRSS_FLAG_CONTRIBUTOR, 132 /** Set the contributor's email to a mrss_t element - the value is a string */ 133 MRSS_FLAG_CONTRIBUTOR_EMAIL, 134 /** Set the contributor's uri to a mrss_t element - the value is a string */ 135 MRSS_FLAG_CONTRIBUTOR_URI, 136 137 /** 138 Generator: 139 */ 140 141 /** Set the generator to a mrss_t element - the value is a string */ 142 MRSS_FLAG_GENERATOR, 143 /** Set the generator's email to a mrss_t element - the value is a string */ 144 MRSS_FLAG_GENERATOR_URI, 145 /** Set the generator's uri to a mrss_t element - the value is a string */ 146 MRSS_FLAG_GENERATOR_VERSION, 147 148 /** 149 Image: 150 */ 151 152 /** Set the image_title to a mrss_t element - the value is a string */ 153 MRSS_FLAG_IMAGE_TITLE, 154 /** Set the image_url to a mrss_t element - the value is a string */ 155 MRSS_FLAG_IMAGE_URL, 156 /** Set the image_logo to a mrss_t element - the value is a string */ 157 MRSS_FLAG_IMAGE_LOGO, 158 /** Set the image_link to a mrss_t element - the value is a string */ 159 MRSS_FLAG_IMAGE_LINK, 160 /** Set the image_width to a mrss_t element - the value is a integer */ 161 MRSS_FLAG_IMAGE_WIDTH, 162 /** Set the image_height to a mrss_t element - the value is a integer */ 163 MRSS_FLAG_IMAGE_HEIGHT, 164 /** Set the image_description to a mrss_t element - the value is a string */ 165 MRSS_FLAG_IMAGE_DESCRIPTION, 166 167 /** 168 TextInput: 169 */ 170 171 /** Set the textinput_title to a mrss_t element - the value is a string */ 172 MRSS_FLAG_TEXTINPUT_TITLE, 173 /** Set the textinput_description to a mrss_t element - the value is a string */ 174 MRSS_FLAG_TEXTINPUT_DESCRIPTION, 175 /** Set the textinput_name to a mrss_t element - the value is a string */ 176 MRSS_FLAG_TEXTINPUT_NAME, 177 /** Set the textinput_link to a mrss_t element - the value is a string */ 178 MRSS_FLAG_TEXTINPUT_LINK, 179 180 181 /** 182 Cloud: 183 */ 184 185 /** Set the cloud to a mrss_t element - the value is a string */ 186 MRSS_FLAG_CLOUD, 187 /** Set the cloud_domain to a mrss_t element - the value is a string */ 188 MRSS_FLAG_CLOUD_DOMAIN, 189 /** Set the cloud_port to a mrss_t element - the value is a string */ 190 MRSS_FLAG_CLOUD_PORT, 191 /** Set the cloud_path to a mrss_t element - the value is a integer */ 192 MRSS_FLAG_CLOUD_PATH, 193 /** Set the cloud_registerProcedure to a mrss_t element - 194 * the value is a string */ 195 MRSS_FLAG_CLOUD_REGISTERPROCEDURE, 196 /** Set the cloud_protocol to a mrss_t element - the value is a string */ 197 MRSS_FLAG_CLOUD_PROTOCOL, 198 199 /* SkipHours */ 200 201 /** Set the hour to a mrss_hour_t element - the value is a string */ 202 MRSS_FLAG_HOUR, 203 204 /* SkipDays */ 205 206 /** Set the day to a mrss_day_t element - the value is a string */ 207 MRSS_FLAG_DAY, 208 209 /* Category or Item/Category */ 210 211 /** Set the category to a mrss_category_t element - the value is a string */ 212 MRSS_FLAG_CATEGORY, 213 /** Set the domain to a mrss_category_t element - the value is a string */ 214 MRSS_FLAG_CATEGORY_DOMAIN, 215 /** Set the label to a mrss_category_t element - the value is a string */ 216 MRSS_FLAG_CATEGORY_LABEL, 217 218 /* Item */ 219 220 /** Set the title to a mrss_item_t element - the value is a string */ 221 MRSS_FLAG_ITEM_TITLE, 222 /** Set the title type to a mrss_item_t element - the value is a string */ 223 MRSS_FLAG_ITEM_TITLE_TYPE, 224 /** Set the link to a mrss_item_t element - the value is a string */ 225 MRSS_FLAG_ITEM_LINK, 226 /** Set the description to a mrss_item_t element - the value is a string */ 227 MRSS_FLAG_ITEM_DESCRIPTION, 228 /** Set the description type to a mrss_item_t element - the value is a string */ 229 MRSS_FLAG_ITEM_DESCRIPTION_TYPE, 230 /** Set the copyright to a mrss_item_t element - the value is a string */ 231 MRSS_FLAG_ITEM_COPYRIGHT, 232 /** Set the copyright type to a mrss_item_t element - the value is a string */ 233 MRSS_FLAG_ITEM_COPYRIGHT_TYPE, 234 235 /** Set the author to a mrss_item_t element - the value is a string */ 236 MRSS_FLAG_ITEM_AUTHOR, 237 /** Set the author's uri to a mrss_item_t element - the value is a string */ 238 MRSS_FLAG_ITEM_AUTHOR_URI, 239 /** Set the author's email to a mrss_item_t element - the value is a string */ 240 MRSS_FLAG_ITEM_AUTHOR_EMAIL, 241 242 /** Set the contributor to a mrss_item_t element - the value is a string */ 243 MRSS_FLAG_ITEM_CONTRIBUTOR, 244 /** Set the contributor's uri to a mrss_item_t element - the value is a string */ 245 MRSS_FLAG_ITEM_CONTRIBUTOR_URI, 246 /** Set the contributor's email to a mrss_item_t element - the value is a string */ 247 MRSS_FLAG_ITEM_CONTRIBUTOR_EMAIL, 248 249 /** Set the comments to a mrss_item_t element - the value is a string */ 250 MRSS_FLAG_ITEM_COMMENTS, 251 /** Set the pubDate to a mrss_item_t element - the value is a string */ 252 MRSS_FLAG_ITEM_PUBDATE, 253 /** Set the guid to a mrss_item_t element - the value is a string */ 254 MRSS_FLAG_ITEM_GUID, 255 /** Set the guid_isPermaLink to a mrss_item_t element - 256 * the value is a integer */ 257 MRSS_FLAG_ITEM_GUID_ISPERMALINK, 258 /** Set the source to a mrss_item_t element - the value is a string */ 259 MRSS_FLAG_ITEM_SOURCE, 260 /** Set the source_url to a mrss_item_t element - the value is a string */ 261 MRSS_FLAG_ITEM_SOURCE_URL, 262 /** Set the enclosure to a mrss_item_t element - the value is a string */ 263 MRSS_FLAG_ITEM_ENCLOSURE, 264 /** Set the enclosure_url to a mrss_item_t element - the value is a string */ 265 MRSS_FLAG_ITEM_ENCLOSURE_URL, 266 /** Set the enclosure_length to a mrss_item_t element - 267 * the value is a integer */ 268 MRSS_FLAG_ITEM_ENCLOSURE_LENGTH, 269 /** Set the enclosure_type to a mrss_item_t element - the value is a string */ 270 MRSS_FLAG_ITEM_ENCLOSURE_TYPE, 271 272 /* Item */ 273 274 /** Set the name to a mrss_tag_t element - the value is a string */ 275 MRSS_FLAG_TAG_NAME, 276 277 /** Set the value to a mrss_tag_t element - the value is a string */ 278 MRSS_FLAG_TAG_VALUE, 279 280 /** Set the namespace to a mrss_tag_t element - the value is a string */ 281 MRSS_FLAG_TAG_NS, 282 283 /** Set the name to a mrss_attribute_t element - the value is a string */ 284 MRSS_FLAG_ATTRIBUTE_NAME, 285 286 /** Set the value to a mrss_attribute_t element - the value is a string */ 287 MRSS_FLAG_ATTRIBUTE_VALUE, 288 289 /** Set the namespace to a mrss_attribute_t element - the value is a string */ 290 MRSS_FLAG_ATTRIBUTE_NS, 291 292 /** Set the terminetor flag */ 293 MRSS_FLAG_END = 0 294 295 } 296 297 /** 298 Enum for the casting of the libmrss data struct 299 */ 300 enum mrss_element_t { 301 /** The data struct is a mrss_t */ 302 MRSS_ELEMENT_CHANNEL, 303 /** The data struct is a mrss_item_t */ 304 MRSS_ELEMENT_ITEM, 305 /** The data struct is a mrss_hour_t */ 306 MRSS_ELEMENT_SKIPHOURS, 307 /** The data struct is a mrss_day_t */ 308 MRSS_ELEMENT_SKIPDAYS, 309 /** The data struct is a mrss_category_t */ 310 MRSS_ELEMENT_CATEGORY, 311 /** The data struct is a mrss_tag_t */ 312 MRSS_ELEMENT_TAG, 313 /** The data struct is a mrss_attribute_t */ 314 MRSS_ELEMENT_ATTRIBUTE 315 } 316 317 /** 318 Data struct for any items of RSS. It contains a pointer to the list 319 of categories. 320 */ 321 struct mrss_item_t { 322 323 /** For internal use only: */ 324 mrss_element_t element; 325 int allocated; 326 327 /* Data: */ 328 329 /* 0.91 0.92 1.0 2.0 ATOM */ 330 char* title; /* R O O O R */ 331 char* title_type; /* - - - - O */ 332 char* link; /* R O O O O */ 333 char* description; /* R O - O O */ 334 char* description_type; /* - - - - 0 */ 335 char* copyright; /* - - - - O */ 336 char* copyright_type; /* - - - - O */ 337 338 char* author; /* - - - O O */ 339 char* author_uri; /* - - - - O */ 340 char* author_email; /* - - - - O */ 341 342 char* contributor; /* - - - - O */ 343 char* contributor_uri; /* - - - - O */ 344 char* contributor_email; /* - - - - O */ 345 346 char* comments; /* - - - O - */ 347 char* pubDate; /* - - - O O */ 348 char* guid; /* - - - O O */ 349 int guid_isPermaLink; /* - - - O - */ 350 351 char* source; /* - O - O - */ 352 char* source_url; /* - R - R - */ 353 354 char* enclosure; /* - O - O - */ 355 char* enclosure_url; /* - R - R - */ 356 int enclosure_length; /* - R - R - */ 357 char* enclosure_type; /* - R - R - */ 358 359 mrss_category_t* category; /* - O - O O */ 360 361 mrss_tag_t* other_tags; 362 363 mrss_item_t* next; 364 } 365 366 /** 367 Data struct for skipHours elements. 368 */ 369 struct mrss_hour_t { 370 /** For internal use only: */ 371 mrss_element_t element; 372 int allocated; 373 374 /* Data: */ 375 /* 0.91 0.92 1.0 2.0 ATOM */ 376 char* hour; /* R R - R - */ 377 mrss_hour_t* next; 378 } 379 380 /** 381 Data struct for skipDays elements. 382 */ 383 struct mrss_day_t { 384 /** For internal use only: */ 385 mrss_element_t element; 386 int allocated; 387 388 /* Data: */ 389 /* 0.91 0.92 1.0 2.0 ATOM */ 390 char* day; /* R R - R - */ 391 mrss_day_t* next; 392 } 393 394 /** 395 Data struct for category elements 396 */ 397 struct mrss_category_t { 398 /** For internal use only: */ 399 mrss_element_t element; 400 int allocated; 401 402 /* Data: */ 403 /* 0.91 0.92 1.0 2.0 ATOM */ 404 char* category; /* - R - R R */ 405 char* domain; /* - O - O O */ 406 char* label; /* - - - - O */ 407 mrss_category_t* next; 408 } 409 410 /** 411 Principal data struct. It contains pointers to any other structures. 412 */ 413 struct mrss_t { 414 /** For internal use only: */ 415 mrss_element_t element; 416 int allocated; 417 int curl_error; 418 419 /* Data: */ 420 421 char* file; 422 size_t size; 423 char* encoding; 424 425 mrss_version_t version_; /* 0.91 0.92 1.0 2.0 ATOM */ 426 427 char* title; /* R R R R R */ 428 char* title_type; /* - - - - O */ 429 char* description; /* R R R R R */ 430 char* description_type; /* - - - - O */ 431 char* link; /* R R R R O */ 432 char* id; /* - - - - O */ 433 char* language; /* R O - O O */ 434 char* rating; /* O O - O - */ 435 char* copyright; /* O O - O O */ 436 char* copyright_type; /* - - - - O */ 437 char* pubDate; /* O O - O - */ 438 char* lastBuildDate; /* O O - O O */ 439 char* docs; /* O O - O - */ 440 char* managingeditor; /* O O - O O */ 441 char* managingeditor_email; /* O O - O O */ 442 char* managingeditor_uri; /* O O - O O */ 443 char* webMaster; /* O O - O - */ 444 int ttl; /* - - - O - */ 445 char* about; /* - - R - - */ 446 447 /// Contributor: /* - - - - O */ 448 char* contributor; /* - - - - R */ 449 char* contributor_email; /* - - - - O */ 450 char* contributor_uri; /* - - - - O */ 451 452 /// Generator: 453 char* generator; /* - - - O O */ 454 char* generator_uri; /* - - - - O */ 455 char* generator_version; /* - - - - O */ 456 457 /// Tag Image: /* O O O O - */ 458 char* image_title; /* R R R R - */ 459 char* image_url; /* R R R R O */ 460 char* image_logo; /* - - - - O */ 461 char* image_link; /* R R R R - */ 462 uint image_width; /* O O - O - */ 463 uint image_height; /* O O - O - */ 464 char* image_description; /* O O - O - */ 465 466 /// TextInput: /* O O O O - */ 467 char* textinput_title; /* R R R R - */ 468 char* textinput_description; /* R R R R - */ 469 char* textinput_name; /* R R R R - */ 470 char* textinput_link; /* R R R R - */ 471 472 /// Cloud: 473 char* cloud; /* - O - O - */ 474 char* cloud_domain; /* - R - R - */ 475 int cloud_port; /* - R - R - */ 476 char* cloud_path; /* - R - R - */ 477 char* cloud_registerProcedure;/* - R - R - */ 478 char* cloud_protocol; /* - R - R - */ 479 480 mrss_hour_t* skipHours; /* O O - O - */ 481 mrss_day_t* skipDays; /* O O - O - */ 482 483 mrss_category_t* category; /* - O - O O */ 484 485 mrss_item_t* item; /* R R R R R */ 486 487 mrss_tag_t* other_tags; 488 489 version (MRSS_USE_LOCALE) 490 void* c_locale; 491 } 492 493 /** 494 Data struct for any other tag out of the RSS namespace. 495 Struct data for external tags 496 */ 497 struct mrss_tag_t { 498 /** For internal use only: */ 499 mrss_element_t element; 500 int allocated; 501 502 /// name of the tag 503 char* name; 504 505 char* value; 506 507 /// namespace 508 char* ns; 509 510 /// list of attributes 511 mrss_attribute_t* attributes; 512 513 /// Sub tags 514 mrss_tag_t* children; 515 516 /// the next tag 517 mrss_tag_t* next; 518 } 519 520 /** 521 Data struct for the attributes of the tag 522 Struct data for external attribute 523 */ 524 struct mrss_attribute_t { 525 /// For internal use only 526 mrss_element_t element; 527 int allocated; 528 529 /// name of the tag 530 char* name; 531 532 /// value 533 char* value; 534 535 /// namespace 536 char* ns; 537 538 /// The next attribute 539 mrss_attribute_t* next; 540 } 541 542 /** 543 Options data struct. It contains some user preferences. 544 */ 545 struct mrss_options_t { 546 int timeout; 547 char* proxy; 548 char* proxy_authentication; 549 char* certfile; 550 char* cacert; 551 char* password; 552 int verifypeer; 553 char* authentication; 554 char* user_agent; 555 } 556 557 /** 558 Parse Functions: 559 */ 560 561 /** 562 Parses a url and creates the data struct of the feed RSS url. 563 This function downloads your request if this is http or ftp. 564 Params: 565 url = The url to be parsed 566 mrss = the pointer to your data struct 567 Returns: 568 the error code 569 */ 570 mrss_error_t mrss_parse_url (char* url, 571 mrss_t** mrss); 572 573 /** 574 Parses a url and creates the data struct of the feed RSS url. 575 This function downloads your request if this is http or ftp. 576 with an options struct. 577 Params: 578 url = The url to be parsed 579 mrss =the pointer to your data struct 580 options = a pointer to a options data struct 581 Returns: 582 the error code 583 */ 584 mrss_error_t mrss_parse_url_with_options 585 (char* url, 586 mrss_t** mrss, 587 mrss_options_t* options); 588 589 /** 590 Parses a url and creates the data struct of the feed RSS url. 591 This function downloads your request if this is http or ftp. 592 with an options struct and CURLcode error 593 Params: 594 url = The url to be parsed 595 mrss = the pointer to your data struct 596 options = a pointer to a options data struct. It can be null 597 curlcode = the error code from libcurl 598 Returns: 599 the error code 600 */ 601 mrss_error_t mrss_parse_url_with_options_and_error 602 (char* url, 603 mrss_t** mrss, 604 mrss_options_t* options, 605 CURLcode* curlcode); 606 607 /** 608 Like the previous function but you take ownership of the downloaded buffer 609 in case of success 610 Params: 611 url = The url to be parsed 612 mrss = the pointer to your data struct 613 options = a pointer to a options data struct 614 curlcode = the error code from libcurl 615 feed_content = a pointer to the buffer with the document. This is not null terminated 616 feed_size = the size of the buffer above 617 Returns: 618 the error code 619 */ 620 mrss_error_t mrss_parse_url_with_options_error_and_transfer_buffer 621 (char* url, 622 mrss_t** mrss, 623 mrss_options_t* options, 624 CURLcode* curlcode, 625 char** feed_content, 626 int* feed_size); 627 628 /** 629 Parses a file and creates the data struct of the feed RSS url 630 Params: 631 file = the file to be parsed 632 mrss = the pointer to your data struct 633 Returns: 634 the error code 635 */ 636 mrss_error_t mrss_parse_file (char* file, 637 mrss_t** mrss); 638 639 /** 640 Parses a buffer and creates the data struct of the feed RSS url 641 Params: 642 buffer = Pointer to the xml memory stream to be parsed 643 size_buffer = The size of the array of char 644 mrss = the pointer to your data struct 645 Returns: 646 the error code 647 */ 648 mrss_error_t mrss_parse_buffer (char* buffer, 649 size_t size_buffer, 650 mrss_t** mrss); 651 652 /** 653 Write Functions: 654 */ 655 656 /** 657 Writes a RSS struct data in a local file 658 Params: 659 mrss = the rss struct data 660 file = the local file 661 Returns: 662 the error code 663 */ 664 mrss_error_t mrss_write_file (mrss_t* mrss, 665 char* file); 666 667 /** 668 Write a RSS struct data in a buffer. 669 670 ` 671 char* buffer; 672 buffer=null; //<--- This is important!! 673 mrss_write_buffer (mrss, &buffer); 674 ` 675 The buffer must be null. 676 677 Params: 678 mrss = the rss struct data 679 buffer = the buffer 680 Returns: 681 the error code 682 */ 683 mrss_error_t mrss_write_buffer (mrss_t * mrss, 684 char** buffer); 685 686 /** 687 Free Function: 688 */ 689 690 /** 691 Frees any type of data struct of libmrss. If the element is alloced by libmrss, it will be freed, else this function frees 692 only the internal data. 693 ` 694 mrss_t *t=....; 695 mrss_item_t *item=...; 696 697 mrss_free(t); 698 mrss_free(item); 699 ` 700 Params: 701 element = the data struct 702 Returns: 703 the error code 704 */ 705 mrss_error_t mrss_free (mrss_generic_t element); 706 707 /** 708 Generic Functions: 709 */ 710 711 /** 712 This function returns a static string with the description of error code 713 Params: 714 err = the error code that you need as string 715 Returns: 716 a string. Don't free this string! 717 */ 718 char* mrss_strerror (mrss_error_t err); 719 720 /** 721 This function returns a static string with the description of curl code 722 Params: 723 err = the error code that you need as string 724 Returns: 725 a string. Don't free this string! 726 */ 727 char* mrss_curl_strerror (CURLcode err); 728 729 /** 730 Returns the mrss_element_t of a mrss data struct. 731 Params: 732 element = it is the element that you want check 733 ret = pointer to a mrss_element_t. It will be sets. 734 Returns: 735 the error code 736 */ 737 mrss_error_t mrss_element (mrss_generic_t element, 738 mrss_element_t* ret); 739 740 /** 741 Returns the number of seconds sinze January 1st 1970 in the 742 UTC time zone, for the url that the urlstring parameter specifies. 743 744 Params: 745 urlstring = the url 746 lastmodified = pointer to a time_t struct. The return value can 747 be 0 if the HEAD request does not return a Last-Modified value. 748 749 Returns: 750 the error code 751 */ 752 mrss_error_t mrss_get_last_modified (char* urlstring, 753 time_t* lastmodified); 754 755 /** 756 Returns the number of seconds sinze January 1st 1970 in the 757 UTC time zone, for the url that the urlstring parameter specifies. 758 With options struct 759 760 Params: 761 urlstring = the url 762 lastmodified = pointer to a time_t struct. The return value can 763 be 0 if the HEAD request does not return a Last-Modified value. 764 options = a pointer to a options struct 765 Returns: 766 the error code 767 */ 768 mrss_error_t mrss_get_last_modified_with_options 769 (char* urlstring, 770 time_t* lastmodified, 771 mrss_options_t* options); 772 /** 773 Returns the number of seconds sinze January 1st 1970 in the 774 UTC time zone, for the url that the urlstring parameter specifies. 775 With options struct and CURLcode pointer. 776 777 Params: 778 urlstring = the url 779 lastmodified = pointer to a time_t struct. The return value can 780 be 0 if the HEAD request does not return a Last-Modified value. 781 options = a pointer to a options struct 782 curl_code = error code of libcurl 783 Returns: 784 the error code 785 */ 786 mrss_error_t mrss_get_last_modified_with_options_and_error 787 (char* urlstring, 788 time_t* lastmodified, 789 mrss_options_t* options, 790 CURLcode* curl_code); 791 792 /** 793 Edit Functions: 794 */ 795 796 /** 797 To create a new feed RSS from scratch, use this function as the first. 798 799 ` 800 mrss_t *d; 801 mrss_error_t err; 802 char* string; 803 int integer; 804 805 d=null; // ->this is important! If d!=null, mrss_new doesn't alloc memory. 806 mrss_new(&d); 807 808 err=mrss_set (d, 809 MRSS_FLAG_VERSION, MRSS_VERSION_0_92, 810 MRSS_FLAG_TITLE, "the title!", 811 MRSS_FLAG_TTL, 12, 812 MRSS_FLAG_END); 813 814 if(err!=MRSS_OK) printf("%s\n",mrss_strerror(err)); 815 816 err=mrss_get (d, MRSS_FLAG_TITLE, &string, MRSS_FLAG_TTL, &integer, MRSS_FLAG_END); 817 818 if(err!=MRSS_OK) printf("%s\n",mrss_strerror(err)); 819 printf("The title is: '%s'\n", string); 820 printf("The ttl is: '%d'\n", integer); 821 free(string); 822 ` 823 Params: 824 mrss = pointer to the new data struct 825 Returns: 826 the error code 827 */ 828 mrss_error_t mrss_new (mrss_t** mrss); 829 830 /** 831 For insert/replace/remove a flags use this function as this example: 832 ` 833 mrss_set(mrss, MRSS_FLAG_TITLE, "hello world", MRSS_FLAG_END); 834 mrss_set(item, MRSS_FLAG_DESCRIPTION, null, MRSS_FLAG_END); 835 ` 836 837 Params: 838 element = mrss data that you want changes the next list of elements. The list is composted by KEY - VALUES and as last element MRSS_FLAG_END. 839 The variable of value depends from key. 840 Returns: 841 the error code 842 */ 843 mrss_error_t mrss_set (mrss_generic_t element, 844 ...); 845 846 /** 847 returns the request arguments. The syntax is the same of mrss_set but the values of the list are 848 pointer to data element (int *, * char* *). If the key needs a char* *, the value will be allocated. 849 850 ` 851 mrss_get(category, MRSS_FLAG_CATEGORY_DOMAIN, &string, MRSS_FLAG_END); 852 if(string) free(string); 853 ` 854 Params: 855 element = any type of mrss data struct 856 Returns: 857 the error code 858 */ 859 mrss_error_t mrss_get (mrss_generic_t element, 860 ...); 861 862 /** 863 adds an element to another element. For example: add a item to a channel, or a category to a item, and so on. 864 Example: 865 ` 866 mrss_item_t *item = null; 867 mrss_hour_t *hour = null; 868 mrss_day_t day; // If the element is no null, the function 869 mrss_category_t category, // does not alloc it 870 871 mrss_new_subdata(mrss, MRSS_ELEMENT_ITEM, &item); 872 mrss_new_subdata(mrss, MRSS_ELEMENT_SKIPHOURS, &hour); 873 mrss_new_subdata(mrss, MRSS_ELEMENT_SKIPDAYS, &day); 874 mrss_new_subdata(item, MRSS_ELEMENT_ITEM_CATEGORY, &category); 875 ` 876 877 Params: 878 element = parent element 879 subelement = type of the child (MRSS_ELEMENT_ITEM, MRSS_ELEMENT_CATEGORY, ...) 880 subdata = pointer to the new struct. If the pointer of *subdata does not exist it will be allocated otherwise not 881 Returns: 882 the error code 883 */ 884 mrss_error_t mrss_new_subdata (mrss_generic_t element, 885 mrss_element_t subelement, 886 mrss_generic_t subdata); 887 888 /** 889 Removes a subdata element. 890 Params: 891 element = parent 892 subdata = child to remove 893 Does not free the memory. So you can remove a item and reinsert it after. 894 Returns: 895 the error code 896 */ 897 mrss_error_t mrss_remove_subdata (mrss_generic_t element, 898 mrss_generic_t subdata); 899 900 /** 901 Tags Functions: 902 */ 903 904 /** 905 Search a tag in a mrss_t, a mrss_item_t or a mrss_tag_t from name and a namespace. 906 Params: 907 element = it is the parent node (mrss_t or mrss_item_t) 908 name = the name of the element 909 ns = the namespace. It can be null if the tag has a null namespace 910 tag = the return pointer 911 Returns: 912 the error code 913 */ 914 mrss_error_t mrss_search_tag (mrss_generic_t element, 915 char* name, 916 char* ns, 917 mrss_tag_t** tag); 918 919 /** 920 This function searches an attribute from a mrss_tag_t, a name and a namespace 921 Params: 922 element = it is the mrss_tag_t 923 name = the name of the element 924 ns = the namespace. It can be null if the tag has a null namespace 925 attribute = the return pointer 926 Returns: 927 the error code 928 */ 929 mrss_error_t mrss_search_attribute (mrss_generic_t element, 930 char* name, 931 char* ns, 932 mrss_attribute_t** attribute); 933 934 /** 935 OPTIONS FUNCTIONS: 936 */ 937 938 /** 939 This function creates a options struct. 940 941 Params: 942 timeout = timeout for the download procedure 943 proxy = a proxy server. can be null 944 proxy_authentication = a proxy authentication (user:pwd). can be null 945 certfile = a certificate for ssl authentication connection 946 password = the password of certfile 947 cacert = CA certificate to verify peer against. can be null 948 verifypeer = active/deactive the peer check 949 authentication = an authentication login (user:pwd). can be null 950 user_agent = a user_agent. can be null 951 952 Returns: 953 a pointer to a new allocated mrss_options_t struct 954 */ 955 mrss_options_t * 956 mrss_options_new (int timeout, 957 char* proxy, 958 char* proxy_authentication, 959 char* certfile, 960 char* password, 961 char* cacert, 962 int verifypeer, 963 char* authentication, 964 char* user_agent); 965 966 /** 967 This function destroys a options struct. 968 Params: 969 options = a pointer to a options struct 970 */ 971 void mrss_options_free (mrss_options_t* options);