LIBGUTENFETCH(3)libgutenfetch overview LIBGUTENFETCH(3)NAMElibgutenfetch - Client-side library to retrieve listings and books
availiable from Project Gutenberg.
DESCRIPTION
This is an overview of how to use libgutenfetch in C programs. There
are specific man pages for each function mentioned within this manual.
All applications that wish to use libgutenfetch must include the guten‐
fetch.h header file. The application must also call gutenfetch_init()
at startup and wait for it to return before calling any other libguten‐
fetch functions. When the application is finished using the library,
gutenfetch_shutdown() must also be called to free all internal
resources.
There are a handful of useful functions provided by the library. These
include the following.
gutenfetch_init()
Initialize internal resouces used by libgutenfetch.
gutenfetch_shutdown()
Release resources held internally by libgutenfetch.
gutenfetch_version()
Returns a NULL-terminated string with the version of
the library you are using.
gutenfetch_is_threadsafe()
Returns 1 if the library is compiled to be thread-
safe, 0 otherwise.
gutenfetch_list_servers()
Get a list of potential servers to use for fetching
etexts from Project Gutenberg.
gutenfetch_get_active_server()
Return the gutenberg server we are currently using to
satisfy requests.
gutenfetch_get_aussie_server()
Return the australian server used to satisfy requests
for etexts available only from/to Australia.
gutenfetch_set_active_server()
Set the current server to use.
gutenfetch_set_active_server_full()
Set the current server to use more explicitly than the
previous function.
gutenfetch_new_server()
Build a new gutenfetch server to use.
gutenfetch_duplicate_server()
Return a dupliacte gutenfetch_server_t structure.
gutenfetch_free_server()
Free the resources held by a gutenfetch_server_t
structure.
gutenfetch_free_servers()
Free all resources held by an array of guten‐
fetch_server_t structures.
gutenfetch_get_listing()
Get a list of all electronic texts available from
Project Gutenberg.
gutenfetch_get_raw_listing()
This returns the unaltered contents of the GUTIN‐
DEX.ALL file from the current server.
gutenfetch_detail_etext()
This function fetches detailed information about a
particular electronic text, returning information
about the different formats that the book is available
in.
gutenfetch_detail_all_etexts()
This function is like the one above except that it
gets information for all known electronic texts.
gutenfetch_get_etext()
Fetch the contents of a particular electronic text.
gutenfetch_error_to_string()
This function generates a human readable string for
any of the internal errors which may be generated by
libgutenfetch.
gutenfetch_cache_flush()
Remove all cached files from the hard disk.
gutenfetch_cache_set_expires()
Set the length of time files can remain cached on disk
without being accessed.
gutenfetch_cache_get_expires()
Return the length of time files can remain cached on
disk without being accessed.
gutenfetch_cache_enable()
This function allows the application to enable or dis‐
able caching of electronic texts and intermediate
files on the local disk.
gutenfetch_cache_is_enabled()
This function determines whether caching is currently
enabled or disabled.
gutenfetch_ms_strip_text_buffer()gutenfetch_ms_strip_text_file()gutenfetch_ms_strip_text_fd()
These three utility functions strip the '^M' symbol
from the end of the lines in text files created in the
Microsoft world. And allow the text file to be dis‐
played properly on UNIX and Macintosh machines.
gutenfetch_ms_clothe_text_buffer()gutenfetch_ms_clothe_text_file()gutenfetch_ms_clothe_text_fd()
These three utility functions add the '^M' to the end
of lines in text files which are created in the UNIX
and Macintosh worlds. This allows Windows users to
properly display electronic texts created elsewhere.
PORTABILITYlibgutenfetch should compile easily and work the same on any platform
which is out there. If it doesn't, please let me know by reporting it
as a bug.
THREADING
If libgutenfetch is compiled with threading support, it should be com‐
pletely thread-safe as long as you wait for gutenfetch_init() to return
before calling any other functions. If libgutenfetch is not compiled
with threading support, you should not call multiple functions from
different threads. It's behavior may be unpredictable and quite possi‐
bly wrong!
COPYRIGHTlibgutenfetch is Copyright (C) 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 MER‐
CHANTABILITY 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
BUGS
Probably, if you find them please take the time to let me know about
them by filling out a bug report at the following URL.
http://www.sourceforge.net/tracker/?group_id=104733&func=browse
AUTHORS
Russell Francis <johntabularasa@users.sf.net>
libgutenfetch 2.0 21 March 2004 LIBGUTENFETCH(3)
