0.5.3/doc/nguide-en.html

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
<meta http-equiv="Content-Language" content="en" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="author" content="Mikio Hirabayashi" />
<meta name="keywords" content="Hyper Estraier, Estraier, full-text search, API, Node, P2P" />
<meta name="description" content="API specifications of Hyper Estraier" />
<link rel="contents" href="./" />
<link rel="alternate" href="nguide-ja.html" hreflang="ja" title="the Japanese version" />
<link rel="stylesheet" href="common.css" />
<link rel="icon" href="icon16.png" />
<link rev="made" href="mailto:mikio@users.sourceforge.net" />
<title>P2P Guide of Hyper Estraier Version 1</title>
</head>

<body>

<h1>P2P Guide</h1>

<div class="note">Copyright (C) 2004-2005 Mikio Hirabayashi</div>
<div class="note">Last Update: Mon, 01 Aug 2005 00:50:38 +0900</div>
<div class="navi">[<a href="nguide-ja.html" hreflang="ja">Japanese</a>] [<a href="index.html">HOME</a>]</div>

<hr />

<h2 id="tableofcontents">Table of Contents</h2>

<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#architecture">Architecture</a></li>
<li><a href="#tutorial">Tutorial</a></li>
<li><a href="#estmaster">Command of the Node Master</a></li>
<li><a href="#protocol">Protocol</a></li>
<li><a href="#nodeapi">Node API</a></li>
<li><a href="#estcall">Command of a Client</a></li>
</ol>

<hr />

<h2 id="introduction">Introduction</h2>

<p>This document describes how to use P2P mechanism of Hyper Estraier.  If you have never read <a href="uguide-en.html">the user's guide</a>, please read it beforehand.</p>

<p>estseek.cgi is not efficient because it connects to the database per execution.  And, it is impossible to perform search during database updating, because estcmd locks the database.  To solve the problem, Hyper Estraier provides a server program of C/S (client/server) architecture.  There are a resident process keeping connection to the database and it serves some operations via network.  The C/S architecture has the following advantages.</p>

<ul>
<li>The server and its clients work on separate machines.</li>
<li>Plural clients of one server can work in parallel.</li>
<li>The database is not broken even when some clients crash.</li>
<li>Clients can be implemented without dependency of programming languages or APIs.</li>
</ul>

<p>Because the protocol between C/S is based on HTTP, some popular web browsers can be used as clients.  Of course, clients can be implemented on your own way.  It is also good idea to use such technologies around web browser as JavaScript, Flash, and so on.</p>

<p>Distributed processing based on P2P (Peer to Peer) architecture is supported.  If you use 10 servers handling one million of documents, you can search 10 millions of documents.  Because servers are equivalent, whole of the network service works successively even if a server crashes.  Moreover, calculating reliability between servers is supported and it can improve search precision.</p>

<p>The node API is provided to hide the protocol between C/S.  Using the node API, you can implement client applications without closeup know-hows about network.  This document describes how to use the node API (C language).  Interfaces of the node API for <a href="japidoc/">Java</a> and <a href="rbapidoc/">Ruby</a> are also provided.</p>

<hr />

<h2 id="architecture">Architecture</h2>

<p>This section describes the P2P architecture of Hyper Estraier.</p>

<h3>Node Master and Node Server</h3>

<p>If you uses many indexes, it is inefficient to run a server per index.  So, a program called node master is provided.  While it works as one process and uses one network port, it can handle several indexes.  Because each index performs its own service, we can regard a "node master" as aggregation of several index servers.  On the viewpoint, each virtual server handling an index is called "node server".  Each node server has an own URL.  A client application knows URL of a node server but does not know in which node master the node server works.</p>

<div class="illust"><img src="nodeframe.png" width="720" height="350" alt="[framework]" /></div>

<p>The term "node" is used as with the term "peer" in the P2P architecture.  As a client connects to a node master itself and manage some nodes, another client connects to a node server and search/register documents.</p>

<h3>Meta Search and Credit</h3>

<p>A node server can link to another node server one-sidedly.  When a client send a query to a node server, the node server relay the query to linked nodes.  Responses of linked nodes and the first node are merged and sent back to the client.  That is, so-called meta search is supported by every nodes and it realizes distributed processing in P2P architecture.</p>

<p>The meta search is performed hierarchically.  Because loop of routing is detected and restrained automatically, the behavior is as with search of tree structured network.  Due to this mechanism, it is possible to increase nodes of the network up to infinity.</p>

<div class="illust"><img src="metatree.png" width="720" height="400" alt="[tree of meta search]" /></div>

<p>Reliability called "credit" is set to each link between nodes.  When a node merges responses collected by meta search, credit is used for weighting of scores.  So, documents in response of nodes with high credit is apt to be shown in high ranks.  As applications are responsible to set links and their credit, it is possible to improve search precision by increasing credit of frequently used nodes.</p>

<h3>Authentication</h3>

<p>When a client connects to the node master or a node server, authentication with a user name and a password is performed.  Users are classified into super users and normal users.  The former has permission to manage nodes and users.  The latter does not have those permissions.  Moreover, permission is granted for each node servers.  Each node has lists of administrator who can update the index and normal users who can perform search only.  Besides, super users of the node master can connect as administrators to node servers in the same node master.</p>

<hr />

<h2 id="tutorial">Tutorial</h2>

<p>As the concept of P2P seems difficult, let's try to use some commands and learn it by degrees.</p>

<h3>Start and Stop</h3>

<p>For preparation for the node master, create the server root directory which includes configuration files and indexes.  Perform the following command and a directory "casket" will be created.</p>

<pre>estmaster init casket
</pre>

<p>Next, start the node master.  Perform the following command.</p>

<pre>estmaster start casket
</pre>

<p>To stop the node master, input Ctrl-D on the terminal on which the node master is running or perform the following command on another terminal.</p>

<pre>estmaster stop casket
</pre>

<h3>Administration Interface</h3>

<p>While the node master is running, we can access "http://localhost:1978/masterui" with a web browser and use the administration interface.  When access the URL, a dialog is shown and the user name and the password is required.  Input "admin" and "admin".  Then, the menu of administration commands is displayed.</p>

<p>If you step into "Manage Master" and select "SHUTDOWN", you can stop the node master.  But, leave it for now.</p>

<p>Select "Manage Users".  As you have logged in as a user whose name is "admin", create a new user account and switch to it.  Input the user name, the password, the flags, the full name, and the the miscellaneous information into the forms at the bottom of the page.  The name and the password can contain alphanumeric characters only.  As for now, input "clint", "tnilc", "s", "Clint Eastwood", and "Dirty Harry".  It is important to set "s" in the flags.  It means that the user is a super user.</p>

<p>Now, the user "admin" is no longer in use.  As it has some potential security problems, delete it.  Select the "DELE" in the line of "admin" and push "delete" on the next confirmation step.</p>

<p>Step into "Manage Nodes".  Because the user "admin" is deleted, you are asked the user name and the password again.  Input the "clint" and "tnilc" so that you can continue.  In turn, create new nodes.  Input the node name and the label into the form at the bottom of the page.  The name can contain alphanumeric characters only.  As for now, create a node whose name is "test1" and whose label is "First Node".  And create another node whose name is "test2" and whose label is "Second Node".</p>

<h3>Register Documents</h3>

<p>Back to the command line operations.  As the terminal of the node master is busy to show log messages, open another terminal.</p>

<p>Let's register some documents into the indexes of nodes.  It is needed to prepare document draft data of documents to register.  Create the following file and save it as "data001.est".</p>

<pre>@uri=data001
@title=Material Girl

Living in a material world
And I am a material girl
You know that we are living in a material world
And I am a material girl
</pre>

<p>To register it into the node "test1", perform the following command.  Because the permission as administrators is needed to update the index, you should specify the user name and the password with the -auth option.  Process of registration finishes in a flash.  It is success if no error message is shown.</p>

<pre>estcall put -auth clint tnilc http://localhost:1978/node/test1 data001.est
</pre>

<p>For explanation of meta search said later, register another document into the node "test2" also.  Create the following file and save it as "data002.est".</p>

<pre>@uri=data002
@title=Liberian Girl

Liberian girl
You came and you changed My world
A love so brand new
</pre>

<p>Then, perform the following command.</p>

<pre>estcall put -auth clint tnilc http://localhost:1978/node/test2 data002.est
</pre>

<p>It is useful to register documents from remote machines, isn't it?  As with the above steps, register some other documents.</p>

<h3>Search for Documents</h3>

<p>All right, let's search for some registered documents.  Perform the following command, and information of the corresponding document is shown.</p>

<pre>estcall search http://localhost:1978/node/test1 "material world"
</pre>

<p>By setting a link between the two nodes, you can do meta search.  Now, set the link from "test1" to "test2".  Specify the URL of the source node, the URL of the destination node, the label to display, and the credit.</p>

<pre>estcall setlink -auth clint tnilc http://localhost:1978/node/test1 \
  http://localhost:1978/node/test2 TEST02 8000
</pre>

<p>And, search again.  This time, set depth of meta search with the option -dpt.</p>

<pre>estcall search -dpt 1 http://localhost:1978/node/test1 "girl"
</pre>

<p>Though you access the node "test1", the result of "test2" is merged and shown.  It is the feature of meta search in P2P architecture.  If "test1" and "test2" are on separate machines, distributed computing is realized.</p>

<p>By increasing the credit, ranking of documents in the result of the destination node is to be higher.  Perform the following command and search again.  Then, you will see the ranking is changed.</p>

<pre>estcall setlink -auth clint tnilc http://localhost:1978/node/test1 \
  http://localhost:1978/node/test2 TEST02 12000
</pre>

<p>You can get result as XML data.  Perform the following command.  See estresult.dtd for detail of the XML format.</p>

<pre>estcall search -dpt 1 -vx http://localhost:1978/node/test1 "girl"
</pre>

<p>Each node server embeds search interface for web browsers.  Access "http://localhost:1978/node/test1/searchui" to use it.</p>

<hr />

<h2 id="estmaster">Command of the Node Master</h2>

<p>`estmaster' is provided as a command to manage the node master.  This section describes how to use estmaster.</p>

<h3>Synopsis and Description</h3>

<p>estmaster is an aggregation of sub commands.  The name of a sub command is specified by the first argument.  Other arguments are parsed according to each sub command.  The argument <var>rootdir</var> specifies the server root directory which contains configuration file and so on.</p>

<dl>
<dt><kbd>estmaster init [-ex] <var>rootdir</var></kbd></dt>
<dd>Create the server root directory.</dd>
<dd>If -ex is specified, some users and some nodes are set for example.  By default, only a super user whose name and password are both "admin" is set.</dd>
</dl>

<dl>
<dt><kbd>estmaster start [-bg] [-st] <var>rootdir</var></kbd></dt>
<dd>Start the node master.</dd>
<dd>If -bg is specified, the server runs in background as a daemon process.</dd>
<dd>If -st is specified, the server runs in single thread mode.</dd>
</dl>

<dl>
<dt><kbd>estmaster stop <var>rootdir</var></kbd></dt>
<dd>Stop the running node master.</dd>
</dl>

<dl>
<dt><kbd>estmaster unittest <var>rootdir</var></kbd></dt>
<dd>Perform unit tests.</dd>
</dl>

<dl>
<dt><kbd>estmaster crypt <var>key</var> [<var>hash</var>]</kbd></dt>
<dd>Output an encrypted string of a string.</dd>
<dd><var>key</var> specifies a target string.</dd>
<dd>If <var>hash</var> is specified, it checks whether the key and the hash matches.</dd>
</dl>

<p>All sub commands return 0 if the operation is success, else return 1.  A running node master finishes with closing the database when it catches the signal 2 (SIGINT), 3 (SIGQUIT), or 15 (SIGTERM).  Moreover, when a running node master catches the signal 1 (SIGHUP), the process is re-start and re-read the configuration files.</p>

<p>A running node server should be finished by valid means by command line or via network.  Otherwise, the index may be broken.</p>

<h3>Constitution of the Server Root Directory</h3>

<p>The server root directory contains the following files and directories.</p>

<ul>
<li><kbd>_conf</kbd> : prime configuration file.</li>
<li><kbd>_user</kbd> : user account file.</li>
<li><kbd>_log</kbd> : log file.</li>
<li><kbd>_meta</kbd> : database file for meta data.</li>
<li><kbd>_pid</kbd> : file recording the process ID.</li>
<li><kbd>_stop</kbd> : file to stop the node master.</li>
<li><kbd>_node/</kbd> : node directory.</li>
<li><kbd>_sess/</kbd> : session directory.</li>
</ul>

<p>The prime configuration file can be edit with a text editor.  However, the user account file should not be edit during the node master is running.</p>

<p>If you have an index created by estcmd, move it into the node directory and reboot the server.  So, the index will work as a node.</p>

<h3>Prime Configuration File</h3>

<p>The prime configuration file is composed of lines and the name of an variable and the value separated by `:' are in each line.  By default, the following configuration is there.</p>

<pre>hostname: localhost
portnum: 1978
runmode: 1
authmode: 2
maxconn: 30
sessiontimeout: 600
searchtimeout: 8
searchdepth: 5
proxyhost:
proxyport:
loglevel: 2
docroot:
indexfile:
trustednode:
denyuntrusted: 0
cachesize: 64
specialcache:
snipwwidth: 480
sniphwidth: 96
snipawidth: 96
uilprefix: file:///home/mikio/public_html/
uigprefix: http://localhost/
uigsuffix:
uidirindex: index.html
uireplace: //localhost/{{!}}//127.0.0.1/
uireplace: //127.0.0.1:80/{{!}}//127.0.0.1/
uiextattr: @author|Author
uiextattr: @mdate|Modification Date
uismplphrase: 1
</pre>

<p>Meaning of each variable is the following.</p>

<ul>
<li><kbd>hostname</kbd> : specifies the host name of the server.</li>
<li><kbd>portnum</kbd> : specifies the port number of the server.</li>
<li><kbd>runmode</kbd> : specifies running mode (1:normal, 2:readonly).</li>
<li><kbd>authmode</kbd> : specifies authorization mode (1:none, 2:admin, 3:all).</li>
<li><kbd>maxconn</kbd> : specifies maximum number of connections at the same time.</li>
<li><kbd>sessiontimeout</kbd> : specifies timeout of a session (in seconds).</li>
<li><kbd>searchtimeout</kbd> : specifies timeout of search (in seconds).</li>
<li><kbd>searchdepth</kbd> : specifies maximum depth of meta search.</li>
<li><kbd>proxyhost</kbd> : specifies the host name of the proxy server.</li>
<li><kbd>proxyport</kbd> : specifies the port number of the proxy server.</li>
<li><kbd>loglevel</kbd> : specifies logging level (1:debug, 2:information, 3:warning, 4:error, 5:none).</li>
<li><kbd>docroot</kbd> : specifies document root directory (full path of a directory to be public).</li>
<li><kbd>indexfile</kbd> : specifies index file (name of directory index files).</li>
<li><kbd>trustednode</kbd> : specifies decimal IP addresses of trusted nodes.  This can be more than once.</li>
<li><kbd>denyuntrusted</kbd> : specifies whether to deny all nodes except for trusted nodes (0:no, 1:yes).</li>
<li><kbd>cachesize</kbd> : specifies maximum size of the index cache (in mega bytes).</li>
<li><kbd>specialcache</kbd> : specifies name of the attribute of the special cache.</li>
<li><kbd>snipwwidth</kbd> : specifies whole width of the snippet of each shown document.</li>
<li><kbd>sniphwidth</kbd> : specifies width of strings picked up from the beginning of the text.</li>
<li><kbd>snipawidth</kbd> : specifies width of strings picked up around each highlighted word.</li>
<li><kbd>uilprefix</kbd> : specifies the prefix of the local URI of each document.</li>
<li><kbd>uigprefix</kbd> : specifies the prefix of the global URI of each document.</li>
<li><kbd>uigsuffix</kbd> : specifies the suffix added to the global URI of each document.</li>
<li><kbd>uidirindex</kbd> : specifies the name of the directory index file.</li>
<li><kbd>uireplace</kbd> : specifies an expression to replace the URI of each document.  Before string and after string are separated by "{{!}}".  This can be more than once.</li>
<li><kbd>uiextattr</kbd> : specifies an attribute to be shown.  The name and the label are separated by "|".  This can be more than once.</li>
<li><kbd>uismplphrase</kbd> : specifies whether to use simplified search phrase (0:no, 1:yes).</li>
</ul>

<h3>User Account File</h3>

<p>The user account file is composed of lines and each includes the name, the encrypted password, the flags, the full name, and the miscellaneous information separated by tabs.  The character encoding is UTF-8.  By default, the following account is there.</p>

<pre>admin   21232f297a57a5a743894a0e4a801fc3        s       Carolus Magnus  Administrator
</pre>

<p>The password is expressed as MD5 hash value.  In the flags, "s" is for super users, and "b" is for banned users.  Flags, full name, and miscellaneous information can be omitted.</p>

<h3>Embedded User Interfaces</h3>

<p>By accessing the absolute URL "/masterui" of the node master with a web browser, you can use the administration interface.  It requires authentication as a super user.</p>

<p>By accessing the URL which is the URL of a node server followed by "/searchui", you can use the search interface.</p>

<hr />

<h2 id="protocol">Protocol</h2>

<p>Communication between nodes and communication between clients and nodes are carried out by a protocol based on HTTP.  This section describes the protocol.</p>

<h3>Introduction</h3>

<p>The node master and node servers implement HTTP/1.0.  As for now, such particular features of HTTP/1.1 as keep-alive connection, chunked encoding, and content negotiation are not supported.</p>

<p>While both of GET and POST are allowed for the request method of HTTP, GET is preferred if the command retrieves information, POST is preferred if the command update the node master or a node server.  As the character encoding of parameters is UTF-8, meta characters and multi-byte characters should be escaped by URL encoding (application/x-www-form-urlencoded).  The maximum length of data sent with the GET method is 8000.  Authentication information is passed in the basic authentication mechanism of HTTP.</p>

<p>If an operation is done successfully, the status code 200 or 202 is returned.  On error, one of the following status code is returned.</p>

<ul>
<li>400 : parameters are invalid.</li>
<li>401 : authentication information lacks or is invalid.</li>
<li>403 : the account has not the permission.</li>
<li>404 : the node does not exist.</li>
<li>500 : some errors of due to the server occurred.</li>
</ul>

<p>The result of operation of search or retrieve is sent as message body of response.  As the format of the data is plain text whose encoding is UTF-8, it can be structured with tabs and line feeds.</p>

<h3>Operation of Node Master</h3>

<p>To operate the node master, connect to the path "/master" of the server.  For example, if the host name is "skyhigh.estraier.go.jp" and the port number is 8888, connect to "http://skyhigh.estraier.go.jp:8888/master".  Only super users are granted to operate the node master.  There are some sub commands for operations of the node master.  The name of a sub command is specified by the parameter "action".  Other parameters vary according to each sub command.</p>

<dl>
<dt><kbd>/master?action=shutdown</kbd></dt>
<dd>Shutdown the node master.</dd>
<dd>No parameter is used.</dd>
<dd>On success, the status code 202 is returned.</dd>
</dl>

<dl>
<dt><kbd>/master?action=userlist</kbd></dt>
<dd>Get the list of user accounts.</dd>
<dd>No parameter is used.</dd>
<dd>On success, the status code 200 is returned.  The entity body of response expresses the list of user accounts whose format is TSV.  Each line is information of each user.  There is fields of the user name, the encrypted password, the flags, the full name, and the miscellaneous information.</dd>
</dl>

<dl>
<dt><kbd>/master?action=useradd&amp;name=<var>str</var>&amp;passwd=<var>str</var>&amp;flags=<var>str</var>&amp;fname=<var>str</var>&amp;misc=<var>str</var></kbd></dt>
<dd>Add a user account.</dd>
<dd><var>name</var> specifies the name of a new user.  It is essential.  Only alphanumeric characters are in the name.  If the specified name overlaps the name of an existing user, it is treated as an error.</dd>
<dd><var>passwd</var> specifies the password.  It is essential.</dd>
<dd><var>flags</var> specifies the flags.  It is optional.</dd>
<dd><var>fname</var> specifies the full name.  It is optional.</dd>
<dd><var>misc</var> specifies the miscellaneous information.  It is optional.</dd>
<dd>On success, the status code 200 is returned.</dd>
<dd>Because the password is sent, POST method should be used.</dd>
</dl>

<dl>
<dt><kbd>/master?action=userdel&amp;name=<var>str</var></kbd></dt>
<dd>Delete a user account.</dd>
<dd><var>name</var> specifies the name of a user.  It is essential.</dd>
<dd>On success, the status code 200 is returned.</dd>
</dl>

<dl>
<dt><kbd>/master?action=nodelist</kbd></dt>
<dd>Get the list of node servers.</dd>
<dd>No parameter is used.</dd>
<dd>On success, the status code 200 is returned.  The entity body of response expresses the list of node servers whose format is TSV.  Each line is information of each node.  There is fields of the node name, the label, the number of documents, the number of unique words, and the size.</dd>
</dl>

<dl>
<dt><kbd>/master?action=nodeadd&amp;name=<var>str</var>&amp;label=<var>str</var></kbd></dt>
<dd>Add a node server.</dd>
<dd><var>name</var> specifies the name of a new node.  It is essential.  Only alphanumeric characters are in the name.  If the specified name overlaps the name of an existing node, it is treated as an error.</dd>
<dd><var>label</var> specifies the label.  It is optional.  If it is omitted, the label is to be the same as the name.</dd>
<dd>On success, the status code 200 is returned.</dd>
</dl>

<dl>
<dt><kbd>/master?action=nodedel&amp;name=<var>str</var></kbd></dt>
<dd>Delete a node server.</dd>
<dd><var>name</var> specifies the name of a node.  It is essential.</dd>
<dd>On success, the status code 200 is returned.</dd>
</dl>

<h3>Operation of Node Server</h3>

<p>To operate a node server, connect to a path which begins "/node/" and is followed by the name of the node.  For example, if the host name is "skyhigh.estraier.go.jp" and the port number is 8888 and the name of the node is "foo", connect to "http://skyhigh.estraier.go.jp:8888/node/foo".  There are some sub commands for operations of node servers.  The name of a sub command is specified after the node name.  Parameters vary according to each sub command.</p>

<dl>
<dt><kbd>/node/<var>name</var>/inform</kbd></dt>
<dd>Get information of a node.</dd>
<dd>No parameter is used.</dd>
<dd>On success, the status code 200 is returned.  The entity body of response expresses node information whose format is TSV.  The first line includes fields of the node name, the label, the number of documents, the number of unique words, and the size.  The next line is empty.  The succeeding lines to the next empty line are names of administrators.  And, the succeeding lines to the next empty line are names of normal users.  And, the succeeding lines to the end are link information.  There are fields of the URL, the label, and the credit.</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/search?phrase=<var>str</var>&amp;attr=<var>str</var>&amp;order=<var>str</var>&amp;max=<var>num</var>&amp;options=<var>num</var>&amp;depth=<var>num</var></kbd></dt>
<dd>Search for documents.</dd>
<dd><var>phrase</var> specifies the search phrase.  It is optional.  The format is as with the one of the core API.</dd>
<dd><var>attr</var> specifies an attribute search condition.  It is optional.  From <var>attr1</var> to <var>attr9</var> works as with it.  The format is as with the one of the core API.</dd>
<dd><var>order</var> specifies the order expression.  It is optional.  The format is as with the one of the core API.</dd>
<dd><var>max</var> specifies the maximum number of shown documents.  It is optional.  By default, it is 10.</dd>
<dd><var>options</var> specifies options.  It is optional.  The value is as with the one of the core API.</dd>
<dd><var>depth</var> specifies depth of meta search.  It is optional.  By default, it is 0.</dd>
<dd>On success, the status code 200 is returned.  The entity body of response expresses the search result.  The format is explained later.</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/get_doc?id=<var>num</var>&amp;uri=<var>str</var></kbd></dt>
<dd>Get information of a document.</dd>
<dd><var>id</var> specifies the ID number of a document.  It is optional.</dd>
<dd><var>uri</var> specifies the URI of a document.  It is optional.</dd>
<dd>On success, the status code 200 is returned.  The entity body of response expresses the search result.  The format is document draft.</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/get_doc_attr?id=<var>num</var>&amp;uri=<var>str</var>&amp;attr=<var>str</var></kbd></dt>
<dd>Get the value of an attribute of a document.</dd>
<dd><var>id</var> specifies the ID number of a document.  It is optional.</dd>
<dd><var>uri</var> specifies the URI of a document.  It is optional.</dd>
<dd><var>attr</var> specifies the name of an attribute.  It is essential.</dd>
<dd>On success, the status code 200 is returned.  The entity body of response expresses the value of the attribute.</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/uri_to_id?uri=<var>str</var></kbd></dt>
<dd>Get the ID number of a document specified by URI.</dd>
<dd><var>uri</var> specifies the URI of a document.  It is essential.</dd>
<dd>On success, the status code 200 is returned.  The entity body of response expresses the ID number of the document.</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/put_doc?draft=<var>str</var></kbd></dt>
<dd>Register a document.  It is available by administrators only.</dd>
<dd><var>draft</var> specifies content of a document in document draft format.  It is essential.</dd>
<dd>On success, the status code 200 is returned.</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/out_doc?id=<var>num</var>&amp;uri=<var>str</var></kbd></dt>
<dd>Remove a document.  It is available by administrators only.</dd>
<dd><var>id</var> specifies the ID number of a document.  It is optional.</dd>
<dd><var>uri</var> specifies the URI of a document.  It is optional.</dd>
<dd>On success, the status code 200 is returned.</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/_set_user?name=<var>str</var>&amp;mode=<var>num</var></kbd></dt>
<dd>Set permission of a user.  It is available by administrators only.</dd>
<dd><var>name</var> specifies the name of a user.  It is essential.</dd>
<dd><var>mode</var> specifies operation mode.  It is essential.  1 means to set the user as an administrator, 2 means to set the user as a normal user, and 0 means to revoke the user account.</dd>
<dd>On success, the status code 200 is returned.</dd>
</dl>

<dl>
<dt><kbd>/node/<var>name</var>/_set_link?url=<var>str</var>&amp;label=<var>str</var>&amp;credit=<var>num</var></kbd></dt>
<dd>Set a link to another node.  It is available by administrators only.</dd>
<dd><var>url</var> specifies the URL of a destination node.  It is essential.  If the specified URL overlaps the URL of an existing link, the label and the credit is overwritten.</dd>
<dd><var>label</var> specifies the label of the link.  It is essential.</dd>
<dd><var>credit</var> specifies the credit of the link.  It is optional.  If it is omitted, the link is removed.</dd>
<dd>On success, the status code 200 is returned.</dd>
</dl>

<p>Note that while super users has permission to administrate all nodes, an administrator of a node may not be a super user.  Moreover, setting of normal users of each node have meaning only when the authorization mode is 3 (all).</p>

<h3>Format of Search Result</h3>

<p>The format of the entity body of result of search command is alike to multipart of MIME.  The following is an example.</p>

<pre>--------[2387AD2E34554FFF]--------
VERSION 0.9
NODE    http://localhost:1978/node/sample1
HIT     2
HINT#1  give    2
DOCNUM  2
WORDNUM 31
TIME    0.001
LINK#0  http://localhost:1978/node/sample1      Sample1 10000   2       31      2731304 2
LINK#1  http://localhost:1978/node/sample2      Sample2 4000    3       125     8524522 1
VIEW    SNIPPET

--------[2387AD2E34554FFF]--------
#nodelabel=Sample Node One
#nodeurl=http://localhost:1978/node/sample1
@id=1
@uri=http://localhost/foo.html

You may my glories and my state dispose, But not my griefs; still am I king of those. (
Give    give
 it u

p, Yo!
Give    give
 it up, Yo!)

--------[2387AD2E34554FFF]--------
#nodelabel=Sample Node One
#nodeurl=http://localhost:1978/node/sample1
@id=2
@uri=http://localhost/bar.html

The faster I go, the behinder I get. (
Give    give
 it up, Yo!
Give    give
 it up, Yo!)

--------[2387AD2E34554FFF]--------:END
</pre>

<p>Each line feed is a single LF.  The first line is definition of the border string.  Each parts are delimited by the border string.  The last border string is followed by ":END".  The first part is the meta section.  The other parts are document sections.</p>

<p>The format of the meta section is TSV.  Meaning of each string is picked out by the first field.  There are the following kinds.</p>

<ul>
<li><kbd>VERSION</kbd> : specifies the version of the protocol.</li>
<li><kbd>NODE</kbd> : specifies the URL of the node.</li>
<li><kbd>HIT</kbd> : specifies the total number of the corresponding documents.</li>
<li><kbd>HINT#<var>n</var></kbd> : specifies the number of documents corresponding each word.  The second field specifies the word.  The third field specifies the number.</li>
<li><kbd>DOCNUM</kbd> : specifies the total number of documents in target nodes.</li>
<li><kbd>WORDNUM</kbd> : specifies the total number of words in target nodes.</li>
<li><kbd>TIME</kbd> : specifies elapsed time in milliseconds.</li>
<li><kbd>LINK#<var>n</var></kbd> : specifies information of each linked node.  Fields express the URL, the label, the credit, the number of documents, the number of unique words, the size of the database, and the number of corresponding documents.  LINK#0 means the node it self.</li>
<li><kbd>VIEW</kbd> : specifies the format of document parts.  As for now, it is constantly "SNIPPET".</li>
</ul>

<p>Each document part expresses attributes and a snippet of a document.  Top lines to the first empty line expresses attributes.  Their format is as with the one of document draft.  The format of the snippet is TSV.  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.</p>

<p>The following pseudo-attributes are added to each result documents of the search command or the get_doc command includes.</p>

<ul>
<li><kbd>#nodeurl</kbd> : specifies the URL of the node into which the document was registered.</li>
<li><kbd>#nodelabel</kbd> : specifies the label of the node into which the document was registered.</li>
</ul>

<h3>Special Format for Document Registration</h3>

<p>Because URL encoding is not efficient as for large data sent for the put_doc command, the raw mode is supported.  If the value of "Content-Type" is "text/x-estraier-draft", the entity body is treated as a document draft itself.  The following is an example.</p>

<pre>POST /node/foo/put_doc HTTP/1.0
Content-Type: text/x-estraier-draft
Content-Length: 138

@uri=http://gogo.estraier.go.jp/sample.html
@title=Twinkle Twinkle Little Star

Twinkle, twinkle, little star,
How I wonder what you are.
</pre>

<hr />

<h2 id="nodeapi">Node API</h2>

<p>As it is a bother to implement HTTP, the node API is useful.  This section describes how to use the node API.</p>

<h3>Introduction</h3>

<p>Using the node API, you can implement clients communicating node severs without considering such low level processing as TCP/IP and HTTP.  Though the node API has overhead comparing to the core API, it is important to be able to execute at remote host and to perform parallel processing without discrimination of readers and writers.</p>

<p>In each source of applications of the node API, include `estraier.h', `estnode.h', `cabin.h', and `stdlib.h'.</p>

<pre>#include &lt;estraier.h&gt;
#include &lt;estnode.h&gt;
#include &lt;cabin.h&gt;
#include &lt;stdlib.h&gt;
</pre>

<p>To build an application, perform the following command.  It is same as with the core API.</p>

<pre>gcc `estconfig --cflags` -o foobar foobar.c `estconfig --ldflags` `estconfig --libs`
</pre>

<p>Because the node API uses features of the core API also, if you have never read <a href="pguide-en.html">the programming guide</a>, please read it beforehand.</p>

<h3>API for Initializing</h3>

<p>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.</p>

<p>The function `est_init_net_env' is used in order to initialize the networking environment.</p>

<dl>
<dt><kbd>int est_init_net_env(void);</kbd></dt>
<dd>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.</dd>
</dl>

<p>The function `est_free_net_env' is used in order to free the networking environment.</p>

<dl>
<dt><kbd>void est_free_net_env(void);</kbd></dt>
<dd>There is no parameter and no return value.</dd>
</dl>

<h3>API for Nodes</h3>

<p>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.</p>

<p>The following is a typical use case of node connection object.</p>

<pre>ESTNODE *node;

/* create a node connection object */
node = est_node_new("http://estraier.gov:1978/node/foo");

/* set the proxy, the timeout, and the authentication */
est_node_set_proxy(node, "proxy.qdbm.go.jp", 8080);
est_node_set_timeout(node, 5);
est_node_set_auth(node, "mikio", "oikim");

  /* register documents or search for documents here */

/* destroy the object */
est_node_delete(node);
</pre>

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

<dl>
<dt><kbd>ESTNODE *est_node_new(const char *<var>url</var>);</kbd></dt>
<dd>`url' specifies the URL of a node.  The return value is a node connection object.</dd>
</dl>

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

<dl>
<dt><kbd>void est_node_delete(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' specifies a node connection object.</dd>
</dl>

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

<dl>
<dt><kbd>void est_node_set_proxy(ESTNODE *<var>node</var>, const char *<var>host</var>, int <var>port</var>);</kbd></dt>
<dd>`node' specifies a node connection object.  `host' specifies the host name of a proxy server.  `port' specifies the port number of the proxy server.</dd>
</dl>

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

<dl>
<dt><kbd>void est_node_set_timeout(ESTNODE *<var>node</var>, int <var>sec</var>);</kbd></dt>
<dd>`node' specifies a node connection object.  `sec' specifies timeout of the connection in seconds.</dd>
</dl>

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

<dl>
<dt><kbd>void est_node_set_auth(ESTNODE *<var>node</var>, const char *<var>name</var>, const char *<var>passwd</var>);</kbd></dt>
<dd>`node' specifies a node connection object.  `name' specifies the name of authentication.  `passwd' specifies the password of the authentication.</dd>
</dl>

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

<dl>
<dt><kbd>int est_node_status(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

<p>The function `est_node_put_doc' is used in order to add a document to a node.</p>

<dl>
<dt><kbd>int est_node_put_doc(ESTNODE *<var>node</var>, ESTDOC *<var>doc</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>int est_node_out_doc(ESTNODE *<var>node</var>, int <var>id</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>int est_node_out_doc_by_uri(ESTNODE *<var>node</var>, const char *<var>uri</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

<p>The function `est_node_get_doc' is used in order to retrieve a document in a node.</p>

<dl>
<dt><kbd>ESTDOC *est_node_get_doc(ESTNODE *<var>node</var>, int <var>id</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>ESTDOC *est_node_get_doc_by_uri(ESTNODE *<var>node</var>, const char *<var>uri</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>char *est_node_get_doc_attr(ESTNODE *<var>node</var>, int <var>id</var>, const char *<var>name</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

<p>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.</p>

<dl>
<dt><kbd>char *est_node_get_doc_attr_by_uri(ESTNODE *<var>node</var>, const char *<var>uri</var>, const char *<var>name</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>int est_node_uri_to_id(ESTNODE *<var>node</var>, const char *<var>uri</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>const char *est_node_name(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>const char *est_node_label(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>int est_node_doc_num(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' specifies a node connection object.  The return value is the number of documents in the node.  On error, -1 is returned.</dd>
</dl>

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

<dl>
<dt><kbd>int est_node_word_num(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' specifies a node connection object.  The return value is the number of unique words in the node.  On error, -1 is returned.</dd>
</dl>

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

<dl>
<dt><kbd>double est_node_size(ESTNODE *<var>node</var>);</kbd></dt>
<dd>`node' specifies a node connection object.  The return value is the size of the database of the node.  On error, -1.0 is returned.</dd>
</dl>

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

<dl>
<dt><kbd>ESTNODERES *est_node_search(ESTNODE *<var>node</var>, ESTCOND *<var>cond</var>, int <var>depth</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>int est_node_set_user(ESTNODE *<var>node</var>, const char *<var>name</var>, int <var>mode</var>);</kbd></dt>
<dd>`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 normal user.  The return value is true if success, else it is false.</dd>
</dl>

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

<dl>
<dt><kbd>int est_node_set_link(ESTNODE *<var>node</var>, const char *<var>url</var>, const char *<var>label</var>, int <var>credit</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

<h3>API for Search Results of Nodes</h3>

<p>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.</p>

<p>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.</p>

<p>The following is a typical use case of node connection object and result document object.</p>

<pre>ESTNODERES *nres;
CBMAP *hints;
ESTRESDOC *rdoc;
int i;

/* create a node result object */
nres = est_node_search(node, cond, 1);

/* get hints */
hints = est_noderes_hints(nres);

   /* show the hints here */

/* scan documents in the result */
for(i = 0; i &lt; est_noderes_doc_num(nres); i++){

  /* get a result document object */
  rdoc = est_noderes_get_doc(nres, i);

  /* show the result document object here */

}

/* destroy the node result object */
est_noderes_delete(nres);
</pre>

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

<dl>
<dt><kbd>void est_noderes_delete(ESTNODERES *<var>nres</var>);</kbd></dt>
<dd>`nres' specifies a node result object.</dd>
</dl>

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

<dl>
<dt><kbd>CBMAP *est_noderes_hints(ESTNODERES *<var>nres</var>);</kbd></dt>
<dd>`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", "LINK#n", and "VIEW".  The life duration of the returned object is synchronous with the one of the node result object.</dd>
</dl>

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

<dl>
<dt><kbd>int est_noderes_doc_num(ESTNODERES *<var>nres</var>);</kbd></dt>
<dd>`nres' specifies a node result object.  The return value is the number of documents in a node result object.</dd>
</dl>

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

<dl>
<dt><kbd>ESTRESDOC *est_noderes_get_doc(ESTNODERES *<var>nres</var>, int <var>index</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>const char *est_resdoc_uri(ESTRESDOC *<var>rdoc</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>CBLIST *est_resdoc_attr_names(ESTRESDOC *<var>rdoc</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>const char *est_resdoc_attr(ESTRESDOC *<var>rdoc</var>, const char *<var>name</var>);</kbd></dt>
<dd>`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.</dd>
</dl>

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

<dl>
<dt><kbd>const char *est_resdoc_snippet(ESTRESDOC *<var>rdoc</var>);</kbd></dt>
<dd>`rdoc' specifies a result document object.  The return value is 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.</dd>
</dl>

<h3>Paralleling</h3>

<p>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.</p>

<h3>Example of Gatherer</h3>

<p>The following is the simplest implementation of a gatherer.</p>

<pre>#include &lt;estraier.h&gt;
#include &lt;estnode.h&gt;
#include &lt;cabin.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;

int main(int argc, char **argv){
  ESTNODE *node;
  ESTDOC *doc;
  /* initialize the network environment */
  if(!est_init_net_env()){
    fprintf(stderr, "error: network is unavailable\n");
    return 1;
  }
  /* create and configure the node connection object */
  node = est_node_new("http://localhost:1978/node/test1");
  est_node_set_auth(node, "admin", "admin");
  /* create a document object */
  doc = est_doc_new();
  /* add attributes to the document object */
  est_doc_add_attr(doc, "@uri", "http://estraier.gov/example.txt");
  est_doc_add_attr(doc, "@title", "Over the Rainbow");
  /* add the body text to the document object */
  est_doc_add_text(doc, "Somewhere over the rainbow.  Way up high.");
  est_doc_add_text(doc, "There's a land that I heard of once in a lullaby.");
  /* register the document object to the node */
  if(!est_node_put_doc(node, doc))
    fprintf(stderr, "error: %d\n", est_node_status(node));
  /* destroy the document object */
  est_doc_delete(doc);
  /* destroy the node object */
  est_node_delete(node);
  /* free the networking environment */
  est_free_net_env();
  return 0;
}
</pre>

<h3>Example of Searcher</h3>

<p>The following is the simplest implementation of a searcher.</p>

<pre>#include &lt;estraier.h&gt;
#include &lt;estnode.h&gt;
#include &lt;cabin.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;

int main(int argc, char **argv){
  ESTNODE *node;
  ESTCOND *cond;
  ESTNODERES *nres;
  ESTRESDOC *rdoc;
  int i;
  const char *value;
  /* initialize the network environment */
  if(!est_init_net_env()){
    fprintf(stderr, "error: network is unavailable\n");
    return 1;
  }
  /* create the node connection object */
  node = est_node_new("http://localhost:1978/node/test1");
  /* create a search condition object */
  cond = est_cond_new();
  /* set the search phrase to the search condition object */
  est_cond_set_phrase(cond, "rainbow AND lullaby");
  /* get the result of search */
  nres = est_node_search(node, cond, 0);
  if(nres){
    /* for each document in the result */
    for(i = 0; i &lt; est_noderes_doc_num(nres); i++){
      /* get a result document object */
      rdoc = est_noderes_get_doc(nres, i);
      /* display attributes */
      if((value = est_resdoc_attr(rdoc, "@uri")) != NULL)
        printf("URI: %s\n", value);
      if((value = est_resdoc_attr(rdoc, "@title")) != NULL)
        printf("Title: %s\n", value);
      /* display the snippet text */
      printf("%s", est_resdoc_snippet(rdoc));
    }
    /* delete the node result object */
    est_noderes_delete(nres);
  } else {
    fprintf(stderr, "error: %d\n", est_node_status(node));
  }
  /* destroy the search condition object */
  est_cond_delete(cond);
  /* destroy the node object */
  est_node_delete(node);
  /* free the networking environment */
  est_free_net_env();
  return 0;
}
</pre>

<hr />

<h2 id="estcall">Command of a Client</h2>

<p>`estcall' is provided as a client command to manage the node server.  This section describes how to use estcall.</p>

<h3>Synopsis and Description</h3>

<p>estcall is an aggregation of sub commands.  The name of a sub command is specified by the first argument.  Other arguments are parsed according to each sub command.  The argument <var>nurl</var> specifies the URL of a node.  The option -proxy specifies the host name and the port number of a proxy server.  The option -tout specifies timeout in seconds.  The option -auth specifies the user name and the password of authentication information.</p>

<dl>
<dt><kbd>estcall put [-proxy <var>host</var> <var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> [<var>file</var>]</kbd></dt>
<dd>Register a document of document draft to a node.</dd>
<dd><var>file</var> specifies a target file.  If it is omitted, the standard input is read.</dd>
</dl>

<dl>
<dt><kbd>estcall out [-proxy <var>host</var> <var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>expr</var></kbd></dt>
<dd>Remove information of a document from a node.</dd>
<dd><var>expr</var> specifies the ID number or the URI of a document.</dd>
</dl>

<dl>
<dt><kbd>estcall get [-proxy <var>host</var> <var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>expr</var> [<var>attr</var>]</kbd></dt>
<dd>Output document draft of a document in a node.</dd>
<dd><var>expr</var> specifies the ID number or the URI of a document.</dd>
<dd>If <var>attr</var> is specified, only the value of the attribute is output.</dd>
</dl>

<dl>
<dt><kbd>estcall uriid [-proxy <var>host</var> <var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>uri</var></kbd></dt>
<dd>Output the ID number of a document specified by URI.</dd>
<dd><var>uri</var> specifies the URI of a document.</dd>
</dl>

<dl>
<dt><kbd>estcall inform [-proxy <var>host</var> <var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var></kbd></dt>
<dd>Output the name, the label, the number of documents, and the number of unique words of a node.</dd>
</dl>

<dl>
<dt><kbd>estcall search [-proxy <var>host</var> <var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] [-vx] [-sf] [-attr <var>expr</var>] [-ord <var>expr</var>] [-max <var>num</var>] [-dpt <var>num</var>] <var>nurl</var> [<var>phrase</var>]</kbd></dt>
<dd>Search a node for documents.</dd>
<dd><var>phrase</var> specifies the search phrase.</dd>
<dd>If -vx is specified, XML including including attributes and snippets is output.</dd>
<dd>If -sf is specified, the phrase is treated as a simplified form.</dd>
<dd>-attr specifies an attribute search condition.  This option can be specified multiple times.</dd>
<dd>-ord specifies the order expression.  By default, it is descending by score.</dd>
<dd>-max specifies the maximum number of show documents.  Negative means unlimited.  By default, it is 10.</dd>
<dd>-dpt specifies depth of meta search.  by default it is 0.</dd>
</dl>

<dl>
<dt><kbd>estcall setuser [-proxy <var>host</var> <var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>name</var> <var>mode</var></kbd></dt>
<dd>Set permission of a user.</dd>
<dd><var>name</var> specifies the name of a user.</dd>
<dd><var>mode</var> specifies operation mode.  1 means to set the user as an administrator, 2 means to set the user as a normal user, and 0 means to revoke the user account.</dd>
</dl>

<dl>
<dt><kbd>estcall setlink [-proxy <var>host</var> <var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] <var>nurl</var> <var>url</var> <var>label</var> <var>credit</var></kbd></dt>
<dd>Set a link to another node.</dd>
<dd><var>url</var> specifies the URL of a destination node.</dd>
<dd><var>label</var> specifies the label of the link.</dd>
<dd><var>credit</var> specifies the credit of the link.  If the value is negative, the link is removed.</dd>
</dl>

<dl>
<dt><kbd>estcall raw [-proxy <var>host</var> <var>port</var>] [-tout <var>num</var>] [-auth <var>user</var> <var>pass</var>] [-np] [-eh <var>expr</var>] <var>url</var> [<var>file</var>]</kbd></dt>
<dd>Output response of an HTTP request.</dd>
<dd><var>url</var> specifies the URL of a target.</dd>
<dd>If <var>file</var> is specified, the content is sent by POST method.  If not, GET method is used.  If "-" is specified, the standard input is read.</dd>
<dd>If -np is specified, output response headers also.</dd>
<dd>-eh specifies an additional HTTP header.  By default, "Host", "Connection", "User-Agent", and "Content-Length" is added.</dd>
</dl>

<p>All sub commands return 0 if the operation is success, else return 1.</p>

<h3>Examples</h3>

<p>Operations for the node maser itself is not provided as APIs, use the raw sub command for that purpose.  For example, the following command is used in order to shutdown the node master.</p>

<pre>estcall raw -auth admin admin \
  'http://localhost:1978/master?action=shutdown'
</pre>

<p>In order to add a user, perform the following command.</p>

<pre>estcall raw -auth admin admin \
  'http://localhost:1978/master?action=useradd&amp;name=mikio&amp;passwd=iloveyou'
</pre>

<p>In order to use POST method, perform the following command.</p>

<pre>echo -n 'action=useradd&amp;name=mikio&amp;passwd=iloveyou' |
  estcall raw -auth admin admin \
    -eh 'Content-Type: application/x-www-form-urlencoded' \
    'http://localhost:1978/master' -
</pre>

<hr />

</body>

</html>

<!-- END OF FILE -->