1ESTNODE(3) Hyper Estraier ESTNODE(3)
2
6 estnode.h - the node API of Hyper Estraier
7
10 #include <estraier.h>
11 #include <estnode.h>
12 #include <cabin.h>
13 #include <stdlib.h>
14
17 For preparation to use the node API, initialize the network environment
18 at the beginning of a program. Moreover, the environment should be
19 freed at the end of the program.
20 The function `est_init_net_env' is used in order to initialize the net‐
22 working environment.
23 int est_init_net_env(void);
25 The return value is true if success, else it is false. As it is
26 allowable to call this function multiple times, it is needed to
27 call the function `est_free_net_env' at the same frequency.
28 The function `est_free_net_env' is used in order to free the networking
30 environment.
31 void est_free_net_env(void);
33 There is no parameter and no return value.
34
37 The type of the structure `ESTNODE' is for abstraction of connection to
38 a node. A node has its own URL. No entity of `ESTNODE' is accessed
39 directly, but it is accessed by the pointer. The term of node connec‐
40 tion object means the pointer and its referent. A node connection
41 object is created by the function `est_node_new' and destroyed by
42 `est_node_delete'. Every created node connection object should be
43 destroyed.
44 The function `est_node_new' is used in order to create a node connec‐
46 tion object.
47 ESTNODE *est_node_new(const char *url);
49 `url' specifies the URL of a node. The return value is a node
50 connection object.
51 The function `est_node_delete' is used in order to destroy a node con‐
53 nection object.
54 void est_node_delete(ESTNODE *node);
56 `node' specifies a node connection object.
57 The function `est_node_set_proxy' is used in order to set the proxy
59 information of a node connection object.
60 void est_node_set_proxy(ESTNODE *node, const char *host, int port);
62 `node' specifies a node connection object. `host' specifies the
63 host name of a proxy server. `port' specifies the port number
64 of the proxy server.
65 The function `est_node_set_timeout' is used in order to set timeout of
67 a connection.
68 void est_node_set_timeout(ESTNODE *node, int sec);
70 `node' specifies a node connection object. `sec' specifies
71 timeout of the connection in seconds.
72 The function `est_node_set_auth' is used in order to set the authenti‐
74 cation information of a node connection object.
75 void est_node_set_auth(ESTNODE *node, const char *name, const char
77 *passwd);
78 `node' specifies a node connection object. `name' specifies the
79 name of authentication. `passwd' specifies the password of the
80 authentication.
81 The function `est_node_status' is used in order to get the status code
83 of the last request of a node.
84 int est_node_status(ESTNODE *node);
86 `node' specifies a node connection object. The return value is
87 the status code of the last request of the node. -1 means fail‐
88 ure of connection.
89 The function `est_node_sync' is used in order to synchronize updating
91 contents of the database of a node.
92 int est_node_sync(ESTNODE *node);
94 `node' specifies a node connection object. The return value is
95 true if success, else it is false.
96 The function `est_node_optimize' is used in order to optimize the data‐
98 base of a node.
99 int est_node_optimize(ESTNODE *node);
101 `node' specifies a node connection object. The return value is
102 true if success, else it is false.
103 The function `est_node_put_doc' is used in order to add a document to a
105 node.
106 int est_node_put_doc(ESTNODE *node, ESTDOC *doc);
108 `node' specifies a node connection object. `doc' specifies a
109 document object. The document object should have the URI
110 attribute. The return value is true if success, else it is
111 false. If the URI attribute is same with an existing document
112 in the node, the existing one is deleted.
113 The function `est_node_out_doc' is used in order to remove a document
115 from a node.
116 int est_node_out_doc(ESTNODE *node, int id);
118 `node' specifies a node connection object. `id' specifies the
119 ID number of a registered document. The return value is true if
120 success, else it is false.
121 The function `est_node_out_doc_by_uri' is used in order to remove a
123 document specified by URI from a node.
124 int est_node_out_doc_by_uri(ESTNODE *node, const char *uri);
126 `node' specifies a node connection object. `uri' specifies the
127 URI of a registered document. The return value is true if suc‐
128 cess, else it is false.
129 The function `est_node_edit_doc' is used in order to edit attributes of
131 a document in a node.
132 int est_node_edit_doc(ESTNODE *node, ESTDOC *doc);
134 `node' specifies a node connection object. `doc' specifies a
135 document object. The return value is true if success, else it
136 is false. The ID can not be changed. If the URI is changed and
137 it overlaps the URI of another registered document, this func‐
138 tion fails.
139 The function `est_node_get_doc' is used in order to retrieve a document
141 in a node.
142 ESTDOC *est_node_get_doc(ESTNODE *node, int id);
144 `node' specifies a node connection object. `id' specifies the
145 ID number of a registered document. The return value is a docu‐
146 ment object. It should be deleted with `est_doc_delete' if it
147 is no longer in use. On error, `NULL' is returned.
148 The function `est_node_get_doc_by_uri' is used in order to retrieve a
150 document specified by URI in a node.
151 ESTDOC *est_node_get_doc_by_uri(ESTNODE *node, const char *uri);
153 `node' specifies a node connection object. `uri' specifies the
154 URI of a registered document. The return value is a document
155 object. It should be deleted with `est_doc_delete' if it is no
156 longer in use. On error, `NULL' is returned.
157 The function `est_node_get_doc_attr' is used in order to retrieve the
159 value of an attribute of a document in a node.
160 char *est_node_get_doc_attr(ESTNODE *node, int id, const char *name);
162 `node' specifies a node connection object. `id' specifies the
163 ID number of a registered document. `name' specifies the name
164 of an attribute. The return value is the value of the attribute
165 or `NULL' if it does not exist. Because the region of the
166 return value is allocated with the `malloc' call, it should be
167 released with the `free' call if it is no longer in use.
168 The function `est_node_get_doc_attr_by_uri' is used in order to
170 retrieve the value of an attribute of a document specified by URI in a
171 node.
172 char *est_node_get_doc_attr_by_uri(ESTNODE *node, const char *uri,
174 const char *name);
175 `node' specifies a node connection object. `uri' specifies the
176 URI of a registered document. `name' specifies the name of an
177 attribute. The return value is the value of the attribute or
178 `NULL' if it does not exist. Because the region of the return
179 value is allocated with the `malloc' call, it should be released
180 with the `free' call if it is no longer in use.
181 The function `est_node_etch_doc' is used in order to extract keywords
183 of a document.
184 CBMAP *est_node_etch_doc(ESTNODE *node, int id);
186 `node' specifies a node connection object. `id' specifies the
187 ID number of a registered document. The return value is a new
188 map object of keywords and their scores in decimal string or
189 `NULL' on error. Because the object of the return value is
190 opened with the function `cbmapopen', it should be closed with
191 the function `cbmapclose' if it is no longer in use.
192 The function `est_node_etch_doc_by_uri' is used in order to extract
194 keywords of a document specified by URI in a node.
195 CBMAP *est_node_etch_doc_by_uri(ESTNODE *node, const char *uri);
197 `node' specifies a node connection object. `uri' specifies the
198 URI of a registered document. The return value is a new map
199 object of keywords and their scores in decimal string or `NULL'
200 on error. Because the object of the return value is opened with
201 the function `cbmapopen', it should be closed with the function
202 `cbmapclose' if it is no longer in use.
203 The function `est_node_uri_to_id' is used in order to get the ID of a
205 document specified by URI.
206 int est_node_uri_to_id(ESTNODE *node, const char *uri);
208 `node' specifies a node connection object. `uri' specifies the
209 URI of a registered document. The return value is the ID of the
210 document. On error, -1 is returned.
211 The function `est_node_name' is used in order to get the name of a
213 node.
214 const char *est_node_name(ESTNODE *node);
216 `node' specifies a node connection object. The return value is
217 the name of the node. On error, `NULL' is returned. The life
218 duration of the returned string is synchronous with the one of
219 the node object.
220 The function `est_node_label' is used in order to get the label of a
222 node.
223 const char *est_node_label(ESTNODE *node);
225 `node' specifies a node connection object. The return value is
226 the label of the node. On error, `NULL' is returned. The life
227 duration of the returned string is synchronous with the one of
228 the node object.
229 The function `est_node_doc_num' is used in order to get the number of
231 documents in a node.
232 int est_node_doc_num(ESTNODE *node);
234 `node' specifies a node connection object. The return value is
235 the number of documents in the node. On error, -1 is returned.
236 The function `est_node_word_num' is used in order to get the number of
238 unique words in a node.
239 int est_node_word_num(ESTNODE *node);
241 `node' specifies a node connection object. The return value is
242 the number of unique words in the node. On error, -1 is
243 returned.
244 The function `est_node_size' is used in order to get the size of the
246 database of a node.
247 double est_node_size(ESTNODE *node);
249 `node' specifies a node connection object. The return value is
250 the size of the database of the node. On error, -1.0 is
251 returned.
252 The function `est_node_cache_usage' is used in order to get the usage
254 ratio of the cache of a node.
255 double est_node_cache_usage(ESTNODE *node);
257 `node' specifies a node connection object. The return value is
258 the usage ratio of the cache of the node. On error, -1.0 is
259 returned.
260 The function `est_node_admins' is used in order to get a list of names
262 of administrators of a node.
263 const CBLIST *est_node_admins(ESTNODE *node);
265 `node' specifies a node connection object. The return value is
266 a list object of names of administrators. On error, `NULL' is
267 returned. The life duration of the returned object is synchro‐
268 nous with the one of the node object.
269 The function `est_node_users' is used in order to get a list of names
271 of users of a node.
272 const CBLIST *est_node_users(ESTNODE *node);
274 `node' specifies a node connection object. The return value is
275 a list object of names of users. On error, `NULL' is returned.
276 The life duration of the returned object is synchronous with the
277 one of the node object.
278 The function `est_node_links' is used in order to get a list of expres‐
280 sions of links of a node.
281 const CBLIST *est_node_links(ESTNODE *node);
283 `node' specifies a node connection object. The return value is
284 a list object of expressions of links. Each element is a TSV
285 string and has three fields of the URL, the label, and the
286 score. On error, `NULL' is returned. The life duration of the
287 returned object is synchronous with the one of the node object.
288 The function `est_node_search' is used in order to search a node for
290 documents corresponding a condition.
291 ESTNODERES *est_node_search(ESTNODE *node, ESTCOND *cond, int depth);
293 `node' specifies a node connection object. `cond' specifies a
294 condition object. `depth' specifies the depth of meta search.
295 The return value is a node result object. It should be deleted
296 with `est_noderes_delete' if it is no longer in use. On error,
297 `NULL' is returned.
298 The function `est_node_set_snippet_width' is used in order to set width
300 of snippet in the result from a node.
301 void est_node_set_snippet_width(ESTNODE *node, int wwidth, int hwidth,
303 int awidth);
304 `node' specifies a node connection object. `wwidth' specifies
305 whole width of a snippet. By default, it is 480. If it is 0,
306 no snippet is sent. If it is negative, whole body text is sent
307 instead of snippet. `hwidth' specifies width of strings picked
308 up from the beginning of the text. By default, it is 96. If it
309 is negative 0, the current setting is not changed. `awidth'
310 specifies width of strings picked up around each highlighted
311 word. By default, it is 96. If it is negative, the current set‐
312 ting is not changed.
313 The function `est_node_set_user' is used in order to manage a user
315 account of a node.
316 int est_node_set_user(ESTNODE *node, const char *name, int mode);
318 `node' specifies a node connection object. `name' specifies the
319 name of a user. `mode' specifies the operation mode. 0 means
320 to delete the account. 1 means to set the account as an admin‐
321 istrator. 2 means to set the account as a guest. The return
322 value is true if success, else it is false.
323 The function `est_node_set_link' is used in order to manage a link of a
325 node.
326 int est_node_set_link(ESTNODE *node, const char *url, const char
328 *label, int credit);
329 `node' specifies a node connection object. `url' specifies the
330 URL of the target node of a link. `label' specifies the label
331 of the link. `credit' specifies the credit of the link. If it
332 is negative, the link is removed. The return value is true if
333 success, else it is false.
334
337 The type of the structure `ESTNODERES' is for abstraction of search
338 result from a node. A result is composed of a list of corresponding
339 documents and information of hints. No entity of `ESTNODERES' is
340 accessed directly, but it is accessed by the pointer. The term of node
341 result object means the pointer and its referent. A node result object
342 is created by the function `est_node_search' and destroyed by
343 `est_noderes_delete'. Every created node connection object should be
344 destroyed.
345 The type of the structure `ESTRESDOC' is for abstraction of a document
347 in search result. A result document is composed of some attributes and
348 a snippet. No entity of `ESTRESDOC' is accessed directly, but it is
349 accessed by the pointer. The term of result document object means the
350 pointer and its referent. A result document object is gotten by the
351 function `est_noderes_get_doc' but it should not be destroyed because
352 the entity is managed inside the node result object.
353 The function `est_noderes_delete' is used in order to delete a node
355 result object.
356 void est_noderes_delete(ESTNODERES *nres);
358 `nres' specifies a node result object.
359 The function `est_noderes_hints' is used in order to get a map object
361 for hints of a node result object.
362 CBMAP *est_noderes_hints(ESTNODERES *nres);
364 `nres' specifies a node result object. The return value is a
365 map object for hints. Keys of the map are "VERSION", "NODE",
366 "HIT", "HINT#n", "DOCNUM", "WORDNUM", "TIME", "TIME#n",
367 "LINK#n", and "VIEW". The life duration of the returned object
368 is synchronous with the one of the node result object.
369 The function `est_noderes_eclipse' is used in order to eclipse similar
371 documents of a node result object.
372 void est_noderes_eclipse(ESTNODERES *nres, int num, double limit);
374 `nres' specifies a node result object. `num' specifies the num‐
375 ber of documents to be shown. If it is not more than 0, eclipse
376 is undone. `limit' specifies the lower limit of similarity for
377 documents to be eclipsed. Similarity is between 0.0 and 1.0.
378 The function `est_noderes_doc_num' is used in order to get the number
380 of documents in a node result object.
381 int est_noderes_doc_num(ESTNODERES *nres);
383 `nres' specifies a node result object. The return value is the
384 number of documents in a node result object.
385 The function `est_noderes_get_doc' is used in order to refer a result
387 document object in a node result object.
388 ESTRESDOC *est_noderes_get_doc(ESTNODERES *nres, int index);
390 `nres' specifies a node result object. `index' specifies the
391 index of a document. The return value is a result document
392 object or `NULL' if `index' is equal to or more than the number
393 of documents. The life duration of the returned object is syn‐
394 chronous with the one of the node result object.
395 The function `est_resdoc_uri' is used in order to get the URI of a
397 result document object.
398 const char *est_resdoc_uri(ESTRESDOC *rdoc);
400 `rdoc' specifies a result document object. The return value is
401 the URI of the result document object. The life duration of the
402 returned string is synchronous with the one of the result docu‐
403 ment object.
404 The function `est_resdoc_attr_names' is used in order to get a list of
406 attribute names of a result document object.
407 CBLIST *est_resdoc_attr_names(ESTRESDOC *rdoc);
409 `rdoc' specifies a result document object. The return value is
410 a new list object of attribute names of the result document
411 object. Because the object of the return value is opened with
412 the function `cblistopen', it should be closed with the function
413 `cblistclose' if it is no longer in use.
414 The function `est_resdoc_attr' is used in order to get the value of an
416 attribute of a result document object.
417 const char *est_resdoc_attr(ESTRESDOC *rdoc, const char *name);
419 `rdoc' specifies a result document object. `name' specifies the
420 name of an attribute. The return value is the value of the
421 attribute or `NULL' if it does not exist. The life duration of
422 the returned string is synchronous with the one of the result
423 document object.
424 The function `est_resdoc_snippet' is used in order to get the snippet
426 of a result document object.
427 const char *est_resdoc_snippet(ESTRESDOC *rdoc);
429 `rdoc' specifies a result document object. The return value is
430 a string of the snippet of the result document object. There
431 are tab separated values. Each line is a string to be shown.
432 Though most lines have only one field, some lines have two
433 fields. If the second field exists, the first field is to be
434 shown with highlighted, and the second field means its normal‐
435 ized form. The life duration of the returned string is synchro‐
436 nous with the one of the result document object.
437 The function `est_resdoc_keywords' is used in order to get keywords of
439 a result document object.
440 const char *est_resdoc_keywords(ESTRESDOC *rdoc);
442 `rdoc' specifies a result document object. The return value is
443 a string of serialized keywords of the result document object.
444 There are tab separated values. Keywords and their scores come
445 alternately. The life duration of the returned string is syn‐
446 chronous with the one of the result document object.
447 The function `est_resdoc_shadows' is used in order to get an array of
449 documents eclipsed by a result document object.
450 ESTRESDOC **est_resdoc_shadows(ESTRESDOC *rdoc, int *np);
452 `rdoc' specifies a result document object. `np' specifies the
453 pointer to a variable to which the number of elements of the
454 return value is assigned. The return value is an array of
455 eclipsed result document objects. The life duration of the
456 returned array and its elements is synchronous with the one of
457 the result document object.
458 The function `est_resdoc_similarity' is used in order to get similarity
460 of an eclipsed result document object.
461 double est_resdoc_similarity(ESTRESDOC *rdoc);
463 `rdoc' specifies a result document object. The return value is
464 similarity of the result document object to the front document
465 or -1.0 if it is not eclipsed.
466
469 Each of node connection objects, node result objects, and result docu‐
470 ment objects can not be shared by threads. If you use multi threads,
471 make each thread have its own objects. If the precondition is kept,
472 functions of the node API can be treated as thread-safe functions.
473
476 Hyper Estraier is written by Mikio Hirabayashi. You can contact the
477 author by e-mail to <mikio@users.sourceforge.net>. Any suggestion or
478 bug report is welcome to the author.
479
482 Hyper Estraier was developed under management by Fumitoshi Ukai and
483 supports by Exploratory Software Project of Information-technology Pro‐
484 motion Agency, Japan (IPA).
485
488 Copyright (C) 2004-2007 Mikio Hirabayashi
489 Hyper Estraier is free software; you can redistribute it and/or modify
491 it under the terms of the GNU Lesser General Public License as pub‐
492 lished by the Free Software Foundation; either version 2 of the
493 License, or any later version.
494 Hyper Estraier is distributed in the hope that it will be useful, but
496 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
497 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
498 General Public License for more details.
499 You should have received a copy of the GNU Lesser General Public
501 License along with Hyper Estraier; if not, write to the Free Software
502 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
503 USA.
504
507 estconfig(1), estcmd(1), estmaster(1), estcall(1), estwaver(1),
508 cabin(3), estraier(3)
509 Please see http://hyperestraier.sourceforge.net/nguide-en.html for
511 detail.
512Man Page 2007-03-06 ESTNODE(3)