


ESTNODE(3)                Hyper Estraier               ESTNODE(3)


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 net-
       working 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 connec-
       tion 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 connec-
       tion 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 con-
       nection 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



Man Page                    2007-03-06                          1





ESTNODE(3)                Hyper Estraier               ESTNODE(3)


       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 authenti-
       cation 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 fail-
              ure 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.



Man Page                    2007-03-06                          2





ESTNODE(3)                Hyper Estraier               ESTNODE(3)


       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  suc-
              cess, 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 func-
              tion 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 docu-
              ment  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.



Man Page                    2007-03-06                          3





ESTNODE(3)                Hyper Estraier               ESTNODE(3)


       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.



Man Page                    2007-03-06                          4





ESTNODE(3)                Hyper Estraier               ESTNODE(3)


       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 syn-
              chronous 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.



Man Page                    2007-03-06                          5





ESTNODE(3)                Hyper Estraier               ESTNODE(3)


       The function `est_node_links' is used in order to get a list of expres-
       sions 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 set-
              ting 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 admin-
              istrator.  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



Man Page                    2007-03-06                          6





ESTNODE(3)                Hyper Estraier               ESTNODE(3)


              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 num-
              ber 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



Man Page                    2007-03-06                          7





ESTNODE(3)                Hyper Estraier               ESTNODE(3)


       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 syn-
              chronous 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 docu-
              ment 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  normal-
              ized  form.   The  life  duration of the returned string is syn-
              chronous 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.




Man Page                    2007-03-06                          8





ESTNODE(3)                Hyper Estraier               ESTNODE(3)


       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  syn-
              chronous 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  docu-
       ment  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 Pro-
       motion 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  pub-
       lished  by  the  Free  Software  Foundation;  either  version  2 of the
       License, or any later version.




Man Page                    2007-03-06                          9





ESTNODE(3)                Hyper Estraier               ESTNODE(3)


       Hyper Estraier is distributed in the hope that it will be  useful,  but
       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER-
       CHANTABILITY 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.








































Man Page                    2007-03-06                         10


