doc/soap.xml

   1 <chapter id="soap"><title>SOAP and SRU</title>
   2   <sect1 id="soap.introduction"><title>Introduction</title>
   3     <para>
   4       &yaz; uses a very simple implementation of
   5       <ulink url="&url.soap;">SOAP</ulink> that only,
   6       currenly, supports what is sufficient to offer SRU SOAP functionality.
   7       The implementation uses the
   8       <ulink url="&url.libxml2.api.tree;">tree API</ulink> of
   9       libxml2 to encode and decode SOAP packages.
  10     </para>
  11     <para>
  12       Like the Z39.50 ASN.1 module, the &yaz; SRU 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 codec
 106       handlers - one handler for each service namespace. For SRU SOAP, the
 107       namespace would be <literal>http://www.loc.gov/zing/srw/v1.0/</literal>.
 108     </para>
 109     <para>
 110       When decoding, the <function>z_soap_codec</function>
 111       inspects the XML content
 112       and tries to match one of the services namespaces of the
 113       supplied handlers. If there is a match a handler function
 114       is invoked which decodes that particular SOAP package.
 115       If successful, the returned <literal>Z_SOAP</literal> package will be
 116       of type <literal>Z_SOAP_Generic</literal>.
 117       Member <literal>no</literal> is
 118       set the offset of handler that matched; <literal>ns</literal>
 119       is set to namespace of matching handler; the void pointer
 120       <literal>p</literal> is set to the C data structure assocatiated
 121       with the handler.
 122     </para>
 123     <para>
 124       When a NULL namespace is met (member <literal>ns</literal> bwlow),
 125       that specifies end-of-list.
 126     </para>
 127     <para>
 128       Each handler is defined as follows:
 129       <synopsis>
 130 typedef struct {
 131     char *ns;
 132     void *client_data;
 133     Z_SOAP_fun f;
 134 } Z_SOAP_Handler;
 135       </synopsis>
 136       The <literal>ns</literal> is namespace of service associated with
 137       handler <literal>f</literal>. <literal>client_data</literal>
 138       is user-defined data which is passed to handler.
 139     </para>
 140     <para>
 141       The prototype for a SOAP service handler is:
 142       <synopsis>
 143 int handler(ODR o, void * ptr, void **handler_data,
 144             void *client_data, const char *ns);
 145       </synopsis>
 146       The <parameter>o</parameter> specifies the mode (decode/encode)
 147       as usual. The second argument, <parameter>ptr</parameter>,
 148       is a libxml2 tree node pointer (<literal>xmlNodePtr</literal>)
 149       and is a pointer to the <literal>Body</literal> element
 150       of the SOAP package. The <parameter>handler_data</parameter>
 151       is an opaque pointer to a C definitions associated with the
 152       SOAP service. <parameter>client_data</parameter> is the pointer
 153       which was set as part of the <literal>Z_SOAP_handler</literal>.
 154       Finally, <parameter>ns</parameter> the service namespace.
 155     </para>
 156   </sect1>
 157   <sect1 id="soap.srw"><title>SRU</title>
 158     <para>
 159       SRU SOAP is just one implementation of a SOAP handler as described
 160       in the previous section.
 161       The encoder/decoder handler for SRU is defined as
 162       follows:
 163       <synopsis>
 164 #include &lt;yaz/srw.h&gt;
 165
 166 int yaz_srw_codec(ODR o, void * pptr,
 167                   Z_SRW_GDU **handler_data,
 168                   void *client_data, const char *ns);
 169       </synopsis>
 170       Here, <literal>Z_SRW_GDU</literal> is either
 171       searchRetrieveRequest or a searchRetrieveResponse.
 172     </para>
 173     <note>
 174       <para>
 175         The xQuery and xSortKeys are not handled yet by
 176         the SRW implementation of &yaz;. Explain is also missing.
 177         Future versions of &yaz; will include these features.
 178       </para>
 179     </note>
 180     <para>
 181       The definition of searchRetrieveRequest is:
 182       <synopsis>
 183 typedef struct {
 184
 185 #define Z_SRW_query_type_cql  1
 186 #define Z_SRW_query_type_xcql 2
 187 #define Z_SRW_query_type_pqf  3
 188     int query_type;
 189     union {
 190         char *cql;
 191         char *xcql;
 192         char *pqf;
 193     } query;
 194
 195 #define Z_SRW_sort_type_none 1
 196 #define Z_SRW_sort_type_sort 2
 197 #define Z_SRW_sort_type_xSort 3
 198     int sort_type;
 199     union {
 200         char *none;
 201         char *sortKeys;
 202         char *xSortKeys;
 203     } sort;
 204     int  *startRecord;
 205     int  *maximumRecords;
 206     char *recordSchema;
 207     char *recordPacking;
 208     char *database;
 209 } Z_SRW_searchRetrieveRequest;
 210       </synopsis>
 211       Please observe that data of type xsd:string is represented
 212       as a char pointer (<literal>char *</literal>). A null pointer
 213       means that the element is absent.
 214       Data of type xsd:integer is representd as a pointer to
 215       an int (<literal>int *</literal>). Again, a null pointer
 216       us used for absent elements.
 217     </para>
 218     <para>
 219       The SearchRetrieveResponse has the following definition.
 220       <synopsis>
 221 typedef struct {
 222     int * numberOfRecords;
 223     char * resultSetId;
 224     int * resultSetIdleTime;
 225
 226     Z_SRW_record *records;
 227     int num_records;
 228
 229     Z_SRW_diagnostic *diagnostics;
 230     int num_diagnostics;
 231     int *nextRecordPosition;
 232 } Z_SRW_searchRetrieveResponse;
 233       </synopsis>
 234       The <literal>num_records</literal> and <literal>num_diagnostics</literal>
 235       is number of returned records and diagnostics respectively and also
 236       correspond to the "size of" arrays <literal>records</literal>
 237       and <literal>diagnostics</literal>.
 238     </para>
 239     <para>
 240       A retrieval record is defined as follows:
 241       <synopsis>
 242 typedef struct {
 243     char *recordSchema;
 244     char *recordData_buf;
 245     int recordData_len;
 246     int *recordPosition;
 247 } Z_SRW_record;
 248       </synopsis>
 249       The record data is defined as a buffer of some length so that
 250       data can be of any type. SRW 1.0 currenly doesn't allow for this
 251       (only XML), but future versions might do.
 252     </para>
 253     <para>
 254       And, a diagnostic as:
 255       <synopsis>
 256 typedef struct {
 257     int  *code;
 258     char *details;
 259 } Z_SRW_diagnostic;
 260       </synopsis>
 261     </para>
 262   </sect1>
 263 </chapter>
 264