X-Git-Url: http://lists.indexdata.com/cgi-bin?a=blobdiff_plain;ds=sidebyside;f=doc%2Fpazpar2_protocol.xml;h=7befc4082ad1e225fe97ee4f8f9d58be71b00ebf;hb=52793fbdcc6099f1c86e0b4c2c918767c22f7bcc;hp=155722ae67dadf54eca893318d850a3ab0f34cf6;hpb=b79fcd31650cec9ae118adaefbaa2dd6cbcc5d66;p=pazpar2-moved-to-github.git

diff --git a/doc/pazpar2_protocol.xml b/doc/pazpar2_protocol.xml
index 155722a..7befc40 100644
--- a/doc/pazpar2_protocol.xml
+++ b/doc/pazpar2_protocol.xml
@@ -5,10 +5,10 @@
      %local;
      <!ENTITY % entities SYSTEM "entities.ent">
      %entities;
-     <!ENTITY % common SYSTEM "common/common.ent">
-     %common;
+     <!ENTITY % idcommon SYSTEM "common/common.ent">
+     %idcommon;
 ]>
-<!-- $Id: pazpar2_protocol.xml,v 1.5 2007-04-10 08:53:48 adam Exp $ -->
+<!-- $Id: pazpar2_protocol.xml,v 1.10 2007-06-28 09:36:11 adam Exp $ -->
 <refentry id="pazpar2_protocol">
  <refentryinfo>
   <productname>Pazpar2</productname>
@@ -33,7 +33,7 @@
    using the proxy setting.
    This way, a regular webserver can host the user interface (itself dynamic
    or static HTML), and AJAX-style calls can be used from JS (or any other client-based
-   scripting environment) to interact with the search logic in pazpar2. 
+   scripting environment) to interact with the search logic in Pazpar2. 
   </para>
   <para>
    Each command is described in sub sections to follow.
@@ -58,6 +58,23 @@
      <session>2044502273</session>
     </init>
 ]]></screen>
+   <para>
+     The init command may take a number of setting parameters, similar to
+     the 'settings' command described below. These settings are immediately
+     applied to the new session. Other parameters for init are:
+    <variablelist>
+     <varlistentry>
+      <term>clear</term>
+      <listitem>
+       <para>
+	If this is defined and the value is non-zero, the session will
+	not use the predefined databases in the configuration; only those
+	specified in the settings parameters (per session databases).
+	</para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
   </refsect2>
   
   <refsect2 id="command-ping"><title>ping</title>
@@ -82,10 +99,52 @@
 ]]></screen>
    </para>
   </refsect2>
+  <refsect2 id="command-settings">
+   <title>settings</title>
+   <para>
+    The settings command applies session-specific settings to one or more
+    databases. A typical function of this is to enable access to
+    restricted resources for registered users, or to set a user- or
+    library-specific username/password to use against a target. Each
+    setting parameter has the form name[target]=value, where name is the
+    name of the setting (e.g. pz:authentication), target is a target ID,
+    or possibly a wildcard, and value is the desired value for the
+    setting.
+   </para>
+   
+   <para>
+    Because the settings command manipulates potentially sensitive
+    information, it is possible to configure Pazpar2 to only allow access
+    to this command from a trusted site -- usually from server-side
+    scripting, which in turn is responsible for authenticating the user,
+    and possibly determining which resources he has access to, etc.
+   </para>
+   
+   <note>
+    <para>
+     As a shortcut, it is also possible to override settings directly in
+     the init command.
+    </para>
+   </note>
+   
+   <para>
+    Example:
+    <screen><![CDATA[
+       search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
+      ]]></screen>
+    Response:
+   <screen><![CDATA[
+<settings>
+  <status>OK</status>
+</settings>
+]]></screen>
+    </para>
+
+  </refsect2>
   <refsect2 id="command-search"><title>search</title>
    <para>
     Launches a search, parameters:
-
+    
     <variablelist>
      <varlistentry>
       <term>session</term>
@@ -205,19 +264,19 @@ search.pz2?session=2044502273&command=stat
      </varlistentry>
 
      <varlistentry>
-       <term>sort</term>
-       <listitem>
-         <para>
-	   Specifies sort criteria. The argument is a comma-separated list
-	   (no whitespace allowed) of sort fields, with the highest-priority
-	   field first. A sort field may be followed by a colon followed by
-	   the number '0' or '1', indicating whether results should be sorted in
-	   increasing or decreasing order according to that field. 0==Decreasing is
-	   the default.
-	 </para>
-	</listitem>
-      </varlistentry>
-
+      <term>sort</term>
+      <listitem>
+       <para>
+	Specifies sort criteria. The argument is a comma-separated list
+	(no whitespace allowed) of sort fields, with the highest-priority
+	field first. A sort field may be followed by a colon followed by
+	the number '0' or '1', indicating whether results should be sorted in
+	increasing or decreasing order according to that field. 0==Decreasing is
+	the default.
+       </para>
+      </listitem>
+     </varlistentry>
+     
     </variablelist>
    </para>
    <para>
@@ -262,7 +321,7 @@ search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
       <listitem>
        <para>
 	Session ID
-	</para>
+       </para>
       </listitem>
      </varlistentry>
 
@@ -369,7 +428,7 @@ Output:
       <term>session</term>
       <listitem>
        <para>
-          Session Id.
+	Session Id.
 	</para>
       </listitem>
      </varlistentry>
@@ -396,11 +455,11 @@ search.pz2?session=605047297&command=record&id=3
   <!-- ... more target nodes below as necessary -->
 </bytarget>
 ]]></screen>
-
-   The following client states are defined: Client_Connecting,
-   Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
-   Client_Searching, Client_Presenting, Client_Error, Client_Failed,
-   Client_Disconnected, Client_Stopped.
+    
+    The following client states are defined: Client_Connecting,
+    Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
+    Client_Searching, Client_Presenting, Client_Error, Client_Failed,
+    Client_Disconnected, Client_Stopped.
    </para>
   </refsect2>