libstorage - 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);


       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

       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

       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

            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.

       expire(8), inn.conf(5), storage.conf(5).


Man(1) output converted with man2html