Use URL entities for most link references
[yaz-moved-to-github.git] / doc / soap.xml
1 <!-- $Id: soap.xml,v 1.6 2006-04-24 09:21:35 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 
6       <ulink url="&url.soap;">SOAP</ulink> that only,
7       currenly, supports what is sufficient to offer SRW 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; SRW 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 SRW, 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>SRW</title>
159     <para>
160       SRW is just one implementation of a SOAP handler as described
161       in the previous section.
162       The encoder/decoder handler for SRW 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