LIBSTORAGE(3)LIBSTORAGE(3)NAMElibstorage - InterNetNews Storage API library routines
SYNOPSIS
#include "storage.h"
BOOL IsToken(const char *text);
char *TokenToText(const TOKEN token);
TOKEN TextToToken(const char *text);
BOOL SMsetup(SMSETUP type, void *value);
BOOL SMinit(void);
TOKEN SMstore(const ARTHANDLE article);
ARTHANDLE *SMretrieve(const TOKEN token, const RETRTYPE amount);
ARTHANDLE *SMnext(const ARTHANDLE *article, const RETRTYPE amount);
void SMfreearticle(ARTHANDLE *article);
BOOL SMcancel(TOKEN token);
BOOL SMprobe(PROBETYPE type, TOKEN *token, void *value);
BOOL SMflushcacheddata(FLUSHTYPE type);
void SMshutdown(void);
int SMerrno;
char *SMerrorstr;
#include "ov.h"
BOOL OVopen(int mode);
BOOL OVctl(OVCTLTYPE type, void *val);
BOOL OVgroupstats(char *group, int *lo, int *hi, int *count, int *flag);
BOOL OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);
BOOL OVgroupdel(char *group);
BOOL OVadd(TOKEN token, char *data, int len, time_t arrived);
BOOL OVcancel(TOKEN token);
void *OVopensearch(char *group, int low, int high);
BOOL OVsearch(void *handle, ARTNUM *artnum, char **data, int *len, TOKEN *token, time_t *arrived);
void OVclosesearch(void *handle);
BOOL OVgetartinfo(char *group, ARTNUM artnum, char **data, int *len, TOKEN *token);
BOOL OVexpiregroup(char *group, int *lo);
typedef struct _OVGE {
BOOL delayrm;
BOOL usepost;
BOOL quiet;
BOOL keep;
BOOL earliest;
BOOL ignoreselfexpire;
char *filename;
time_t now;
float timewarp;
} OVGE;
void OVclose(void);
DESCRIPTION
Libstorage is a library of common utility (the storage
manager) routines for accessing Usenet articles and
related data independent of particular storage method, and
this is called storage api. The storage manager's func
tion 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.
One of the core concepts in the storage api is that arti
cles 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 identi
fier 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.
``OV'' is a common utility routines for accessing news
groups and overview data independent of particular
overview method. The ``OV'' function is to isolate the
applications from the individual methods.
All articles passed through storage api are assumed to be
wire formatted. Wire formatted means that ``\CR\LF'' at
the end of lines, ``.'' at the beginnig of lines and
``.\CR\LF'' at the end of article on nntp stream are not
stripped. This has performance win when transferring
articles. For ``tradspool'' method, wire format can be
disabled. This is just for compatibility which is needed
by some old tool written for traditional spool.
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.
TokenToText converts token into text token string.
TextToToken converts text into token.
SMsetup configures some parameters for use by storage man
ager. Type is one of following.
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)
The value is the pointer which tells each type's value.
It returns TRUE if setup is successful or returns FALSE if
not.
SMinit calls the setup function for all of the configured
methods based on SMsetup. This function should be called
prior to all other storage api functions which begin with
``SM'' except SMsetup. It returns TRUE if initialization
is successful or returns FALSE if not. SMinit returns
TRUE, unless all storage methods fail initialization.
SMstore stores an article specified with article. If
arrived is specified, SMstore use its value as article's
arrival time or SMstore use current time for it. SMstore
returns token type as type, or returns TOKEN_EMPTY if
article is not stored whichever error occures or simply
does not match wildmat(3) in storage.conf(5). SMstore
fails if SM_RDWR is not set to true with SMsetup.
SMretrieve retrieves an article specified with token.
Amount is the one of following which specifies retrieving
type.
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
The data area indicated by ARTHANDLE should not be modi
fied.
SMnext is similar in function to SMretrieve except that it
is intended for traversing the method's article store
sequentially. To start a query, SMnext should be called
with a NULL pointer ARTHANDLE. Then SMnext returns
ARTHANDLE which should be used for the next query. If
NULL pointer ARTHANDLE is returned, no article is left to
be queried. If data of ARTHANDLE is NULL pointer or len
of ARTHANDLE is 0, it indicates the article may be cor
rupted and should be cancelled by SMcancel. The data area
indicated by ARTHANDLE should not be modified.
SMfreearticle frees all allocated memory used by SMre_
trieve and SMnext. If SMnext will be called with previ
ously returned ARTHANDLE, SMfreearticle should not be
called as SMnext frees allocated memory in itself.
SMcancel removes an article specified with token. It
returns TRUE if cancellation is successful or returns
FALSE if not. SMcancel fails if SM_RDWR is not set to
true with SMsetup.
SMprobe checks the token on PROBETYPE. Type is one of
following.
SELFEXPIRE checks to see if the method of the token
has self expire functionality
SMARTNGNUM gets newsgroup name and article number
of the token.
SMflushcacheddata flushes cached data on each storage
method. Type is one of following.
SM_HEAD flushes cached header
SM_CANCELEDART flushes articles which should be canceled
SM_ALL flushes all cached data
SMshutdown calls the shutdown for each configured storage
method and then free any resources it has allocated for
itself.
SMerrno and SMerrorstr indicates the reason of the last
error concerning storage manager.
OVopen calls the setup function for configured method
which is specified as ``ovmethod'' in inn.conf(5). Mode
is constructed from following.
OV_READ allow read open for overview
method
OV_WRITE allow write open for overview
method
This function should be called prior to all other OV func
tions which begin with ``OV''.
OVctl probes or set some parameters for overview method.
Type is one of following.
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
OVgroupstats retrieves specified newsgroup information
from overview method.
OVgroupadd informs overview method to specified newsgroup
is added.
OVgroupdel informs overview method to specified newsgroup
is removed.
OVadd stores an overview data.
OVcancel requests overview method to delete an overview
data specified with token.
OVopensearch requests overview method to prepare overview
data retrieval. The request range is determined by low
and high.
OVsearch retrieves information; article number, overview
data or arrival time. OVsearch should be called with NULL
handle when it is the 1st time. And subsequent OVsearch
should be called with the handle which is got at preveous
OVsearch. OVsearch returns TRUE, unless it reaches high
which is specified by OVopensearch. Retrieved overview
data are sorted by article number, and len is 0 if there
is no overview data for article.
OVclosesearch frees all resources which is allocated by
OVopensearch.
OVgetartinfo retrieves overview data and token specified
with artnum.
OVexpiregroup expires overview data for the newsgroup.
OVexpiregroup checks the existense of the article and
purge overview data if it's gone. If ``groupbaseexpiry''
in inn.conf is true, OVexpiregroup also expires articles.
OVclose frees all resources which is used by overview
method.
HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for Inter
NetNews. This is revision 1.12.2.2, dated 2000/09/05.
SEE ALSOexpire(8), inn.conf(5), storage.conf(5).
LIBSTORAGE(3)
