/*
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 <time.h>
/*
* 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 */
syntax highlighted by Code2HTML, v. 0.9.1