doc/soap.xml

   1 <!-- $Id: soap.xml,v 1.7 2006-06-13 16:01:51 adam Exp $ -->
   2 <chapter id="soap"><title>SOAP and SRU</title>
   3   <sect1 id="soap.introduction"><title>Introduction</title>
   4     <para>
   5       &yaz; uses a very simple implementation of
   6       <ulink url="&url.soap;">SOAP</ulink> that only,
   7       currenly, supports what is sufficient to offer SRU SOAP functionality.
   8       The implementation uses the
   9       <ulink url="&url.libxml2.api.tree;">tree API</ulink> of
  10       libxml2 to encode and decode SOAP packages.
  11     </para>
  12     <para>
  13       Like the Z39.50 ASN.1 module, the &yaz; SRU implementation uses
  14       simple C structs to represent SOAP packages as well as
  15       HTTP packages.
  16     </para>
  17   </sect1>
  18   <sect1 id="soap.http"><title>HTTP</title>
  19     <para>
  20       &yaz; only offers HTTP as transport carrier for SOAP, but it is
  21       relatively easy to change that.
  22     </para>
  23     <para>
  24       The following definition of <literal>Z_GDU</literal> (Generic Data
  25       Unit) allows for both HTTP and Z39.50 in one packet.
  26     </para>
  27     <synopsis>
  28 #include &lt;yaz/zgdu.h&gt;
  29
  30 #define Z_GDU_Z3950         1
  31 #define Z_GDU_HTTP_Request  2
  32 #define Z_GDU_HTTP_Response 3
  33 typedef struct {
  34   int which;
  35   union {
  36     Z_APDU *z3950;
  37     Z_HTTP_Request *HTTP_Request;
  38     Z_HTTP_Response *HTTP_Response;
  39   } u;
  40 } Z_GDU ;
  41     </synopsis>
  42     <para>
  43       The corresponding Z_GDU encoder/decoder is <function>z_GDU</function>.
  44       The <literal>z3950</literal> is any of the known BER encoded Z39.50
  45       APDUs.
  46       <literal>HTTP_Request</literal> and <literal>HTTP_Response</literal>
  47       is the HTTP Request and Response respectively.
  48     </para>
  49   </sect1>
  50   <sect1 id="soap.xml"><title>SOAP Packages</title>
  51     <para>
  52       Every SOAP package in &yaz; is represented as follows:
  53       <synopsis>
  54 #include &lt;yaz/soap.h&gt;
  55
  56 typedef struct {
  57     char *fault_code;
  58     char *fault_string;
  59     char *details;
  60 } Z_SOAP_Fault;
  61
  62 typedef struct {
  63     int no;
  64     char *ns;
  65     void *p;
  66 } Z_SOAP_Generic;
  67
  68 #define Z_SOAP_fault 1
  69 #define Z_SOAP_generic 2
  70 #define Z_SOAP_error 3
  71 typedef struct {
  72     int which;
  73     union {
  74         Z_SOAP_Fault   *fault;
  75         Z_SOAP_Generic *generic;
  76         Z_SOAP_Fault   *soap_error;
  77     } u;
  78     const char *ns;
  79 } Z_SOAP;
  80       </synopsis>
  81     </para>
  82     <para>
  83       The <literal>fault</literal> and <literal>soap_error</literal>
  84       arms represent both a SOAP fault - struct
  85       <literal>Z_SOAP_Fault</literal>. Any other generic
  86         (valid) package is represented by <literal>Z_SOAP_Generic</literal>.
  87     </para>
  88     <para>
  89       The <literal>ns</literal> as part of <literal>Z_SOAP</literal>
  90       is the namespace for SOAP itself and reflects the SOAP
  91       version. For version 1.1 it is
  92       <literal>http://schemas.xmlsoap.org/soap/envelope/</literal>,
  93       for version 1.2 it is
  94       <literal>http://www.w3.org/2001/06/soap-envelope</literal>.
  95     </para>
  96     <synopsis>
  97 int z_soap_codec(ODR o, Z_SOAP **pp,
  98                  char **content_buf, int *content_len,
  99                  Z_SOAP_Handler *handlers);
 100     </synopsis>
 101     <para>
 102       The <literal>content_buf</literal> and <literal>content_len</literal>
 103       is XML buffer and length of buffer respectively.
 104     </para>
 105     <para>
 106       The <literal>handlers</literal> is a list of SOAP codec
 107       handlers - one handler for each service namespace. For SRU SOAP, the
 108       namespace would be <literal>http://www.loc.gov/zing/srw/v1.0/</literal>.
 109     </para>
 110     <para>
 111       When decoding, the <function>z_soap_codec</function>
 112       inspects the XML content
 113       and tries to match one of the services namespaces of the
 114       supplied handlers. If there is a match a handler function
 115       is invoked which decodes that particular SOAP package.
 116       If successful, the returned <literal>Z_SOAP</literal> package will be
 117       of type <literal>Z_SOAP_Generic</literal>.
 118       Member <literal>no</literal> is
 119       set the offset of handler that matched; <literal>ns</literal>
 120       is set to namespace of matching handler; the void pointer
 121       <literal>p</literal> is set to the C data structure assocatiated
 122       with the handler.
 123     </para>
 124     <para>
 125       When a NULL namespace is met (member <literal>ns</literal> bwlow),
 126       that specifies end-of-list.
 127     </para>
 128     <para>
 129       Each handler is defined as follows:
 130       <synopsis>
 131 typedef struct {
 132     char *ns;
 133     void *client_data;
 134     Z_SOAP_fun f;
 135 } Z_SOAP_Handler;
 136       </synopsis>
 137       The <literal>ns</literal> is namespace of service associated with
 138       handler <literal>f</literal>. <literal>client_data</literal>
 139       is user-defined data which is passed to handler.
 140     </para>
 141     <para>
 142       The prototype for a SOAP service handler is:
 143       <synopsis>
 144 int handler(ODR o, void * ptr, void **handler_data,
 145             void *client_data, const char *ns);
 146       </synopsis>
 147       The <parameter>o</parameter> specifies the mode (decode/encode)
 148       as usual. The second argument, <parameter>ptr</parameter>,
 149       is a libxml2 tree node pointer (<literal>xmlNodePtr</literal>)
 150       and is a pointer to the <literal>Body</literal> element
 151       of the SOAP package. The <parameter>handler_data</parameter>
 152       is an opaque pointer to a C definitions associated with the
 153       SOAP service. <parameter>client_data</parameter> is the pointer
 154       which was set as part of the <literal>Z_SOAP_handler</literal>.
 155       Finally, <parameter>ns</parameter> the service namespace.
 156     </para>
 157   </sect1>
 158   <sect1 id="soap.srw"><title>SRU</title>
 159     <para>
 160       SRU SOAP is just one implementation of a SOAP handler as described
 161       in the previous section.
 162       The encoder/decoder handler for SRU is defined as
 163       follows:
 164       <synopsis>
 165 #include &lt;yaz/srw.h&gt;
 166
 167 int yaz_srw_codec(ODR o, void * pptr,
 168                   Z_SRW_GDU **handler_data,
 169                   void *client_data, const char *ns);
 170       </synopsis>
 171       Here, <literal>Z_SRW_GDU</literal> is either
 172       searchRetrieveRequest or a searchRetrieveResponse.
 173     </para>
 174     <note>
 175       <para>
 176         The xQuery and xSortKeys are not handled yet by
 177         the SRW implementation of &yaz;. Explain is also missing.
 178         Future versions of &yaz; will include these features.
 179       </para>
 180     </note>
 181     <para>
 182       The definition of searchRetrieveRequest is:
 183       <synopsis>
 184 typedef struct {
 185
 186 #define Z_SRW_query_type_cql  1
 187 #define Z_SRW_query_type_xcql 2
 188 #define Z_SRW_query_type_pqf  3
 189     int query_type;
 190     union {
 191         char *cql;
 192         char *xcql;
 193         char *pqf;
 194     } query;
 195
 196 #define Z_SRW_sort_type_none 1
 197 #define Z_SRW_sort_type_sort 2
 198 #define Z_SRW_sort_type_xSort 3
 199     int sort_type;
 200     union {
 201         char *none;
 202         char *sortKeys;
 203         char *xSortKeys;
 204     } sort;
 205     int  *startRecord;
 206     int  *maximumRecords;
 207     char *recordSchema;
 208     char *recordPacking;
 209     char *database;
 210 } Z_SRW_searchRetrieveRequest;
 211       </synopsis>
 212       Please observe that data of type xsd:string is represented
 213       as a char pointer (<literal>char *</literal>). A null pointer
 214       means that the element is absent.
 215       Data of type xsd:integer is representd as a pointer to
 216       an int (<literal>int *</literal>). Again, a null pointer
 217       us used for absent elements.
 218     </para>
 219     <para>
 220       The SearchRetrieveResponse has the following definition.
 221       <synopsis>
 222 typedef struct {
 223     int * numberOfRecords;
 224     char * resultSetId;
 225     int * resultSetIdleTime;
 226
 227     Z_SRW_record *records;
 228     int num_records;
 229
 230     Z_SRW_diagnostic *diagnostics;
 231     int num_diagnostics;
 232     int *nextRecordPosition;
 233 } Z_SRW_searchRetrieveResponse;
 234       </synopsis>
 235       The <literal>num_records</literal> and <literal>num_diagnostics</literal>
 236       is number of returned records and diagnostics respectively and also
 237       correspond to the "size of" arrays <literal>records</literal>
 238       and <literal>diagnostics</literal>.
 239     </para>
 240     <para>
 241       A retrieval record is defined as follows:
 242       <synopsis>
 243 typedef struct {
 244     char *recordSchema;
 245     char *recordData_buf;
 246     int recordData_len;
 247     int *recordPosition;
 248 } Z_SRW_record;
 249       </synopsis>
 250       The record data is defined as a buffer of some length so that
 251       data can be of any type. SRW 1.0 currenly doesn't allow for this
 252       (only XML), but future versions might do.
 253     </para>
 254     <para>
 255       And, a diagnostic as:
 256       <synopsis>
 257 typedef struct {
 258     int  *code;
 259     char *details;
 260 } Z_SRW_diagnostic;
 261       </synopsis>
 262     </para>
 263   </sect1>
 264 </chapter>
 265