Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 ob-
       ject is	created	 by  the  function  `est_node_new'  and	 destroyed  by
       `est_node_delete'.   Every created node connection object should	be de-
       stroyed.

       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 in-
       formation 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 data-
       base 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  at-
	      tribute.	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  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 re-
	      turn value is allocated with the `malloc'	call, it should	be re-
	      leased 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  re-
       trieve  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 ob-
	      ject 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  re-
	      turned.

       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 re-
	      turned.

       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 re-
	      turned.

       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 synchro-
	      nous 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 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  ac-
       count 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	*la-
       bel, 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 re-
       sult from a node.  A result is composed of a list of corresponding doc-
       uments 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 re-
       sult 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
       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  ob-
	      ject or `NULL' if	`index'	is equal to or more than the number of
	      documents.  The life duration of the returned object is synchro-
	      nous with	the one	of the node result object.

       The  function `est_resdoc_uri' is used in order to get the URI of a re-
       sult 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  ob-
	      ject.  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 at-
	      tribute 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 synchro-
	      nous 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 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 re-
	      turn value is  assigned.	 The  return  value  is	 an  array  of
	      eclipsed	result document	objects.  The life duration of the re-
	      turned 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  Li-
       cense, 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  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  Li-
       cense  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  de-
       tail.

Man Page			  2007-03-06			    ESTNODE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=estnode&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help