-## $Id: Makefile.am,v 1.38 2003-02-21 00:24:26 adam Exp $
+## $Id: Makefile.am,v 1.39 2003-02-21 12:06:05 adam Exp $
docdir=$(datadir)/doc/@PACKAGE@
XMLFILES=yaz.xml.in introduction.xml installation.xml indexdata.xml \
asn.xml tools.xml odr.xml comstack.xml frontend.xml license.xml \
future.xml client.xml zoom.xml credits.xml ztest-options.xml \
- yaz-client-commands.xml
+ yaz-client-commands.xml soap.xml
HTMLFILES = \
asn.external.html asn.html asn.oid.html asn.pdu.html asn.preparing.html \
license.html license.other.html odr.debugging.html odr.html \
odr.programming.html odr.use.html server.backendfunctions.html \
server.backend.html server.frontend.html server.html server.invocation.html \
- server.main.html tools.html tools.nmem.html tools.oid.html yaz.html \
+ server.main.html soap.html soap.http.html soap.xml.html \
+ tools.html tools.nmem.html tools.oid.html yaz.html \
zoom.events.html zoom.html zoom.options.html zoom.query.html \
zoom.records.html zoom.resultsets.html zoom.scan.html
-<!-- $Id: comstack.xml,v 1.9 2002-08-17 07:55:51 adam Exp $ -->
+<!-- $Id: comstack.xml,v 1.10 2003-02-21 12:06:05 adam Exp $ -->
<chapter id="comstack"><title>The COMSTACK Module</title>
<sect1 id="comstack.synopsis"><title>Synopsis (blocking mode)</title>
<para>
The &comstack;
subsystem provides a transparent interface to different types of transport
- stacks for the exchange of BER-encoded data. At present, the
- RFC1729 method (BER over TCP/IP), local UNIX socket and an
+ stacks for the exchange of BER-encoded data and HTTP packets.
+ At present, the RFC1729 method (BER over TCP/IP), local UNIX socket and an
experimental SSL stack are supported, but others may be added in time.
The philosophy of the
module is to provide a simple interface by hiding unused options and
<variablelist>
<varlistentry><term><literal>tcpip_type</literal></term>
- <listitem><para>TCP/IP (BER over TCP/IP)
+ <listitem><para>TCP/IP (BER over TCP/IP or HTTP over TCP/IP)
</para></listitem>
</varlistentry>
<varlistentry><term><literal>ssl_type</literal></term>
<listitem><para>Secure Socket Layer (SSL). This COMSTACK
- is experimental and is not fully implemented.
+ is experimental and is not fully implemented. If
+ HTTP is used, this effectively is HTTPS.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>unix_type</literal></term>
- <listitem><para>Unix socket (unix only). Fast local transfer via
+ <listitem><para>Unix socket (unix only). Local Transfer via
file socket. See <citerefentry><refentrytitle>unix</refentrytitle>
<manvolnum>7</manvolnum></citerefentry>.
</para></listitem>
The <literal>blocking</literal> parameter should be one if
you wish the association to operate in blocking mode, zero otherwise.
The <literal>protocol</literal> field should be
- <literal>PROTO_Z3950</literal>.
+ <literal>PROTO_Z3950</literal> or <literal>PROTO_HTTP</literal>.
Protocol <literal>PROTO_SR</literal> is no longer supported.
</para>
</synopsis>
<para>
- Receives a PDU from the peer. Returns the number of bytes read.
+ Receives a PDU or HTTP Response from the peer. Returns the number of
+ bytes read.
In nonblocking mode, it is possible that not all of the packet can be
read at once. In this case, the function returns 1. To simplify the
interface, the function is
-<!-- $Id: future.xml,v 1.7 2002-09-17 20:17:44 adam Exp $ -->
+<!-- $Id: future.xml,v 1.8 2003-02-21 12:06:05 adam Exp $ -->
<chapter id="future"><title>Future Directions</title>
<para>
</para>
<para>
- The 'retrieval' module needs to be finalized and documented. We think
- it can form a useful resource for people dealing with complex record
- structures, but for now, you'll mostly have to chew through the code
- yourself to make use of it. Not acceptable.
- </para>
-
- <para>
&yaz; is a BER toolkit and as such should support all protocols
out there based on that. We'd like to see running ILL applications.
It shouldn't be that hard. Another thing that would be interesting is
</para>
<para>
+ The SOAP implementation is incomplete. In the future we hope
+ to add more features to it. Perhaps make a WSDL/XML Schema compiler.
+ The authors of libxml2 are already working on XML Schema / RelagNG
+ compilers so this may not be too hard.
+ </para>
+
+ <para>
+ It would be neat to have a proper module mechanism for the Generic
+ Frontend Server so that backend would be dynamically
+ loaded (as shared objects / DLLs).
+ </para>
+
+ <para>
Other than that, &yaz; generally moves in the directions which appear to
make the most people happy (including ourselves, as prime users of the
software). If there's something you'd like to see in here, then drop
us a note and let's see what we can come up with.
</para>
+
</chapter>
<!-- Keep this comment at the end of the file
-<!-- $Id: introduction.xml,v 1.9 2003-02-21 00:24:26 adam Exp $ -->
+<!-- $Id: introduction.xml,v 1.10 2003-02-21 12:06:05 adam Exp $ -->
<chapter id="introduction"><title>Introduction</title>
<para>
<para>
<xref linkend="asn"/> documents the most commonly used Z39.50
C data structures offered by the &yaz; API. Client
- developers using ZOOM you do not need reading this.
- For the remaining client developers (not using ZOOM),
- reading this chapter is a must.
- Z39.50 server implementors should read this, unless you're
- developing a simple server (or SRW only).
+ developers using ZOOM and non-Z39.50 implementors may skip this.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="soap"/> describes how SRW and SOAP is used
+ in &yaz;. Only if you're developing SOAP/SRW applications
+ this section is a must.
</para>
</listitem>
--- /dev/null
+<!-- $Id: soap.xml,v 1.1 2003-02-21 12:06:05 adam Exp $ -->
+<chapter id="soap"><title>SOAP and SRW</title>
+ <sect1 id="soap.introduction"><title>Introduction</title>
+ <para>
+ &yaz; uses a very simple implementation of SOAP that only,
+ currenly, supports what is sufficient to offer SRW functionality.
+ The implementation uses the
+ <ulink url="http://www.xmlsoft.org/html/libxml-tree.html">tree
+ API</ulink> of libxml2 to encode and decode SOAP packages.
+ </para>
+ <para>
+ Like the Z39.50 ASN.1 module, the &yaz; SRW implementation uses
+ simple C structs to represent SOAP packages as well as
+ HTTP packages.
+ </para>
+ </sect1>
+ <sect1 id="soap.http"><title>HTTP</title>
+ <para>
+ &yaz; only offers HTTP as transport carrier for SOAP, but it is
+ relatively easy to change that.
+ </para>
+ <para>
+ The following definition of <literal>Z_GDU</literal> (Generic Data
+ Unit) allows for both HTTP and Z39.50 in one packet.
+ </para>
+ <synopsis>
+#include <yaz/zgdu.h>
+
+#define Z_GDU_Z3950 1
+#define Z_GDU_HTTP_Request 2
+#define Z_GDU_HTTP_Response 3
+typedef struct {
+ int which;
+ union {
+ Z_APDU *z3950;
+ Z_HTTP_Request *HTTP_Request;
+ Z_HTTP_Response *HTTP_Response;
+ } u;
+} Z_GDU ;
+ </synopsis>
+ <para>
+ The corresponding Z_GDU encoder/decoder is <function>z_GDU</function>.
+ The <literal>z3950</literal> is any of the known BER encoded Z39.50
+ APDUs.
+ <literal>HTTP_Request</literal> and <literal>HTTP_Response</literal>
+ is the HTTP Request and Response respectively.
+ </para>
+ </sect1>
+ <sect1 id="soap.xml"><title>SOAP Packages</title>
+ <para>
+ Every SOAP package in &yaz; is represented as follows:
+ <synopsis>
+#include <yaz/soap.h>
+
+typedef struct {
+ char *fault_code;
+ char *fault_string;
+ char *details;
+} Z_SOAP_Fault;
+
+typedef struct {
+ int no;
+ char *ns;
+ void *p;
+} Z_SOAP_Generic;
+
+#define Z_SOAP_fault 1
+#define Z_SOAP_generic 2
+#define Z_SOAP_error 3
+typedef struct {
+ int which;
+ union {
+ Z_SOAP_Fault *fault;
+ Z_SOAP_Generic *generic;
+ Z_SOAP_Fault *soap_error;
+ } u;
+ const char *ns;
+} Z_SOAP;
+ </synopsis>
+ </para>
+ <para>
+ The <literal>fault</literal> and <literal>soap_error</literal>
+ arms represent both a SOAP fault - struct
+ <literal>Z_SOAP_Fault</literal>. Any other generic
+ (valid) package is represented by <literal>Z_SOAP_Generic</literal>.
+ </para>
+ <para>
+ The <literal>ns</literal> as part of <literal>Z_SOAP</literal>
+ is the namespace for SOAP itself and reflects the SOAP
+ version. For version 1.1 it is
+ <literal>http://schemas.xmlsoap.org/soap/envelope/</literal>,
+ for version 1.2 it is
+ <literal>http://www.w3.org/2001/06/soap-envelope</literal>.
+ </para>
+ <synopsis>
+int z_soap_codec(ODR o, Z_SOAP **pp,
+ char **content_buf, int *content_len,
+ Z_SOAP_Handler *handlers);
+ </synopsis>
+ <para>
+ The <literal>content_buf</literal> and <literal>content_len</literal>
+ is XML buffer and length of buffer respectively.
+ </para>
+ <para>
+ The <literal>handlers</literal> is a list of SOAP services codec
+ handlers - one handler for each service namespace. For SRW, the
+ namespace is http://www.loc.gov/zing/srw/v1.0/.
+ </para>
+ <para>
+ Each handler is define as follows:
+ <synopsis>
+typedef struct {
+ char *ns;
+ void *client_data;
+ Z_SOAP_fun f;
+} Z_SOAP_Handler;
+ </synopsis>
+ The <literal>ns</literal> is namespace of service associated with
+ handler <literal>f</literal>. <literal>client_data</literal>
+ is user-defined data which is passed to handler.
+ </para>
+ <para>
+ The prototype for a handler is:
+ <synopsis>
+int handler(ODR o, void * ptr, void **handler_data,
+ void *client_data, const char *ns);
+ </synopsis>
+ </para>
+ </sect1>
+ <sect1><title>SRW</title>
+ <para>
+ SRW is just one kind of SOAP handler as described in the previous
+ section.
+ <synopsis>
+#include <yaz/soap.h>
+
+typedef struct {
+ char *recordSchema;
+ char *recordData_buf;
+ int recordData_len;
+ int *recordPosition;
+} Z_SRW_record;
+
+typedef struct {
+ int *code;
+ char *details;
+} Z_SRW_diagnostic;
+
+typedef struct {
+ char *query;
+ char *pQuery;
+ void *xQuery;
+ char *sortKeys;
+ void *xSortKeys;
+ int *startRecord;
+ int *maximumRecords;
+ char *recordSchema;
+ char *recordPacking;
+ char *database;
+} Z_SRW_searchRetrieveRequest;
+
+typedef struct {
+ int * numberOfRecords;
+ char * resultSetId;
+ int * resultSetIdleTime;
+
+ Z_SRW_record *records;
+ int num_records;
+
+ Z_SRW_diagnostic *diagnostics;
+ int num_diagnostics;
+ int *nextRecordPosition;
+} Z_SRW_searchRetrieveResponse;
+
+#define Z_SRW_searchRetrieve_request 1
+#define Z_SRW_searchRetrieve_response 2
+
+typedef struct {
+ int which;
+ union {
+ Z_SRW_searchRetrieveRequest *request;
+ Z_SRW_searchRetrieveResponse *response;
+ } u;
+} Z_SRW_searchRetrieve;
+ </synopsis>
+ [more to be written]
+ </para>
+ </sect1>
+</chapter>
+
<!ENTITY chap-zoom SYSTEM "zoom.xml">
<!ENTITY chap-client SYSTEM "client.xml">
<!ENTITY chap-asn SYSTEM "asn.xml">
+ <!ENTITY chap-soap SYSTEM "soap.xml">
<!ENTITY chap-tools SYSTEM "tools.xml">
<!ENTITY chap-odr SYSTEM "odr.xml">
<!ENTITY chap-comstack SYSTEM "comstack.xml">
<!ENTITY comstack "<acronym>COMSTACK</acronym>">
<!ENTITY zoom "<acronym>ZOOM</acronym>">
]>
-<!-- $Id: yaz.xml.in,v 1.8 2003-02-21 00:24:26 adam Exp $ -->
+<!-- $Id: yaz.xml.in,v 1.9 2003-02-21 12:06:05 adam Exp $ -->
<book id="yaz">
<bookinfo>
<title>YAZ User's Guide and Reference</title>
&chap-frontend;
&chap-client;
&chap-asn;
+ &chap-soap;
&chap-tools;
&chap-odr;
&chap-comstack;
projects / yaz-moved-to-github.git / commitdiff