4 libstorage \- InterNetNews Storage API library routines
7 .ta \w' unsigned long 'u
11 .B "bool IsToken(const char *text);"
13 .B "char *TokenToText(const TOKEN token);"
15 .B "TOKEN TextToToken(const char *text);"
17 .B "bool SMsetup(SMSETUP type, void *value);"
19 .B "bool SMinit(void);"
21 .B "TOKEN SMstore(const ARTHANDLE article);"
23 .B "ARTHANDLE *SMretrieve(const TOKEN token, const RETRTYPE amount);"
25 .B "ARTHANDLE *SMnext(const ARTHANDLE *article, const RETRTYPE amount);"
27 .B "void SMfreearticle(ARTHANDLE *article);"
29 .B "bool SMcancel(TOKEN token);"
31 .B "bool SMprobe(PROBETYPE type, TOKEN *token, void *value);"
33 .B "void SMprintfiles(FILE *file, TOKEN token, char **xref, int ngroups)"
35 .B "bool SMflushcacheddata(FLUSHTYPE type);"
37 .B "void SMshutdown(void);"
40 .B "char *SMerrorstr;"
44 .B "bool OVopen(int mode);"
46 .B "bool OVctl(OVCTLTYPE type, void *val);"
48 .B "bool OVgroupstats(char *group, int *lo, int *hi, int *count, int *flag);"
50 .B "bool OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);"
52 .B "bool OVgroupdel(char *group);"
54 .B "OVADDRESULT OVadd(TOKEN token, char *data, int len, time_t arrived);"
56 .B "bool OVcancel(TOKEN token);"
58 .B "void *OVopensearch(char *group, int low, int high);"
60 .B "bool OVsearch(void *handle, ARTNUM *artnum, char **data, int *len, TOKEN *token, time_t *arrived);"
62 .B "void OVclosesearch(void *handle);"
64 .B "bool OVgetartinfo(char *group, ARTNUM artnum, char **data, int *len, TOKEN *token);"
66 .B "bool OVexpiregroup(char *group, int *lo);"
68 .B "typedef struct _OVGE {"
74 .B " bool ignoreselfexpire;"
80 .B "void OVclose(void);"
85 is a library of common utility (the storage manager) routines for accessing
86 Usenet articles and related data independent of particular storage method;
87 this is known as the storage API.
88 The storage manager's function is to isolate the applications from the
89 individual methods and make the policy decisions as to which storage method
90 should be called to store an article.
92 One of the core concepts in the storage API is that articles are not
93 manipulated using the message-id or article number, but rather a token that
94 uniquely identifies the article to the method that stored it. This may seem
95 to be redundant since the message-id already is a unique identifier for the
96 article, however, since the storage method generates the token, it can
97 encode all the information it needs to locate the article in the token.
99 \&``OV'' is a common utility routines for accessing newsgroups and overview
100 data independent of particular overview method.
101 The ``OV'' function is to isolate the applications from the
104 All articles passed through the storage API are assumed to be in wire
105 format. Wire format means ``\\CR\\LF'' at the end of lines, ``.'' at the
106 beginning of lines, and ``.\\CR\\LF'' at the end of article on NNTP stream
107 are not stripped. This has a performance win when transferring articles.
108 For the ``tradspool'' method, wire format can be disabled. This is just
109 for compatibility which is needed by some old tools written for
113 checks to see if the text is formatted as a text token string.
114 It returns true if formatted correctly or returns false if not.
117 converts token into text string for output.
120 converts text into token.
123 configures some parameters for use by storage manager.
129 SM_RDWR allow read/write open for storage
130 files (default is false)
131 SM_PREOPEN open all storage files at startup
132 time and keep them (default is false)
138 is the pointer which tells each type's value.
139 It returns true if setup is successful, or false if not.
142 calls the setup function for all of the configured methods based on
144 This function should be called prior to all other storage API functions which
145 begin with ``SM'' except
147 It returns true if initialization is successful or returns false if not.
149 returns true, unless all storage methods fail initialization.
152 stores an article specified with
154 The headers and body of the article are supplied to
169 uses its value as article's arrival time; otherwise
171 uses the current time for it.
173 returns token type as
177 if article is not stored because some error occurs or simply does not
185 has not been set to true with
189 retrieves an article specified with
192 is the one of following which specifies retrieving type.
196 RETR_ALL retrieve whole article
197 RETR_HEAD retrieve headers of article
198 RETR_BODY retrieve body of article
199 RETR_STAT just check to see if article exists
204 provides the article data via the
213 The data area indicated by
215 should not be modified.
218 is similar in function to
220 except that it is intended for traversing the method's article store
224 should be called with a NULL pointer
230 which should be used for the next query.
233 is returned, no articles are left to be queried.
242 is 0, it indicates the article may be corrupted and should be cancelled by
244 The data area indicated by
246 should not be modified.
249 frees all allocated memory used by
255 will be called with previously returned
258 should not be called as
260 frees allocated memory internally.
263 removes the article specified with
265 It returns true if cancellation is successful or returns false if not.
269 has not been set to true with
280 SELFEXPIRE checks to see if the method of the token
281 has self expire functionality
282 SMARTNGNUM gets newsgroup name and article number
289 shows file name or token usable by
293 flushes cached data on each storage method.
299 SM_HEAD flushes cached header
300 SM_CANCELEDART flushes articles which should be canceled
301 SM_ALL flushes all cached data
307 calls the shutdown for each configured storage method and
308 then frees any resources it has allocated for itself.
313 indicate the reason of the last error concerning storage manager.
316 calls the setup function for configured method which is specified as
320 is constructed from following.
324 OV_READ allow read open for overview
326 OV_WRITE allow write open for overview
331 This function should be called prior to all other OV functions which
335 probes or sets some parameters for overview method.
341 OVGROUPBASEDEXPIRE setup how group-based expiry is
343 OVCUTOFFLOW do not add overview data, if the
344 data is under lowest article
345 OVSORT probe which key is suitable for
347 OVSPACE probe overview space usage
348 OVSTATALL stat all articles when
349 OVexpiregroup is called
355 retrieves specified newsgroup information from overview method.
358 informs overview method that specified newsgroup is being added.
361 informs overview method that specified newsgroup is being removed.
364 stores an overview data.
367 requests the overview method delete overview data specified with token.
370 requests the overview method prepare overview data retrieval.
371 The request range is determined by
377 retrieves information; article number, overview data, or arrival time.
379 should be called with NULL handle when it is the first time;
382 calls should use the handle returned by the previous call to
385 returns true, unless it reaches high which is specified by
387 Retrieved overview data are sorted by article number, and
389 is ``0'' if there is no overview data for article. Note that the
390 retrieved data is not neccessarily null-terminated; you should only rely
393 octets of overview data being present.
396 frees all resources which have been allocated by
400 retrieves overview data and token specified with
404 expires overview data for the newsgroup.
406 checks the existense of the article and purges overview data if the
407 article no longer exists.
408 If ``groupbaseexpiry'' in
412 also expires articles.
415 frees all resources which are used by the overview method.
417 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
419 This is revision \\$3, dated \\$4.
421 .R$ $Id: libstorage.3 6124 2003-01-14 06:03:29Z rra $
~ian / inn-innduct.git / blob