1ESTNODE(3)                      Hyper Estraier                      ESTNODE(3)
2
3
4

NAME

6       estnode.h - the node API of Hyper Estraier
7
8

SYNOPSIS

10       #include <estraier.h>
11       #include <estnode.h>
12       #include <cabin.h>
13       #include <stdlib.h>
14
15

API FOR INITIALIZING

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
21       The function `est_init_net_env' is used in order to initialize the net‐
22       working environment.
23
24       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
29       The function `est_free_net_env' is used in order to free the networking
30       environment.
31
32       void est_free_net_env(void);
33              There is no parameter and no return value.
34
35

API FOR NODES

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
45       The  function  `est_node_new' is used in order to create a node connec‐
46       tion object.
47
48       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
52       The  function `est_node_delete' is used in order to destroy a node con‐
53       nection object.
54
55       void est_node_delete(ESTNODE *node);
56              `node' specifies a node connection object.
57
58       The function `est_node_set_proxy' is used in order  to  set  the  proxy
59       information of a node connection object.
60
61       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
66       The  function `est_node_set_timeout' is used in order to set timeout of
67       a connection.
68
69       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
73       The  function `est_node_set_auth' is used in order to set the authenti‐
74       cation information of a node connection object.
75
76       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
82       The  function `est_node_status' is used in order to get the status code
83       of the last request of a node.
84
85       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
90       The function `est_node_sync' is used in order to  synchronize  updating
91       contents of the database of a node.
92
93       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
97       The function `est_node_optimize' is used in order to optimize the data‐
98       base of a node.
99
100       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
104       The function `est_node_put_doc' is used in order to add a document to a
105       node.
106
107       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
114       The  function  `est_node_out_doc' is used in order to remove a document
115       from a node.
116
117       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
122       The function `est_node_out_doc_by_uri' is used in  order  to  remove  a
123       document specified by URI from a node.
124
125       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
130       The function `est_node_edit_doc' is used in order to edit attributes of
131       a document in a node.
132
133       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
140       The function `est_node_get_doc' is used in order to retrieve a document
141       in a node.
142
143       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
149       The function `est_node_get_doc_by_uri' is used in order to  retrieve  a
150       document specified by URI in a node.
151
152       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
158       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
161       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
169       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
173       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
182       The function `est_node_etch_doc' is used in order to  extract  keywords
183       of a document.
184
185       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
193       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
196       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
204       The function `est_node_uri_to_id' is used in order to get the ID  of  a
205       document specified by URI.
206
207       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
212       The  function  `est_node_name'  is  used  in order to get the name of a
213       node.
214
215       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
221       The  function  `est_node_label'  is used in order to get the label of a
222       node.
223
224       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
230       The  function  `est_node_doc_num' is used in order to get the number of
231       documents in a node.
232
233       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
237       The  function `est_node_word_num' is used in order to get the number of
238       unique words in a node.
239
240       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
245       The function `est_node_size' is used in order to get the  size  of  the
246       database of a node.
247
248       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
253       The  function  `est_node_cache_usage' is used in order to get the usage
254       ratio of the cache of a node.
255
256       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
261       The function `est_node_admins' is used in order to get a list of  names
262       of administrators of a node.
263
264       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
270       The function `est_node_users' is used in order to get a list  of  names
271       of users of a node.
272
273       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
279       The function `est_node_links' is used in order to get a list of expres‐
280       sions of links of a node.
281
282       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
289       The  function  `est_node_search'  is used in order to search a node for
290       documents corresponding a condition.
291
292       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
299       The function `est_node_set_snippet_width' is used in order to set width
300       of snippet in the result from a node.
301
302       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
314       The function `est_node_set_user' is used in  order  to  manage  a  user
315       account of a node.
316
317       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
324       The function `est_node_set_link' is used in order to manage a link of a
325       node.
326
327       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
335

API FOR SEARCH RESULTS OF NODES

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
346       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
354       The function `est_noderes_delete' is used in order  to  delete  a  node
355       result object.
356
357       void est_noderes_delete(ESTNODERES *nres);
358              `nres' specifies a node result object.
359
360       The  function  `est_noderes_hints' is used in order to get a map object
361       for hints of a node result object.
362
363       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
370       The function `est_noderes_eclipse' is used in order to eclipse  similar
371       documents of a node result object.
372
373       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
379       The function `est_noderes_doc_num' is used in order to get  the  number
380       of documents in a node result object.
381
382       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
386       The function `est_noderes_get_doc' is used in order to refer  a  result
387       document object in a node result object.
388
389       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
396       The  function  `est_resdoc_uri'  is  used  in order to get the URI of a
397       result document object.
398
399       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
405       The  function `est_resdoc_attr_names' is used in order to get a list of
406       attribute names of a result document object.
407
408       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
415       The function `est_resdoc_attr' is used in order to get the value of  an
416       attribute of a result document object.
417
418       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
425       The  function  `est_resdoc_snippet' is used in order to get the snippet
426       of a result document object.
427
428       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
438       The  function `est_resdoc_keywords' is used in order to get keywords of
439       a result document object.
440
441       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
448       The function `est_resdoc_shadows' is used in order to get an  array  of
449       documents eclipsed by a result document object.
450
451       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
459       The function `est_resdoc_similarity' is used in order to get similarity
460       of an eclipsed result document object.
461
462       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
467

PARALLELING

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
474

AUTHOR

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
480

ACKNOWLEDGEMENTS

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
486
488       Copyright (C) 2004-2007 Mikio Hirabayashi
489
490       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
495       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
500       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
505

SEE ALSO

507       estconfig(1),   estcmd(1),   estmaster(1),   estcall(1),   estwaver(1),
508       cabin(3), estraier(3)
509
510       Please  see   http://hyperestraier.sourceforge.net/nguide-en.html   for
511       detail.
512
513
514
515Man Page                          2007-03-06                        ESTNODE(3)
Impressum