File: soap.xml

package info (click to toggle)
yaz 3.0.34-2
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 13,404 kB
  • ctags: 12,108
  • sloc: xml: 116,075; ansic: 52,205; sh: 9,746; tcl: 2,043; makefile: 1,141; yacc: 347
file content (264 lines) | stat: -rw-r--r-- 8,496 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
<chapter id="soap"><title>SOAP and SRU</title>
  <sect1 id="soap.introduction"><title>Introduction</title>
    <para>
      &yaz; uses a very simple implementation of 
      <ulink url="&url.soap;">SOAP</ulink> that only,
      currenly, supports what is sufficient to offer SRU SOAP functionality.
      The implementation uses the 
      <ulink url="&url.libxml2.api.tree;">tree API</ulink> of
      libxml2 to encode and decode SOAP packages.
    </para>
    <para>
      Like the Z39.50 ASN.1 module, the &yaz; SRU implementation uses
      simple C structs to represent SOAP packages as well as
      HTTP packages.
    </para>
  </sect1>
  <sect1 id="soap.http"><title>HTTP</title>
    <para>
      &yaz; only offers HTTP as transport carrier for SOAP, but it is
      relatively easy to change that.
    </para>
    <para>
      The following definition of <literal>Z_GDU</literal> (Generic Data
      Unit) allows for both HTTP and Z39.50 in one packet.
    </para>
    <synopsis>
#include &lt;yaz/zgdu.h&gt;

#define Z_GDU_Z3950         1
#define Z_GDU_HTTP_Request  2
#define Z_GDU_HTTP_Response 3
typedef struct {
  int which;
  union {
    Z_APDU *z3950;
    Z_HTTP_Request *HTTP_Request;
    Z_HTTP_Response *HTTP_Response;
  } u;
} Z_GDU ;
    </synopsis>
    <para>
      The corresponding Z_GDU encoder/decoder is <function>z_GDU</function>.
      The <literal>z3950</literal> is any of the known BER encoded Z39.50
      APDUs.
      <literal>HTTP_Request</literal> and <literal>HTTP_Response</literal>
      is the HTTP Request and Response respectively.
    </para>
  </sect1>
  <sect1 id="soap.xml"><title>SOAP Packages</title>
    <para>
      Every SOAP package in &yaz; is represented as follows:
      <synopsis>
#include &lt;yaz/soap.h&gt;

typedef struct {
    char *fault_code;
    char *fault_string;
    char *details;
} Z_SOAP_Fault;

typedef struct {
    int no;
    char *ns;
    void *p;
} Z_SOAP_Generic;

#define Z_SOAP_fault 1
#define Z_SOAP_generic 2
#define Z_SOAP_error 3
typedef struct {
    int which;
    union {
        Z_SOAP_Fault   *fault;
        Z_SOAP_Generic *generic;
        Z_SOAP_Fault   *soap_error;
    } u;
    const char *ns;
} Z_SOAP;
      </synopsis>
    </para>
    <para>
      The <literal>fault</literal> and <literal>soap_error</literal>
      arms represent both a SOAP fault - struct
      <literal>Z_SOAP_Fault</literal>. Any other generic
        (valid) package is represented by <literal>Z_SOAP_Generic</literal>.
    </para>
    <para>
      The <literal>ns</literal> as part of <literal>Z_SOAP</literal>
      is the namespace for SOAP itself and reflects the SOAP
      version. For version 1.1 it is
      <literal>http://schemas.xmlsoap.org/soap/envelope/</literal>,
      for version 1.2 it is
      <literal>http://www.w3.org/2001/06/soap-envelope</literal>.
    </para>
    <synopsis>
int z_soap_codec(ODR o, Z_SOAP **pp,
                 char **content_buf, int *content_len,
                 Z_SOAP_Handler *handlers);
    </synopsis>
    <para>
      The <literal>content_buf</literal> and <literal>content_len</literal>
      is XML buffer and length of buffer respectively.
    </para>
    <para>
      The <literal>handlers</literal> is a list of SOAP codec
      handlers - one handler for each service namespace. For SRU SOAP, the
      namespace would be <literal>http://www.loc.gov/zing/srw/v1.0/</literal>.
    </para>
    <para>
      When decoding, the <function>z_soap_codec</function>
      inspects the XML content
      and tries to match one of the services namespaces of the
      supplied handlers. If there is a match a handler function
      is invoked which decodes that particular SOAP package.
      If successful, the returned <literal>Z_SOAP</literal> package will be
      of type <literal>Z_SOAP_Generic</literal>.
      Member <literal>no</literal> is
      set the offset of handler that matched; <literal>ns</literal>
      is set to namespace of matching handler; the void pointer
      <literal>p</literal> is set to the C data structure assocatiated
      with the handler.
    </para>
    <para>
      When a NULL namespace is met (member <literal>ns</literal> bwlow),
      that specifies end-of-list.
    </para>
    <para>
      Each handler is defined as follows:
      <synopsis>
typedef struct {
    char *ns;
    void *client_data;
    Z_SOAP_fun f;
} Z_SOAP_Handler;
      </synopsis>
      The <literal>ns</literal> is namespace of service associated with
      handler <literal>f</literal>. <literal>client_data</literal>
      is user-defined data which is passed to handler.
    </para>
    <para>
      The prototype for a SOAP service handler is:
      <synopsis>
int handler(ODR o, void * ptr, void **handler_data,
            void *client_data, const char *ns);
      </synopsis>
      The <parameter>o</parameter> specifies the mode (decode/encode)
      as usual. The second argument, <parameter>ptr</parameter>,
      is a libxml2 tree node pointer (<literal>xmlNodePtr</literal>)
      and is a pointer to the <literal>Body</literal> element
      of the SOAP package. The <parameter>handler_data</parameter>
      is an opaque pointer to a C definitions associated with the
      SOAP service. <parameter>client_data</parameter> is the pointer
      which was set as part of the <literal>Z_SOAP_handler</literal>.
      Finally, <parameter>ns</parameter> the service namespace.
    </para>
  </sect1>
  <sect1 id="soap.srw"><title>SRU</title>
    <para>
      SRU SOAP is just one implementation of a SOAP handler as described
      in the previous section.
      The encoder/decoder handler for SRU is defined as
      follows:
      <synopsis>
#include &lt;yaz/srw.h&gt;

int yaz_srw_codec(ODR o, void * pptr,
                  Z_SRW_GDU **handler_data,
                  void *client_data, const char *ns);
      </synopsis>
      Here, <literal>Z_SRW_GDU</literal> is either
      searchRetrieveRequest or a searchRetrieveResponse. 
    </para>
    <note>
      <para>
        The xQuery and xSortKeys are not handled yet by
        the SRW implementation of &yaz;. Explain is also missing.
        Future versions of &yaz; will include these features.
      </para>
    </note>
    <para>
      The definition of searchRetrieveRequest is:
      <synopsis>
typedef struct {

#define Z_SRW_query_type_cql  1
#define Z_SRW_query_type_xcql 2
#define Z_SRW_query_type_pqf  3
    int query_type;
    union {
        char *cql;
        char *xcql;
        char *pqf;
    } query;

#define Z_SRW_sort_type_none 1
#define Z_SRW_sort_type_sort 2
#define Z_SRW_sort_type_xSort 3
    int sort_type;
    union {
        char *none;
        char *sortKeys;
        char *xSortKeys;
    } sort;
    int  *startRecord;
    int  *maximumRecords;
    char *recordSchema;
    char *recordPacking;
    char *database;
} Z_SRW_searchRetrieveRequest;
      </synopsis>
      Please observe that data of type xsd:string is represented
      as a char pointer (<literal>char *</literal>). A null pointer
      means that the element is absent.
      Data of type xsd:integer is representd as a pointer to
      an int (<literal>int *</literal>). Again, a null pointer
      us used for absent elements.
    </para>
    <para>
      The SearchRetrieveResponse has the following definition.
      <synopsis>
typedef struct {
    int * numberOfRecords;
    char * resultSetId;
    int * resultSetIdleTime;
    
    Z_SRW_record *records;
    int num_records;

    Z_SRW_diagnostic *diagnostics;
    int num_diagnostics;
    int *nextRecordPosition;
} Z_SRW_searchRetrieveResponse;
      </synopsis>
      The <literal>num_records</literal> and <literal>num_diagnostics</literal>
      is number of returned records and diagnostics respectively and also
      correspond to the "size of" arrays <literal>records</literal>
      and <literal>diagnostics</literal>.
    </para>
    <para>
      A retrieval record is defined as follows:
      <synopsis>
typedef struct {
    char *recordSchema;
    char *recordData_buf;
    int recordData_len;
    int *recordPosition;
} Z_SRW_record;
      </synopsis>
      The record data is defined as a buffer of some length so that
      data can be of any type. SRW 1.0 currenly doesn't allow for this
      (only XML), but future versions might do.
    </para>
    <para>
      And, a diagnostic as:
      <synopsis>
typedef struct {
    int  *code;
    char *details;
} Z_SRW_diagnostic;
      </synopsis>
    </para>
  </sect1>
</chapter>