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
158 uses its value as article's arrival time; otherwise
160 uses the current time for it.
162 returns token type as
166 if article is not stored because some error occurs or simply does not
174 has not been set to true with
178 retrieves an article specified with
181 is the one of following which specifies retrieving type.
185 RETR_ALL retrieve whole article
186 RETR_HEAD retrieve headers of article
187 RETR_BODY retrieve body of article
188 RETR_STAT just check to see if article exists
193 The data area indicated by
195 should not be modified.
198 is similar in function to
200 except that it is intended for traversing the method's article store
204 should be called with a NULL pointer
210 which should be used for the next query.
213 is returned, no articles are left to be queried.
222 is 0, it indicates the article may be corrupted and should be cancelled by
224 The data area indicated by
226 should not be modified.
229 frees all allocated memory used by
235 will be called with previously returned
238 should not be called as
240 frees allocated memory internally.
243 removes the article specified with
245 It returns true if cancellation is successful or returns false if not.
249 has not been set to true with
260 SELFEXPIRE checks to see if the method of the token
261 has self expire functionality
262 SMARTNGNUM gets newsgroup name and article number
269 shows file name or token usable by
273 flushes cached data on each storage method.
279 SM_HEAD flushes cached header
280 SM_CANCELEDART flushes articles which should be canceled
281 SM_ALL flushes all cached data
287 calls the shutdown for each configured storage method and
288 then frees any resources it has allocated for itself.
293 indicate the reason of the last error concerning storage manager.
296 calls the setup function for configured method which is specified as
300 is constructed from following.
304 OV_READ allow read open for overview
306 OV_WRITE allow write open for overview
311 This function should be called prior to all other OV functions which
315 probes or sets some parameters for overview method.
321 OVGROUPBASEDEXPIRE setup how group-based expiry is
323 OVCUTOFFLOW do not add overview data, if the
324 data is under lowest article
325 OVSORT probe which key is suitable for
327 OVSPACE probe overview space usage
328 OVSTATALL stat all articles when
329 OVexpiregroup is called
335 retrieves specified newsgroup information from overview method.
338 informs overview method that specified newsgroup is being added.
341 informs overview method that specified newsgroup is being removed.
344 stores an overview data.
347 requests the overview method delete overview data specified with token.
350 requests the overview method prepare overview data retrieval.
351 The request range is determined by
357 retrieves information; article number, overview data, or arrival time.
359 should be called with NULL handle when it is the first time;
362 calls should use the handle returned by the previous call to
365 returns true, unless it reaches high which is specified by
367 Retrieved overview data are sorted by article number, and
369 is ``0'' if there is no overview data for article. Note that the
370 retrieved data is not neccessarily null-terminated; you should only rely
373 octets of overview data being present.
376 frees all resources which have been allocated by
380 retrieves overview data and token specified with
384 expires overview data for the newsgroup.
386 checks the existense of the article and purges overview data if the
387 article no longer exists.
388 If ``groupbaseexpiry'' in
392 also expires articles.
395 frees all resources which are used by the overview method.
397 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
399 This is revision \\$3, dated \\$4.
401 .R$ $Id: libstorage.3 6124 2003-01-14 06:03:29Z rra $
~ian / inn-innduct.git / blob