Announce new functionality API on Debian
[yaz-moved-to-github.git] / 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