1 /* 2 gutenfetch - a small utility to list and fetch books available through 3 project gutenberg 4 5 Copyright (C) 2001, 2002, 2003, 2004 Russell Francis 6 7 This program is free software; you can redistribute it and/or modify 8 it under the terms of the GNU General Public License as published by 9 the Free Software Foundation; either version 2 of the License, or 10 (at your option) any later version. 11 12 This program is distributed in the hope that it will be useful, 13 but WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 GNU General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with this program; if not, write to the 19 20 Free Software Foundation, Inc. 21 59 Temple Place, Suite 330 22 Boston, MA 02111-1307 USA 23 24 Last updated on $Date: 2004/07/11 22:39:51 $ by $Author: johntabularasa $. 25 */ 26 #ifndef GUTENFETCH_H 27 #define GUTENFETCH_H 28 #include <time.h> 29 30 /* 31 * This is a list of the possible error messages which the library 32 * may return on failure. 33 */ 34 typedef enum { 35 GUTENFETCH_OK, /* SUCCESS */ 36 GUTENFETCH_UNRECOGNIZED_ERROR, /* AN UNRECOGNIZED ERROR */ 37 GUTENFETCH_SEE_ERRNO, /* errno holds the error key. */ 38 GUTENFETCH_NOMEM, 39 GUTENFETCH_CURL_GLOBAL_INIT_FAILED, 40 GUTENFETCH_CURL_GET_HANDLE_FAILED, 41 GUTENFETCH_CURL_PERFORM_FAILED, 42 GUTENFETCH_BAD_PARAM, 43 GUTENFETCH_NO_ACTIVE_SERVER, 44 GUTENFETCH_UNABLE_TO_DETAIL_LISTING, 45 GUTENFETCH_UNABLE_TO_INIT_CACHE, 46 NUM_OF_ERRORS 47 } gutenfetch_error_t; 48 49 /* 50 * An enumerated list of the continents which servers have 51 * been on and may be on in the future. 52 */ 53 typedef enum { 54 NORTH_AMERICA, 55 SOUTH_AMERICA, 56 EUROPE, 57 AFRICA, 58 ASIA, 59 AUSTRALASIA_OCEANIA, 60 NUM_OF_CONTINENTS, 61 ALL_CONTINENTS, 62 UNKNOWN_CONTINENT 63 } gutenfetch_continent_t; 64 65 /* 66 * These can be passed to the listing 67 * functions to fine tune the ebooks that 68 * are returned. 69 */ 70 typedef enum { 71 LIST_NON_AUSTRALIAN, 72 LIST_AUSTRALIAN, 73 LIST_ALL, 74 } listing_type_t; 75 76 typedef enum { 77 AUSTRALIAN, 78 NON_AUSTRALIAN 79 } server_location_t; 80 81 /* 82 * This is used to hold the relevant information 83 * about a given project gutenberg server. 84 */ 85 typedef struct { 86 char *host; /* The base url to the gutenberg archives. */ 87 char *name; /* The organization sponsoring the gutenberg host. */ 88 char *area; /* The specific geographic region of the host. */ 89 /* The general geographic region of the host. */ 90 gutenfetch_continent_t continent; 91 } gutenfetch_server_t; 92 93 typedef struct { 94 unsigned int verified : 1; /* In the interest of time/bandwidth 95 * we can guess, this is set only if 96 * we have explicitly checked that these 97 * formats are available. */ 98 99 unsigned int plain_text : 1; /* plain ASCII text */ 100 unsigned int eight_bit_text : 1; /* 8-bit text for international glyphs */ 101 unsigned int big5_text : 1; /* Unsure */ 102 unsigned int unicode : 1; /* Unicode text */ 103 unsigned int html : 1; /* HTML encoded document */ 104 unsigned int tex : 1; /* TeX encoded document */ 105 unsigned int xml : 1; /* XML encoded document */ 106 unsigned int mp3 : 1; /* An audio recording in mp3 format */ 107 unsigned int rtf : 1; /* Rich Text Format */ 108 unsigned int pdf : 1; /* Adobe Acrobat Format */ 109 unsigned int lit : 1; /* Unsure */ 110 unsigned int doc : 1; /* Microsoft Word Document */ 111 unsigned int pdb : 1; /* Protein Data Bank file */ 112 unsigned int prc : 1; /* Palm Resource file */ 113 } gutenfetch_etext_formats_t; 114 115 /** 116 * Properties of an electronic text. 117 * 118 * This structure holds important information regarding 119 * the properties of a given electronic text. 120 * 121 */ 122 typedef struct { 123 /** 124 * This flag is set if the book is protected under copyright 125 * and has limitations to distribution which should be listed 126 * in the electronic text, if clear you are free to distribute 127 * this text in any way you wish. 128 */ 129 unsigned int copyright : 1; 130 131 /** 132 * This book is not in the project gutenberg archives but 133 * the name is reserved for when the book becomes available. 134 */ 135 unsigned int reserved : 1; 136 137 /** 138 * Due to copyright strangeness, this flag will be set if this 139 * book is only available from australia. 140 */ 141 unsigned int australia : 1; 142 } gutenfetch_etext_condition_t; 143 144 145 /* 146 * This holds the specific information regarding a single file on 147 * the Gutenberg servers, 148 */ 149 typedef struct { 150 char *directory; /* The directory of the file. */ 151 char *filebase; /* The base of the file. 152 * this may be different than 153 * the parent's filebase. */ 154 char *file_ext; /* The extension of the file */ 155 char *mime; /* MIME type of file */ 156 unsigned int filesize; /* The size in bytes */ 157 gutenfetch_etext_formats_t format; /* One flag will be set to 158 * indicate the file type. */ 159 unsigned int available_as_zip : 1; /* This file is available 160 * as a .zip file. */ 161 unsigned int aussie : 1; /* Look on the aussie servers for 162 this etext. */ 163 } gutenfetch_etext_entry_t; 164 165 166 /* 167 * This structure holds information regarding a specific title, 168 * on the Gutenberg servers. 169 */ 170 typedef struct { 171 char *full; /* The full line describing the book */ 172 char *author; /* The author, we will try to parse */ 173 char *title; /* The title of the book we will try to parse */ 174 char *directory; /* The directory to append the the server. */ 175 char *filebase; /* The base of the filename */ 176 char *extra; /* The extra more than 1 line description 177 of the text. */ 178 unsigned int id; /* The id number of the book */ 179 /* A flag which indicates certain props */ 180 gutenfetch_etext_condition_t cflag; 181 /* Indicates the avail formats for the book */ 182 gutenfetch_etext_formats_t fflag; 183 /* An array of entries, often there are 184 several editions of a single etext, 185 or it is available in 7 or 8 bit text, 186 each different format will be represented 187 with an entry in this NULL terminated 188 array. */ 189 gutenfetch_etext_entry_t **entry; 190 } gutenfetch_etext_t; 191 192 /* 193 * This structure is filled in when an electronic text 194 * is fetched. 195 */ 196 typedef struct { 197 char *filename; // The filename. 198 char *contents; // The contents. 199 size_t filesize; // The size in bytes of contents. 200 unsigned int zipped : 1; // whether this is a .ZIP compressed file. 201 } gutenfetch_file_t; 202 203 #ifdef __cplusplus 204 extern "C" { 205 #endif 206 207 /************************************************************** 208 * General initialization/shutdown. 209 **************************************************************/ 210 /* initialize the gutenfetch library, must be the 211 first function called. */ 212 gutenfetch_error_t gutenfetch_init(void); 213 214 /* Shutdown the gutenfetch library, must be the last 215 function called. */ 216 void gutenfetch_shutdown(void); 217 218 /* Get a string which states the version, it is statically allocated 219 and should not be freed or modified. */ 220 char * gutenfetch_version(void); 221 222 /* Return TRUE if the library is thread-safe. */ 223 int gutenfetch_is_threadsafe(void); 224 225 /************************************************************** 226 * Setting and Querying Servers 227 **************************************************************/ 228 /* get a NULL terminated list of available servers */ 229 gutenfetch_server_t ** 230 gutenfetch_list_servers(gutenfetch_continent_t); 231 232 /* get the current active server */ 233 gutenfetch_server_t * 234 gutenfetch_get_active_server(void); 235 236 /* Get aussie server */ 237 gutenfetch_server_t * 238 gutenfetch_get_aussie_server(void); 239 240 /* set the current active server with a URL only */ 241 gutenfetch_error_t 242 gutenfetch_set_active_server(char *); 243 244 /* Set the current active server with a gutenfetch_server_t */ 245 gutenfetch_error_t 246 gutenfetch_set_active_server_full(gutenfetch_server_t *); 247 248 /* Build a new server struct from raw inforeation. */ 249 gutenfetch_server_t * 250 gutenfetch_new_server(char *, char *, char *, gutenfetch_continent_t); 251 252 /* Duplicate an existing gutenfetch_server_t * */ 253 gutenfetch_server_t * 254 gutenfetch_duplicate_server(gutenfetch_server_t *); 255 256 /* Release the memory used by a gutenfetch_server_t */ 257 void 258 gutenfetch_free_server(gutenfetch_server_t *); 259 260 /* Release the memory used by an array of gutenfetch_server_t's */ 261 void 262 gutenfetch_free_servers(gutenfetch_server_t **); 263 264 /*************************************************************** 265 * Listing available etexts 266 ***************************************************************/ 267 268 gutenfetch_error_t gutenfetch_get_listing( 269 gutenfetch_etext_t ***, 270 listing_type_t, 271 int (*)(void *, double, double, double, const char *), 272 void *); 273 274 gutenfetch_error_t gutenfetch_get_raw_listing( 275 char **, 276 listing_type_t, 277 int (*progress_func)(void *, double, double, double, const char *), 278 void *data); 279 280 gutenfetch_error_t gutenfetch_detail_etext( 281 gutenfetch_etext_t *); 282 283 gutenfetch_error_t gutenfetch_detail_all_etexts( 284 int (*)(void*, double, double, double, const char *), 285 void *); 286 287 /*************************************************************** 288 * Fetch available electronic texts 289 ***************************************************************/ 290 gutenfetch_error_t gutenfetch_get_etext( 291 gutenfetch_etext_entry_t *, 292 gutenfetch_file_t *, 293 int, 294 int (*progress_func)(void *, double, double, double, const char *), 295 void *data); 296 297 298 /*************************************************************** 299 * Error handling 300 ***************************************************************/ 301 const char * gutenfetch_error_to_string(gutenfetch_error_t); 302 303 /*************************************************************** 304 * Cache Functions 305 **************************************************************/ 306 gutenfetch_error_t gutenfetch_cache_flush(void); 307 308 /* 309 * Get/Set how long a file remains *GOOD* once it 310 * is cached. default is 48hrs 311 */ 312 void gutenfetch_cache_set_expires(time_t); 313 time_t gutenfetch_cache_get_expires(void); 314 315 /* 316 * Enable/Disable caching 317 */ 318 gutenfetch_error_t gutenfetch_cache_enable(int); 319 int gutenfetch_cache_is_enabled(void); 320 321 322 /*************************************************************** 323 * Utility functions 324 ***************************************************************/ 325 /* These are 3 variations on a function which strips the '^M' 326 * character from etexts made in the Microsoft world. 327 */ 328 gutenfetch_error_t gutenfetch_ms_strip_text_buffer(char *); 329 gutenfetch_error_t gutenfetch_ms_strip_text_file(char *); 330 gutenfetch_error_t gutenfetch_ms_strip_text_fd(int); 331 332 /* These replace the UNIX/Mac newline with a windows newline. */ 333 gutenfetch_error_t gutenfetch_ms_clothe_text_buffer(char **); 334 gutenfetch_error_t gutenfetch_ms_clothe_text_file(char *); 335 gutenfetch_error_t gutenfetch_ms_clothe_text_fd(int); 336 337 #ifdef __cplusplus 338 } 339 #endif 340 341 #endif /* GUTENFETCH_H */ 342