.\" $Revision: 6124 $
.TH LIBSTORAGE 3
.SH NAME
libstorage \- InterNetNews Storage API library routines
.SH SYNOPSIS
.nf
.ta \w'    unsigned long    'u

#include "storage.h"

.B "bool IsToken(const char *text);"

.B "char *TokenToText(const TOKEN token);"

.B "TOKEN TextToToken(const char *text);"

.B "bool SMsetup(SMSETUP type, void *value);"

.B "bool SMinit(void);"

.B "TOKEN SMstore(const ARTHANDLE article);"

.B "ARTHANDLE *SMretrieve(const TOKEN token, const RETRTYPE amount);"

.B "ARTHANDLE *SMnext(const ARTHANDLE *article, const RETRTYPE amount);"

.B "void SMfreearticle(ARTHANDLE *article);"

.B "bool SMcancel(TOKEN token);"

.B "bool SMprobe(PROBETYPE type, TOKEN *token, void *value);"

.B "void SMprintfiles(FILE *file, TOKEN token, char **xref, int ngroups)"

.B "bool SMflushcacheddata(FLUSHTYPE type);"

.B "void SMshutdown(void);"

.B "int SMerrno;"
.B "char *SMerrorstr;"

#include "ov.h"

.B "bool OVopen(int mode);"

.B "bool OVctl(OVCTLTYPE type, void *val);"

.B "bool OVgroupstats(char *group, int *lo, int *hi, int *count, int *flag);"

.B "bool OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);"

.B "bool OVgroupdel(char *group);"

.B "OVADDRESULT OVadd(TOKEN token, char *data, int len, time_t arrived);"

.B "bool OVcancel(TOKEN token);"

.B "void *OVopensearch(char *group, int low, int high);"

.B "bool OVsearch(void *handle, ARTNUM *artnum, char **data, int *len, TOKEN *token, time_t *arrived);"

.B "void OVclosesearch(void *handle);"

.B "bool OVgetartinfo(char *group, ARTNUM artnum, char **data, int *len, TOKEN *token);"

.B "bool OVexpiregroup(char *group, int *lo);"

.B "typedef struct _OVGE {"
.B "    bool        delayrm;"
.B "    bool        usepost;"
.B "    bool        quiet;"
.B "    bool        keep;"
.B "    bool        earliest;"
.B "    bool        ignoreselfexpire;"
.B "    char        *filename;"
.B "    time_t      now;"
.B "    float       timewarp;"
.B "} OVGE;"

.B "void OVclose(void);"

.fi
.SH DESCRIPTION
.I Libstorage
is a library of common utility (the storage manager) routines for accessing
Usenet articles and related data independent of particular storage method;
this is known as the storage API.
The storage manager's function is to isolate the applications from the
individual methods and make the policy decisions as to which storage method
should be called to store an article.
.PP
One of the core concepts in the storage API is that articles are not
manipulated using the message-id or article number, but rather a token that
uniquely identifies the article to the method that stored it.  This may seem
to be redundant since the message-id already is a unique identifier for the
article, however, since the storage method generates the token, it can
encode all the information it needs to locate the article in the token.
.PP
\&``OV'' is a common utility routines for accessing newsgroups and overview
data independent of particular overview method.
The ``OV'' function is to isolate the applications from the
individual methods.
.PP
All articles passed through the storage API are assumed to be in wire
format.  Wire format means ``\\CR\\LF'' at the end of lines, ``.'' at the
beginning of lines, and ``.\\CR\\LF'' at the end of article on NNTP stream
are not stripped.  This has a performance win when transferring articles.
For the ``tradspool'' method, wire format can be disabled.  This is just
for compatibility which is needed by some old tools written for
traditional spool.
.PP
.I IsToken
checks to see if the text is formatted as a text token string.
It returns true if formatted correctly or returns false if not.
.PP
.I TokenToText
converts token into text string for output.
.PP
.I TextToToken
converts text into token.
.PP
.I SMsetup
configures some parameters for use by storage manager.
.I Type
is one of following.
.sp 1
.in +0.5i
.nf
SM_RDWR	allow read/write open for storage
	files (default is false)
SM_PREOPEN	open all storage files at startup
	time and keep them (default is false)
.fi
.in -0.5i
.sp 1
The
.I value
is the pointer which tells each type's value.
It returns true if setup is successful, or false if not.
.PP
.I SMinit
calls the setup function for all of the configured methods based on
.IR SMsetup .
This function should be called prior to all other storage API functions which
begin with ``SM'' except
.IR SMsetup .
It returns true if initialization is successful or returns false if not.
.I SMinit
returns true, unless all storage methods fail initialization.
.PP
.I SMstore
stores an article specified with
.IR article .
If
.I arrived
is specified,
.I SMstore
uses its value as article's arrival time; otherwise
.I SMstore
uses the current time for it.
.I SMstore
returns token type as
.IR type ,
or returns
.I TOKEN_EMPTY
if article is not stored because some error occurs or simply does not
match any
.IR uwildmat (3)
in
.IR storage.conf .
.I SMstore
fails if
.I SM_RDWR
has not been set to true with
.IR SMsetup .
.PP
.I SMretrieve
retrieves an article specified with
.IR token .
.I Amount
is the one of following which specifies retrieving type.
.sp 1
.in +0.5i
.nf
RETR_ALL	retrieve whole article
RETR_HEAD	retrieve headers of article
RETR_BODY	retrieve body of article
RETR_STAT	just check to see if article exists
.fi
.in -0.5i
.sp 1
.PP
The data area indicated by
.I ARTHANDLE
should not be modified.
.PP
.I SMnext
is similar in function to
.I SMretrieve
except that it is intended for traversing the method's article store
sequentially.
To start a query,
.I SMnext
should be called with a NULL pointer
.IR ARTHANDLE .
Then
.I SMnext
returns
.I ARTHANDLE
which should be used for the next query.
If a NULL pointer
.I ARTHANDLE
is returned, no articles are left to be queried.
If
.I data
of
.I ARTHANDLE
is NULL pointer or
.I len
of
.I ARTHANDLE
is 0, it indicates the article may be corrupted and should be cancelled by
.IR SMcancel .
The data area indicated by
.I ARTHANDLE
should not be modified.
.PP
.I SMfreearticle
frees all allocated memory used by
.I SMretrieve
and
.IR SMnext .
If
.I SMnext
will be called with previously returned
.IR ARTHANDLE ,
.I SMfreearticle
should not be called as
.I SMnext
frees allocated memory internally.
.PP
.I SMcancel
removes the article specified with
.IR token .
It returns true if cancellation is successful or returns false if not.
.I SMcancel
fails if
.I SM_RDWR
has not been set to true with
.IR SMsetup .
.PP
.I SMprobe
checks the token on
.IR PROBETYPE .
.I Type
is one of following.
.sp 1
.in +0.5i
.nf
SELFEXPIRE	checks to see if the method of the token
	has self expire functionality
SMARTNGNUM	gets newsgroup name and article number
	of the token.
.fi
.in -0.5i
.sp 1
.PP
.I SMprintfiles
shows file name or token usable by
.IR fastrm (8).
.PP
.I SMflushcacheddata
flushes cached data on each storage method.
.I Type
is one of following.
.sp 1
.in +0.5i
.nf
SM_HEAD	flushes cached header
SM_CANCELEDART	flushes articles which should be canceled
SM_ALL	flushes all cached data
.fi
.in -0.5i
.sp 1
.PP
.I SMshutdown
calls the shutdown for each configured storage method and
then frees any resources it has allocated for itself.
.PP
.I SMerrno
and
.I SMerrorstr
indicate the reason of the last error concerning storage manager.
.PP
.I OVopen
calls the setup function for configured method which is specified as
\&``ovmethod'' in
.IR inn.conf .
.I Mode
is constructed from following.
.sp 1
.in +0.5i
.nf
OV_READ	allow read open for overview
	method
OV_WRITE	allow write open for overview
	method
.fi
.in -0.5i
.sp 1
This function should be called prior to all other OV functions which
begin with ``OV''.
.PP
.I OVctl
probes or sets some parameters for overview method.
.I Type
is one of following.
.sp 1
.in +0.5i
.nf
OVGROUPBASEDEXPIRE	setup how group-based expiry is
	done
OVCUTOFFLOW	do not add overview data, if the
	data is under lowest article
OVSORT	probe which key is suitable for
	overview method
OVSPACE	probe overview space usage
OVSTATALL	stat all articles when
	OVexpiregroup is called
.fi
.in -0.5i
.sp 1
.PP
.I OVgroupstats
retrieves specified newsgroup information from overview method.
.PP
.I OVgroupadd
informs overview method that specified newsgroup is being added.
.PP
.I OVgroupdel
informs overview method that specified newsgroup is being removed.
.PP
.I OVadd
stores an overview data.
.PP
.I OVcancel
requests the overview method delete overview data specified with token.
.PP
.I OVopensearch
requests the overview method prepare overview data retrieval.
The request range is determined by
.I low
and
.IR high .
.PP
.I OVsearch
retrieves information; article number, overview data, or arrival time.
.I OVsearch
should be called with NULL handle when it is the first time;
subsequent
.I OVsearch
calls should use the handle returned by the previous call to
.IR OVsearch .
.I OVsearch
returns true, unless it reaches high which is specified by
.IR OVopensearch .
Retrieved overview data are sorted by article number, and
.I len
is ``0'' if there is no overview data for article.  Note that the
retrieved data is not neccessarily null-terminated; you should only rely
on
.I len
octets of overview data being present.
.PP
.I OVclosesearch
frees all resources which have been allocated by
.IR OVopensearch .
.PP
.I OVgetartinfo
retrieves overview data and token specified with
.IR artnum .
.PP
.I OVexpiregroup
expires overview data for the newsgroup.
.I OVexpiregroup
checks the existense of the article and purges overview data if the
article no longer exists.
If ``groupbaseexpiry'' in
.I inn.conf
is true,
.I OVexpiregroup
also expires articles.
.PP
.I OVclose
frees all resources which are used by the overview method.
.SH HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
.de R$
This is revision \\$3, dated \\$4.
..
.R$ $Id: libstorage.3 6124 2003-01-14 06:03:29Z rra $
.SH "SEE ALSO"
expire(8),
inn.conf(5),
storage.conf(5).