Provided by: libestraier-dev_1.4.13-14ubuntu2_amd64 bug

NAME

       estnode.h - the node API of Hyper Estraier

SYNOPSIS

       #include <estraier.h>
       #include <estnode.h>
       #include <cabin.h>
       #include <stdlib.h>

API FOR INITIALIZING

       For  preparation  to use the node API, initialize the network environment at the beginning
       of a program.  Moreover, the environment should be freed at the end of the program.

       The function `est_init_net_env' is used in order to initialize the networking environment.

       int est_init_net_env(void);
              The return value is true if success, else it is false.  As it is allowable to  call
              this  function multiple times, it is needed to call the function `est_free_net_env'
              at the same frequency.

       The function `est_free_net_env' is used in order to free the networking environment.

       void est_free_net_env(void);
              There is no parameter and no return value.

API FOR NODES

       The type of the structure `ESTNODE' is for abstraction of connection to a  node.   A  node
       has  its  own URL.  No entity of `ESTNODE' is accessed directly, but it is accessed by the
       pointer.  The term of node connection object means the pointer and its referent.   A  node
       connection   object   is   created   by  the  function  `est_node_new'  and  destroyed  by
       `est_node_delete'.  Every created node connection object should be destroyed.

       The function `est_node_new' is used in order to create a node connection object.

       ESTNODE *est_node_new(const char *url);
              `url' specifies the URL of a node.  The return value is a node connection object.

       The function `est_node_delete' is used in order to destroy a node connection object.

       void est_node_delete(ESTNODE *node);
              `node' specifies a node connection object.

       The function `est_node_set_proxy' is used in order to set the proxy information of a  node
       connection object.

       void est_node_set_proxy(ESTNODE *node, const char *host, int port);
              `node'  specifies  a  node  connection object.  `host' specifies the host name of a
              proxy server.  `port' specifies the port number of the proxy server.

       The function `est_node_set_timeout' is used in order to set timeout of a connection.

       void est_node_set_timeout(ESTNODE *node, int sec);
              `node' specifies  a  node  connection  object.   `sec'  specifies  timeout  of  the
              connection in seconds.

       The function `est_node_set_auth' is used in order to set the authentication information of
       a node connection object.

       void est_node_set_auth(ESTNODE *node, const char *name, const char *passwd);
              `node'  specifies  a  node  connection  object.   `name'  specifies  the  name   of
              authentication.  `passwd' specifies the password of the authentication.

       The function `est_node_status' is used in order to get the status code of the last request
       of a node.

       int est_node_status(ESTNODE *node);
              `node' specifies a node connection object.  The return value is the status code  of
              the last request of the node.  -1 means failure of connection.

       The  function  `est_node_sync'  is  used  in order to synchronize updating contents of the
       database of a node.

       int est_node_sync(ESTNODE *node);
              `node' specifies a node connection object.  The return value is  true  if  success,
              else it is false.

       The function `est_node_optimize' is used in order to optimize the database of a node.

       int est_node_optimize(ESTNODE *node);
              `node'  specifies  a  node connection object.  The return value is true if success,
              else it is false.

       The function `est_node_put_doc' is used in order to add a document to a node.

       int est_node_put_doc(ESTNODE *node, ESTDOC *doc);
              `node' specifies a node connection object.  `doc' specifies a document object.  The
              document  object  should  have  the  URI  attribute.   The  return value is true if
              success, else it is false.  If the URI attribute is same with an existing  document
              in the node, the existing one is deleted.

       The function `est_node_out_doc' is used in order to remove a document from a node.

       int est_node_out_doc(ESTNODE *node, int id);
              `node'  specifies  a  node  connection  object.   `id' specifies the ID number of a
              registered document.  The return value is true if success, else it is false.

       The function `est_node_out_doc_by_uri' is used in order to remove a document specified  by
       URI from a node.

       int est_node_out_doc_by_uri(ESTNODE *node, const char *uri);
              `node' specifies a node connection object.  `uri' specifies the URI of a registered
              document.  The return value is true if success, else it is false.

       The function `est_node_edit_doc' is used in order to edit attributes of a  document  in  a
       node.

       int est_node_edit_doc(ESTNODE *node, ESTDOC *doc);
              `node' specifies a node connection object.  `doc' specifies a document object.  The
              return value is true if success, else it is false.  The ID can not be changed.   If
              the  URI  is  changed  and it overlaps the URI of another registered document, this
              function fails.

       The function `est_node_get_doc' is used in order to retrieve a document in a node.

       ESTDOC *est_node_get_doc(ESTNODE *node, int id);
              `node' specifies a node connection object.  `id'  specifies  the  ID  number  of  a
              registered  document.  The return value is a document object.  It should be deleted
              with `est_doc_delete' if it is no longer in use.  On error, `NULL' is returned.

       The function `est_node_get_doc_by_uri' is used in order to retrieve a  document  specified
       by URI in a node.

       ESTDOC *est_node_get_doc_by_uri(ESTNODE *node, const char *uri);
              `node' specifies a node connection object.  `uri' specifies the URI of a registered
              document.  The return value is a  document  object.   It  should  be  deleted  with
              `est_doc_delete' if it is no longer in use.  On error, `NULL' is returned.

       The  function  `est_node_get_doc_attr'  is  used  in  order  to  retrieve  the value of an
       attribute of a document in a node.

       char *est_node_get_doc_attr(ESTNODE *node, int id, const char *name);
              `node' specifies a node connection object.  `id'  specifies  the  ID  number  of  a
              registered  document.  `name' specifies the name of an attribute.  The return value
              is the value of the attribute or `NULL' if it does not exist.  Because  the  region
              of the return value is allocated with the `malloc' call, it should be released with
              the `free' call if it is no longer in use.

       The function `est_node_get_doc_attr_by_uri' is used in order to retrieve the value  of  an
       attribute of a document specified by URI in a node.

       char *est_node_get_doc_attr_by_uri(ESTNODE *node, const char *uri, const char *name);
              `node' specifies a node connection object.  `uri' specifies the URI of a registered
              document.  `name' specifies the name of an attribute.   The  return  value  is  the
              value  of  the attribute or `NULL' if it does not exist.  Because the region of the
              return value is allocated with the `malloc' call, it should be  released  with  the
              `free' call if it is no longer in use.

       The function `est_node_etch_doc' is used in order to extract keywords of a document.

       CBMAP *est_node_etch_doc(ESTNODE *node, int id);
              `node'  specifies  a  node  connection  object.   `id' specifies the ID number of a
              registered document.  The return value is a new map object of  keywords  and  their
              scores  in  decimal  string  or  `NULL' on error.  Because the object of the return
              value is opened with the  function  `cbmapopen',  it  should  be  closed  with  the
              function `cbmapclose' if it is no longer in use.

       The function `est_node_etch_doc_by_uri' is used in order to extract keywords of a document
       specified by URI in a node.

       CBMAP *est_node_etch_doc_by_uri(ESTNODE *node, const char *uri);
              `node' specifies a node connection object.  `uri' specifies the URI of a registered
              document.   The  return  value  is a new map object of keywords and their scores in
              decimal string or `NULL' on error.  Because the  object  of  the  return  value  is
              opened  with  the  function  `cbmapopen',  it  should  be  closed with the function
              `cbmapclose' if it is no longer in use.

       The function `est_node_uri_to_id' is used in order to get the ID of a  document  specified
       by URI.

       int est_node_uri_to_id(ESTNODE *node, const char *uri);
              `node' specifies a node connection object.  `uri' specifies the URI of a registered
              document.  The return value is the ID of the document.  On error, -1 is returned.

       The function `est_node_name' is used in order to get the name of a node.

       const char *est_node_name(ESTNODE *node);
              `node' specifies a node connection object.  The return value is  the  name  of  the
              node.   On  error, `NULL' is returned.  The life duration of the returned string is
              synchronous with the one of the node object.

       The function `est_node_label' is used in order to get the label of a node.

       const char *est_node_label(ESTNODE *node);
              `node' specifies a node connection object.  The return value is the  label  of  the
              node.   On  error, `NULL' is returned.  The life duration of the returned string is
              synchronous with the one of the node object.

       The function `est_node_doc_num' is used in order to get the number of documents in a node.

       int est_node_doc_num(ESTNODE *node);
              `node' specifies a node connection object.  The  return  value  is  the  number  of
              documents in the node.  On error, -1 is returned.

       The  function  `est_node_word_num' is used in order to get the number of unique words in a
       node.

       int est_node_word_num(ESTNODE *node);
              `node' specifies a node connection object.  The  return  value  is  the  number  of
              unique words in the node.  On error, -1 is returned.

       The function `est_node_size' is used in order to get the size of the database of a node.

       double est_node_size(ESTNODE *node);
              `node'  specifies  a  node  connection object.  The return value is the size of the
              database of the node.  On error, -1.0 is returned.

       The function `est_node_cache_usage' is used in order to get the usage ratio of  the  cache
       of a node.

       double est_node_cache_usage(ESTNODE *node);
              `node'  specifies a node connection object.  The return value is the usage ratio of
              the cache of the node.  On error, -1.0 is returned.

       The function `est_node_admins' is used in order to get a list of names  of  administrators
       of a node.

       const CBLIST *est_node_admins(ESTNODE *node);
              `node'  specifies  a  node connection object.  The return value is a list object of
              names of administrators.  On error, `NULL' is returned.  The life duration  of  the
              returned object is synchronous with the one of the node object.

       The function `est_node_users' is used in order to get a list of names of users of a node.

       const CBLIST *est_node_users(ESTNODE *node);
              `node'  specifies  a  node connection object.  The return value is a list object of
              names of users.  On error, `NULL' is returned.  The life duration of  the  returned
              object is synchronous with the one of the node object.

       The  function `est_node_links' is used in order to get a list of expressions of links of a
       node.

       const CBLIST *est_node_links(ESTNODE *node);
              `node' specifies a node connection object.  The return value is a  list  object  of
              expressions  of  links.   Each  element is a TSV string and has three fields of the
              URL, the label, and the score.  On error, `NULL' is returned.  The life duration of
              the returned object is synchronous with the one of the node object.

       The  function  `est_node_search'  is  used  in  order  to  search  a  node  for  documents
       corresponding a condition.

       ESTNODERES *est_node_search(ESTNODE *node, ESTCOND *cond, int depth);
              `node' specifies a node connection object.  `cond' specifies  a  condition  object.
              `depth'  specifies  the  depth  of  meta search.  The return value is a node result
              object.  It should be deleted with `est_noderes_delete' if it is no longer in  use.
              On error, `NULL' is returned.

       The  function `est_node_set_snippet_width' is used in order to set width of snippet in the
       result from a node.

       void est_node_set_snippet_width(ESTNODE *node, int wwidth, int hwidth, int awidth);
              `node' specifies a node connection object.  `wwidth' specifies  whole  width  of  a
              snippet.   By  default,  it  is  480.   If  it  is  0, no snippet is sent. If it is
              negative, whole body text is sent instead of snippet.  `hwidth' specifies width  of
              strings  picked up from the beginning of the text.  By default, it is 96.  If it is
              negative 0, the current setting  is  not  changed.   `awidth'  specifies  width  of
              strings  picked  up  around  each highlighted word. By default, it is 96.  If it is
              negative, the current setting is not changed.

       The function `est_node_set_user' is used in order to manage a user account of a node.

       int est_node_set_user(ESTNODE *node, const char *name, int mode);
              `node' specifies a node connection object.  `name' specifies the name  of  a  user.
              `mode'  specifies  the  operation mode.  0 means to delete the account.  1 means to
              set the account as an administrator.  2 means to set the account as a  guest.   The
              return value is true if success, else it is false.

       The function `est_node_set_link' is used in order to manage a link of a node.

       int est_node_set_link(ESTNODE *node, const char *url, const char *label, int credit);
              `node'  specifies  a node connection object.  `url' specifies the URL of the target
              node of a link.  `label' specifies the label of the link.  `credit'  specifies  the
              credit  of  the link.  If it is negative, the link is removed.  The return value is
              true if success, else it is false.

API FOR SEARCH RESULTS OF NODES

       The type of the structure `ESTNODERES' is for abstraction of search result from a node.  A
       result  is  composed  of  a  list of corresponding documents and information of hints.  No
       entity of `ESTNODERES' is accessed directly, but it is accessed by the pointer.  The  term
       of node result object means the pointer and its referent.  A node result object is created
       by the function `est_node_search' and destroyed by  `est_noderes_delete'.   Every  created
       node connection object should be destroyed.

       The  type  of the structure `ESTRESDOC' is for abstraction of a document in search result.
       A result document is composed of some attributes and a snippet.  No entity of  `ESTRESDOC'
       is  accessed  directly,  but  it  is accessed by the pointer.  The term of result document
       object means the pointer and its referent.  A result document  object  is  gotten  by  the
       function  `est_noderes_get_doc'  but  it  should  not  be  destroyed because the entity is
       managed inside the node result object.

       The function `est_noderes_delete' is used in order to delete a node result object.

       void est_noderes_delete(ESTNODERES *nres);
              `nres' specifies a node result object.

       The function `est_noderes_hints' is used in order to get a map object for hints of a  node
       result object.

       CBMAP *est_noderes_hints(ESTNODERES *nres);
              `nres' specifies a node result object.  The return value is a map object for hints.
              Keys of the map  are  "VERSION",  "NODE",  "HIT",  "HINT#n",  "DOCNUM",  "WORDNUM",
              "TIME",  "TIME#n",  "LINK#n", and "VIEW".  The life duration of the returned object
              is synchronous with the one of the node result object.

       The function `est_noderes_eclipse' is used in order to eclipse similar documents of a node
       result object.

       void est_noderes_eclipse(ESTNODERES *nres, int num, double limit);
              `nres'  specifies a node result object.  `num' specifies the number of documents to
              be shown.  If it is not more than 0, eclipse  is  undone.   `limit'  specifies  the
              lower  limit of similarity for documents to be eclipsed.  Similarity is between 0.0
              and 1.0.

       The function `est_noderes_doc_num' is used in order to get the number of  documents  in  a
       node result object.

       int est_noderes_doc_num(ESTNODERES *nres);
              `nres' specifies a node result object.  The return value is the number of documents
              in a node result object.

       The function `est_noderes_get_doc' is used in order to refer a result document object in a
       node result object.

       ESTRESDOC *est_noderes_get_doc(ESTNODERES *nres, int index);
              `nres'  specifies a node result object.  `index' specifies the index of a document.
              The return value is a result document object or `NULL' if `index' is  equal  to  or
              more  than  the  number  of documents.  The life duration of the returned object is
              synchronous with the one of the node result object.

       The function `est_resdoc_uri' is used in order to get the URI of a result document object.

       const char *est_resdoc_uri(ESTRESDOC *rdoc);
              `rdoc' specifies a result document object.  The return value  is  the  URI  of  the
              result  document  object.   The life duration of the returned string is synchronous
              with the one of the result document object.

       The function `est_resdoc_attr_names' is used in order to get a list of attribute names  of
       a result document object.

       CBLIST *est_resdoc_attr_names(ESTRESDOC *rdoc);
              `rdoc'  specifies  a result document object.  The return value is a new list object
              of attribute names of the result document object.  Because the object of the return
              value  is  opened  with  the  function  `cblistopen',  it should be closed with the
              function `cblistclose' if it is no longer in use.

       The function `est_resdoc_attr' is used in order to get the value  of  an  attribute  of  a
       result document object.

       const char *est_resdoc_attr(ESTRESDOC *rdoc, const char *name);
              `rdoc'  specifies  a  result  document  object.   `name'  specifies  the name of an
              attribute.  The return value is the value of the attribute or `NULL' if it does not
              exist.  The life duration of the returned string is synchronous with the one of the
              result document object.

       The function `est_resdoc_snippet' is used in order to get the snippet of a result document
       object.

       const char *est_resdoc_snippet(ESTRESDOC *rdoc);
              `rdoc'  specifies  a  result  document object.  The return value is a string of the
              snippet of the result document object.  There are tab separated values.  Each  line
              is  a  string  to be shown.  Though most lines have only one field, some lines have
              two fields.  If the second field exists, the  first  field  is  to  be  shown  with
              highlighted,  and the second field means its normalized form.  The life duration of
              the returned string is synchronous with the one of the result document object.

       The function `est_resdoc_keywords' is used in order to get keywords of a  result  document
       object.

       const char *est_resdoc_keywords(ESTRESDOC *rdoc);
              `rdoc'  specifies  a  result  document  object.   The  return  value is a string of
              serialized keywords of the result document object.  There are tab separated values.
              Keywords  and  their  scores  come  alternately.  The life duration of the returned
              string is synchronous with the one of the result document object.

       The function `est_resdoc_shadows' is used in order to get an array of  documents  eclipsed
       by a result document object.

       ESTRESDOC **est_resdoc_shadows(ESTRESDOC *rdoc, int *np);
              `rdoc'  specifies  a  result  document  object.   `np'  specifies  the pointer to a
              variable to which the number of elements of the  return  value  is  assigned.   The
              return value is an array of eclipsed result document objects.  The life duration of
              the returned array and its elements is synchronous  with  the  one  of  the  result
              document object.

       The  function  `est_resdoc_similarity'  is  used in order to get similarity of an eclipsed
       result document object.

       double est_resdoc_similarity(ESTRESDOC *rdoc);
              `rdoc' specifies a result document object.  The return value is similarity  of  the
              result document object to the front document or -1.0 if it is not eclipsed.

PARALLELING

       Each  of node connection objects, node result objects, and result document objects can not
       be shared by threads.  If you use multi threads, make each thread have  its  own  objects.
       If  the  precondition  is  kept,  functions  of the node API can be treated as thread-safe
       functions.

AUTHOR

       Hyper Estraier is written by Mikio Hirabayashi.  You can contact the author by  e-mail  to
       <mikio@users.sourceforge.net>.  Any suggestion or bug report is welcome to the author.

ACKNOWLEDGEMENTS

       Hyper  Estraier  was  developed  under  management  by  Fumitoshi  Ukai  and  supports  by
       Exploratory Software Project of Information-technology Promotion Agency, Japan (IPA).

COPYRIGHT

       Copyright (C) 2004-2007 Mikio Hirabayashi

       Hyper Estraier is free software; you can redistribute it and/or modify it under the  terms
       of  the  GNU  Lesser  General Public License as published by the Free Software Foundation;
       either version 2 of the License, or any later version.

       Hyper Estraier is distributed in the  hope  that  it  will  be  useful,  but  WITHOUT  ANY
       WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU Lesser General Public License for more details.

       You should have received a copy of the GNU Lesser General Public License along with  Hyper
       Estraier; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
       Boston, MA 02111-1307 USA.

SEE ALSO

       estconfig(1), estcmd(1), estmaster(1), estcall(1), estwaver(1), cabin(3), estraier(3)

       Please see http://hyperestraier.sourceforge.net/nguide-en.html for detail.