doc/soap.xml

   1 <!-- $Id: soap.xml,v 1.1 2003-02-21 12:06:05 adam Exp $ -->
   2 <chapter id="soap"><title>SOAP and SRW</title>
   3   <sect1 id="soap.introduction"><title>Introduction</title>
   4     <para>
   5       &yaz; uses a very simple implementation of SOAP that only,
   6       currenly, supports what is sufficient to offer SRW functionality.
   7       The implementation uses the
   8       <ulink url="http://www.xmlsoft.org/html/libxml-tree.html">tree
   9         API</ulink> of libxml2 to encode and decode SOAP packages.
  10     </para>
  11     <para>
  12       Like the Z39.50 ASN.1 module, the &yaz; SRW implementation uses
  13       simple C structs to represent SOAP packages as well as
  14       HTTP packages.
  15     </para>
  16   </sect1>
  17   <sect1 id="soap.http"><title>HTTP</title>
  18     <para>
  19       &yaz; only offers HTTP as transport carrier for SOAP, but it is
  20       relatively easy to change that.
  21     </para>
  22     <para>
  23       The following definition of <literal>Z_GDU</literal> (Generic Data
  24       Unit) allows for both HTTP and Z39.50 in one packet.
  25     </para>
  26     <synopsis>
  27 #include &lt;yaz/zgdu.h&gt;
  28
  29 #define Z_GDU_Z3950         1
  30 #define Z_GDU_HTTP_Request  2
  31 #define Z_GDU_HTTP_Response 3
  32 typedef struct {
  33   int which;
  34   union {
  35     Z_APDU *z3950;
  36     Z_HTTP_Request *HTTP_Request;
  37     Z_HTTP_Response *HTTP_Response;
  38   } u;
  39 } Z_GDU ;
  40     </synopsis>
  41     <para>
  42       The corresponding Z_GDU encoder/decoder is <function>z_GDU</function>.
  43       The <literal>z3950</literal> is any of the known BER encoded Z39.50
  44       APDUs.
  45       <literal>HTTP_Request</literal> and <literal>HTTP_Response</literal>
  46       is the HTTP Request and Response respectively.
  47     </para>
  48   </sect1>
  49   <sect1 id="soap.xml"><title>SOAP Packages</title>
  50     <para>
  51       Every SOAP package in &yaz; is represented as follows:
  52       <synopsis>
  53 #include &lt;yaz/soap.h&gt;
  54
  55 typedef struct {
  56     char *fault_code;
  57     char *fault_string;
  58     char *details;
  59 } Z_SOAP_Fault;
  60
  61 typedef struct {
  62     int no;
  63     char *ns;
  64     void *p;
  65 } Z_SOAP_Generic;
  66
  67 #define Z_SOAP_fault 1
  68 #define Z_SOAP_generic 2
  69 #define Z_SOAP_error 3
  70 typedef struct {
  71     int which;
  72     union {
  73         Z_SOAP_Fault   *fault;
  74         Z_SOAP_Generic *generic;
  75         Z_SOAP_Fault   *soap_error;
  76     } u;
  77     const char *ns;
  78 } Z_SOAP;
  79       </synopsis>
  80     </para>
  81     <para>
  82       The <literal>fault</literal> and <literal>soap_error</literal>
  83       arms represent both a SOAP fault - struct
  84       <literal>Z_SOAP_Fault</literal>. Any other generic
  85         (valid) package is represented by <literal>Z_SOAP_Generic</literal>.
  86     </para>
  87     <para>
  88       The <literal>ns</literal> as part of <literal>Z_SOAP</literal>
  89       is the namespace for SOAP itself and reflects the SOAP
  90       version. For version 1.1 it is
  91       <literal>http://schemas.xmlsoap.org/soap/envelope/</literal>,
  92       for version 1.2 it is
  93       <literal>http://www.w3.org/2001/06/soap-envelope</literal>.
  94     </para>
  95     <synopsis>
  96 int z_soap_codec(ODR o, Z_SOAP **pp,
  97                  char **content_buf, int *content_len,
  98                  Z_SOAP_Handler *handlers);
  99     </synopsis>
 100     <para>
 101       The <literal>content_buf</literal>  and <literal>content_len</literal>
 102       is XML buffer and length of buffer respectively.
 103     </para>
 104     <para>
 105       The <literal>handlers</literal> is a list of SOAP services codec
 106       handlers - one handler for each service namespace. For SRW, the
 107       namespace is http://www.loc.gov/zing/srw/v1.0/.
 108     </para>
 109     <para>
 110       Each handler is define as follows:
 111       <synopsis>
 112 typedef struct {
 113     char *ns;
 114     void *client_data;
 115     Z_SOAP_fun f;
 116 } Z_SOAP_Handler;
 117       </synopsis>
 118       The <literal>ns</literal> is namespace of service associated with
 119       handler <literal>f</literal>. <literal>client_data</literal>
 120       is user-defined data which is passed to handler.
 121     </para>
 122     <para>
 123       The prototype for a handler is:
 124       <synopsis>
 125 int handler(ODR o, void * ptr, void **handler_data,
 126             void *client_data, const char *ns);
 127       </synopsis>
 128     </para>
 129   </sect1>
 130   <sect1><title>SRW</title>
 131     <para>
 132       SRW is just one kind of SOAP handler as described in the previous
 133       section.
 134       <synopsis>
 135 #include &lt;yaz/soap.h&gt;
 136
 137 typedef struct {
 138     char *recordSchema;
 139     char *recordData_buf;
 140     int recordData_len;
 141     int *recordPosition;
 142 } Z_SRW_record;
 143
 144 typedef struct {
 145     int  *code;
 146     char *details;
 147 } Z_SRW_diagnostic;
 148
 149 typedef struct {
 150     char *query;
 151     char *pQuery;
 152     void *xQuery;
 153     char *sortKeys;
 154     void *xSortKeys;
 155     int *startRecord;
 156     int  *maximumRecords;
 157     char *recordSchema;
 158     char *recordPacking;
 159     char *database;
 160 } Z_SRW_searchRetrieveRequest;
 161
 162 typedef struct {
 163     int * numberOfRecords;
 164     char * resultSetId;
 165     int * resultSetIdleTime;
 166
 167     Z_SRW_record *records;
 168     int num_records;
 169
 170     Z_SRW_diagnostic *diagnostics;
 171     int num_diagnostics;
 172     int *nextRecordPosition;
 173 } Z_SRW_searchRetrieveResponse;
 174
 175 #define Z_SRW_searchRetrieve_request  1
 176 #define Z_SRW_searchRetrieve_response 2
 177
 178 typedef struct {
 179     int which;
 180     union {
 181         Z_SRW_searchRetrieveRequest *request;
 182         Z_SRW_searchRetrieveResponse *response;
 183     } u;
 184 } Z_SRW_searchRetrieve;
 185       </synopsis>
 186       [more to be written]
 187     </para>
 188   </sect1>
 189 </chapter>
 190