1 <!-- $Id: soap.xml,v 1.2 2003-02-21 12:20:22 adam Exp $ -->
2 <chapter id="soap"><title>SOAP and SRW</title>
3 <sect1 id="soap.introduction"><title>Introduction</title>
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.
12 Like the Z39.50 ASN.1 module, the &yaz; SRW implementation uses
13 simple C structs to represent SOAP packages as well as
17 <sect1 id="soap.http"><title>HTTP</title>
19 &yaz; only offers HTTP as transport carrier for SOAP, but it is
20 relatively easy to change that.
23 The following definition of <literal>Z_GDU</literal> (Generic Data
24 Unit) allows for both HTTP and Z39.50 in one packet.
27 #include <yaz/zgdu.h>
30 #define Z_GDU_HTTP_Request 2
31 #define Z_GDU_HTTP_Response 3
36 Z_HTTP_Request *HTTP_Request;
37 Z_HTTP_Response *HTTP_Response;
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
45 <literal>HTTP_Request</literal> and <literal>HTTP_Response</literal>
46 is the HTTP Request and Response respectively.
49 <sect1 id="soap.xml"><title>SOAP Packages</title>
51 Every SOAP package in &yaz; is represented as follows:
53 #include <yaz/soap.h>
67 #define Z_SOAP_fault 1
68 #define Z_SOAP_generic 2
69 #define Z_SOAP_error 3
74 Z_SOAP_Generic *generic;
75 Z_SOAP_Fault *soap_error;
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>.
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>,
93 <literal>http://www.w3.org/2001/06/soap-envelope</literal>.
96 int z_soap_codec(ODR o, Z_SOAP **pp,
97 char **content_buf, int *content_len,
98 Z_SOAP_Handler *handlers);
101 The <literal>content_buf</literal> and <literal>content_len</literal>
102 is XML buffer and length of buffer respectively.
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 <literal>http://www.loc.gov/zing/srw/v1.0/</literal>.
110 Each handler is define as follows:
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.
123 The prototype for a handler is:
125 int handler(ODR o, void * ptr, void **handler_data,
126 void *client_data, const char *ns);
130 <sect1 id="soap.srw"><title>SRW</title>
132 SRW is just one kind of SOAP handler as described in the previous
135 #include <yaz/soap.h>
139 char *recordData_buf;
160 } Z_SRW_searchRetrieveRequest;
163 int * numberOfRecords;
165 int * resultSetIdleTime;
167 Z_SRW_record *records;
170 Z_SRW_diagnostic *diagnostics;
172 int *nextRecordPosition;
173 } Z_SRW_searchRetrieveResponse;
175 #define Z_SRW_searchRetrieve_request 1
176 #define Z_SRW_searchRetrieve_response 2
181 Z_SRW_searchRetrieveRequest *request;
182 Z_SRW_searchRetrieveResponse *response;
184 } Z_SRW_searchRetrieve;