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.