Man Linux: Main Page and Category List

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-2005 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.