trunk/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 2</title>
</head>

<body>

<h1>P2P Guide</h1>

<div class="note">Copyright (C) 2004-2005 Mikio Hirabayashi</div>
<div class="note">Last Update: Tue, 07 Jun 2005 06:17:00 +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 Hyper Estraier's client/server (C/S) and peer to
peer (P2P) architecture.
<br/>
If you haven't read <a href="uguide-en.html">user's guide</a> yet, now is a
good moment to do so.
</p>

<p>There was several problems which where motivation for C/S architecture.
<tt>estseek.cgi</tt> is inefficient because it reconnects to database for each search
query. Database updates using <tt>estcmd</tt> prevents searches on same database
because <em>estcmd</em> uses locks when doing update. To solve those problems,
<tt>estmaster</tt> server process is provided. This is resident (daemon) process
which has control over database and provides services via network.
<br/>
This approach also leads to following advantages:
</p>

<ul>
<li>server and clients can be distributed across different machines</li>
<li>multiple clients and servers can work in parallel</li>
<li>client crash doesn't leave database in inconsistent state</li>
<li>clients implementation isn't specific to any programming language</li>
</ul>

<p>Protocol between clients and servers is based on HTTP, so normal web
browsers can be used as simple clients. Clients can be implemented using any
languages which supports HTTP protocol like JavaScript or Flash.
</p>

<p>Distributed processing is based on peer to peer (P2P) architecture. This
allows horizontal scalability. For example, if you use 10 servers, each with
million documents, you can search 10 million documents without much
additional effort. Since all servers are equal, search service is provided
even if some of servers are unavailable. There is notion of relevance of
each index which can improve search results (if some parts of index are more
important that others).
</p>

<p class="note">
Relevance was called reliability in previous version of this document.
</p>

<p>This document describes node API which can be used by client applications
to implement search capabilities without using network protocol between
client and server.
</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>When using multiple indexes it is highly inefficient to run one server for each
index. <em>estmaster</em> is server process (daemon) implemented as single process
available on network through HTTP protocol on some hight port that provides
services for multiple indexes. This component is called <em>node master</em>.
Each index has it's own unique URL which is served by <em>node server</em>.
<br/>
You can think about <em>node server</em> as a virtual servers for each index
within one <em>node master</em>.
</p>

<div class="illust"><img src="nodeframe.png" width="720" height="350" alt="[framework]" /></div>
<p>
Client application just need to know URL of <em>node server</em> and issue queries to it on any available <em>node masters</em>. Term <em>node</em> corresponds to <em>peer</em> in P2P architecture.
Clients can also connect to <em>node masters</em> directly to manage
configuration of that master.
</p>

<h3>Meta Search and Credit</h3>

<p>Each <em>node server</em> can have uni-directional links to other
<em>node servers</em>. This allows distributed searching called <em>meta
search</em>. When client sends query to <em>node server</em>, it will
forward that query to all other <em>node servers</em> and merge responses
before sending result back to client. This allows distributed processing of
search queries.
</p>

<p>Meta search is performed hierarchically. Loops in links are detected and
restrained automatically, so searching is always
performed on tree structured network of nodes. This allows infinite scalability
just by adding additional nodes.</p>

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

<p>There is a notion of relevance for each link between nodes called
<em>credit</em>. It's used for weighting of scores when merging results
from different nodes.
<br/>
Document coming from node with larger <em>credit</em> will have higher rank
in search results. Application can set links and credits for them, and this
allows improving of search precision by modifying credits of frequently used
nodes.
</p>

<h3>Authentication</h3>

<p>Client connections to <em>node master</em> or <em>node server</em>
are authenticated using logins and passwords.
Users and permissions are defined on
<em>node masters</em> and all <em>node servers</em> on that master inherit those
permissions.
<br/>
Users are divided into two groups: super users and normal users. Normal uses
have permission to search index while super users also have permission to
create and update indexes.
</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 adminisration 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 prapare 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 finishs with closing the database when it catchs 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 sould 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:
trustednodes:
denyuntrusted: 0
cachesize: 64
specialcache:
snipwwidth: 480
sniphwidth: 96
snipawidth: 96
</pre>

<p>Means 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>trustednodes</kbd> : specifies decimal IP addresses of trusted nodes (list separated by comma).</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>
</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.  Authority 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 : authority 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 essantial.</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 docuemnt.  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 entitiy 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 correspondign 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.</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 entitiy 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 autority */
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_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_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 authoririty 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 an authority.  `passwd' specifies the password of the authority.</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 spacified 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 datbase 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 datbase 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 entitiy 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 entitiy 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 eath thread have its own objects.  If the precondition is kept, functions of the node API can be treated as thread-safe functions.</p>

<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 authority 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>Outout 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] [-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>-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>Outout 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 standart 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 -->