/* gutenfetch - a small utility to list and fetch books available through project gutenberg Copyright (C) 2001, 2002, 2003, 2004 Russell Francis This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc. 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Last updated on $Date: 2004/07/11 22:39:51 $ by $Author: johntabularasa $. */ #ifndef GUTENFETCH_H #define GUTENFETCH_H #include /* * This is a list of the possible error messages which the library * may return on failure. */ typedef enum { GUTENFETCH_OK, /* SUCCESS */ GUTENFETCH_UNRECOGNIZED_ERROR, /* AN UNRECOGNIZED ERROR */ GUTENFETCH_SEE_ERRNO, /* errno holds the error key. */ GUTENFETCH_NOMEM, GUTENFETCH_CURL_GLOBAL_INIT_FAILED, GUTENFETCH_CURL_GET_HANDLE_FAILED, GUTENFETCH_CURL_PERFORM_FAILED, GUTENFETCH_BAD_PARAM, GUTENFETCH_NO_ACTIVE_SERVER, GUTENFETCH_UNABLE_TO_DETAIL_LISTING, GUTENFETCH_UNABLE_TO_INIT_CACHE, NUM_OF_ERRORS } gutenfetch_error_t; /* * An enumerated list of the continents which servers have * been on and may be on in the future. */ typedef enum { NORTH_AMERICA, SOUTH_AMERICA, EUROPE, AFRICA, ASIA, AUSTRALASIA_OCEANIA, NUM_OF_CONTINENTS, ALL_CONTINENTS, UNKNOWN_CONTINENT } gutenfetch_continent_t; /* * These can be passed to the listing * functions to fine tune the ebooks that * are returned. */ typedef enum { LIST_NON_AUSTRALIAN, LIST_AUSTRALIAN, LIST_ALL, } listing_type_t; typedef enum { AUSTRALIAN, NON_AUSTRALIAN } server_location_t; /* * This is used to hold the relevant information * about a given project gutenberg server. */ typedef struct { char *host; /* The base url to the gutenberg archives. */ char *name; /* The organization sponsoring the gutenberg host. */ char *area; /* The specific geographic region of the host. */ /* The general geographic region of the host. */ gutenfetch_continent_t continent; } gutenfetch_server_t; typedef struct { unsigned int verified : 1; /* In the interest of time/bandwidth * we can guess, this is set only if * we have explicitly checked that these * formats are available. */ unsigned int plain_text : 1; /* plain ASCII text */ unsigned int eight_bit_text : 1; /* 8-bit text for international glyphs */ unsigned int big5_text : 1; /* Unsure */ unsigned int unicode : 1; /* Unicode text */ unsigned int html : 1; /* HTML encoded document */ unsigned int tex : 1; /* TeX encoded document */ unsigned int xml : 1; /* XML encoded document */ unsigned int mp3 : 1; /* An audio recording in mp3 format */ unsigned int rtf : 1; /* Rich Text Format */ unsigned int pdf : 1; /* Adobe Acrobat Format */ unsigned int lit : 1; /* Unsure */ unsigned int doc : 1; /* Microsoft Word Document */ unsigned int pdb : 1; /* Protein Data Bank file */ unsigned int prc : 1; /* Palm Resource file */ } gutenfetch_etext_formats_t; /** * Properties of an electronic text. * * This structure holds important information regarding * the properties of a given electronic text. * */ typedef struct { /** * This flag is set if the book is protected under copyright * and has limitations to distribution which should be listed * in the electronic text, if clear you are free to distribute * this text in any way you wish. */ unsigned int copyright : 1; /** * This book is not in the project gutenberg archives but * the name is reserved for when the book becomes available. */ unsigned int reserved : 1; /** * Due to copyright strangeness, this flag will be set if this * book is only available from australia. */ unsigned int australia : 1; } gutenfetch_etext_condition_t; /* * This holds the specific information regarding a single file on * the Gutenberg servers, */ typedef struct { char *directory; /* The directory of the file. */ char *filebase; /* The base of the file. * this may be different than * the parent's filebase. */ char *file_ext; /* The extension of the file */ char *mime; /* MIME type of file */ unsigned int filesize; /* The size in bytes */ gutenfetch_etext_formats_t format; /* One flag will be set to * indicate the file type. */ unsigned int available_as_zip : 1; /* This file is available * as a .zip file. */ unsigned int aussie : 1; /* Look on the aussie servers for this etext. */ } gutenfetch_etext_entry_t; /* * This structure holds information regarding a specific title, * on the Gutenberg servers. */ typedef struct { char *full; /* The full line describing the book */ char *author; /* The author, we will try to parse */ char *title; /* The title of the book we will try to parse */ char *directory; /* The directory to append the the server. */ char *filebase; /* The base of the filename */ char *extra; /* The extra more than 1 line description of the text. */ unsigned int id; /* The id number of the book */ /* A flag which indicates certain props */ gutenfetch_etext_condition_t cflag; /* Indicates the avail formats for the book */ gutenfetch_etext_formats_t fflag; /* An array of entries, often there are several editions of a single etext, or it is available in 7 or 8 bit text, each different format will be represented with an entry in this NULL terminated array. */ gutenfetch_etext_entry_t **entry; } gutenfetch_etext_t; /* * This structure is filled in when an electronic text * is fetched. */ typedef struct { char *filename; // The filename. char *contents; // The contents. size_t filesize; // The size in bytes of contents. unsigned int zipped : 1; // whether this is a .ZIP compressed file. } gutenfetch_file_t; #ifdef __cplusplus extern "C" { #endif /************************************************************** * General initialization/shutdown. **************************************************************/ /* initialize the gutenfetch library, must be the first function called. */ gutenfetch_error_t gutenfetch_init(void); /* Shutdown the gutenfetch library, must be the last function called. */ void gutenfetch_shutdown(void); /* Get a string which states the version, it is statically allocated and should not be freed or modified. */ char * gutenfetch_version(void); /* Return TRUE if the library is thread-safe. */ int gutenfetch_is_threadsafe(void); /************************************************************** * Setting and Querying Servers **************************************************************/ /* get a NULL terminated list of available servers */ gutenfetch_server_t ** gutenfetch_list_servers(gutenfetch_continent_t); /* get the current active server */ gutenfetch_server_t * gutenfetch_get_active_server(void); /* Get aussie server */ gutenfetch_server_t * gutenfetch_get_aussie_server(void); /* set the current active server with a URL only */ gutenfetch_error_t gutenfetch_set_active_server(char *); /* Set the current active server with a gutenfetch_server_t */ gutenfetch_error_t gutenfetch_set_active_server_full(gutenfetch_server_t *); /* Build a new server struct from raw inforeation. */ gutenfetch_server_t * gutenfetch_new_server(char *, char *, char *, gutenfetch_continent_t); /* Duplicate an existing gutenfetch_server_t * */ gutenfetch_server_t * gutenfetch_duplicate_server(gutenfetch_server_t *); /* Release the memory used by a gutenfetch_server_t */ void gutenfetch_free_server(gutenfetch_server_t *); /* Release the memory used by an array of gutenfetch_server_t's */ void gutenfetch_free_servers(gutenfetch_server_t **); /*************************************************************** * Listing available etexts ***************************************************************/ gutenfetch_error_t gutenfetch_get_listing( gutenfetch_etext_t ***, listing_type_t, int (*)(void *, double, double, double, const char *), void *); gutenfetch_error_t gutenfetch_get_raw_listing( char **, listing_type_t, int (*progress_func)(void *, double, double, double, const char *), void *data); gutenfetch_error_t gutenfetch_detail_etext( gutenfetch_etext_t *); gutenfetch_error_t gutenfetch_detail_all_etexts( int (*)(void*, double, double, double, const char *), void *); /*************************************************************** * Fetch available electronic texts ***************************************************************/ gutenfetch_error_t gutenfetch_get_etext( gutenfetch_etext_entry_t *, gutenfetch_file_t *, int, int (*progress_func)(void *, double, double, double, const char *), void *data); /*************************************************************** * Error handling ***************************************************************/ const char * gutenfetch_error_to_string(gutenfetch_error_t); /*************************************************************** * Cache Functions **************************************************************/ gutenfetch_error_t gutenfetch_cache_flush(void); /* * Get/Set how long a file remains *GOOD* once it * is cached. default is 48hrs */ void gutenfetch_cache_set_expires(time_t); time_t gutenfetch_cache_get_expires(void); /* * Enable/Disable caching */ gutenfetch_error_t gutenfetch_cache_enable(int); int gutenfetch_cache_is_enabled(void); /*************************************************************** * Utility functions ***************************************************************/ /* These are 3 variations on a function which strips the '^M' * character from etexts made in the Microsoft world. */ gutenfetch_error_t gutenfetch_ms_strip_text_buffer(char *); gutenfetch_error_t gutenfetch_ms_strip_text_file(char *); gutenfetch_error_t gutenfetch_ms_strip_text_fd(int); /* These replace the UNIX/Mac newline with a windows newline. */ gutenfetch_error_t gutenfetch_ms_clothe_text_buffer(char **); gutenfetch_error_t gutenfetch_ms_clothe_text_file(char *); gutenfetch_error_t gutenfetch_ms_clothe_text_fd(int); #ifdef __cplusplus } #endif #endif /* GUTENFETCH_H */