Fix yaz URL
[yaz-moved-to-github.git] / include / yaz / srw.h
1 /* This file is part of the YAZ toolkit.
2  * Copyright (C) 1995-2010 Index Data.
3  * All rights reserved.
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  *     * Redistributions of source code must retain the above copyright
8  *       notice, this list of conditions and the following disclaimer.
9  *     * Redistributions in binary form must reproduce the above copyright
10  *       notice, this list of conditions and the following disclaimer in the
11  *       documentation and/or other materials provided with the distribution.
12  *     * Neither the name of Index Data nor the names of its contributors
13  *       may be used to endorse or promote products derived from this
14  *       software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27
28 /**
29  * \file srw.h
30  * \brief Header for SRW/SRU
31  */
32
33 #ifndef YAZ_SRW_H
34 #define YAZ_SRW_H
35
36 #include <yaz/soap.h>
37 #include <yaz/zgdu.h>
38 #include <yaz/diagsrw.h>
39 #include <yaz/diagsru_update.h>
40 #include "facet.h"
41
42 YAZ_BEGIN_CDECL
43
44 typedef struct {
45     char *extraRecordData_buf;
46     int extraRecordData_len;
47     char *recordIdentifier;
48 } Z_SRW_extra_record;
49
50 typedef struct {
51     char *recordSchema;
52     int recordPacking;
53 #define Z_SRW_recordPacking_string 0
54 #define Z_SRW_recordPacking_XML 1
55 #define Z_SRW_recordPacking_URL 2
56     char *recordData_buf;
57     int recordData_len;
58     Odr_int *recordPosition;
59 } Z_SRW_record;
60
61 typedef struct {
62     char *uri;
63     char *details;
64     char *message;
65 } Z_SRW_diagnostic;
66     
67 typedef struct {
68
69 #define Z_SRW_query_type_cql  1
70 #define Z_SRW_query_type_xcql 2
71 #define Z_SRW_query_type_pqf  3
72     int query_type;
73     union {
74         char *cql;
75         char *xcql;
76         char *pqf;
77     } query;
78
79 #define Z_SRW_sort_type_none 1
80 #define Z_SRW_sort_type_sort 2
81 #define Z_SRW_sort_type_xSort 3
82     int sort_type;
83     union {
84         char *none;
85         char *sortKeys;
86         char *xSortKeys;
87     } sort;
88     Odr_int *startRecord;
89     Odr_int *maximumRecords;
90     char *recordSchema;
91     char *recordPacking;
92     char *recordXPath;
93     char *database;
94     char *stylesheet;
95     Odr_int *resultSetTTL;
96     Z_FacetList *facetList;
97 } Z_SRW_searchRetrieveRequest;
98
99 typedef struct {
100     Odr_int *numberOfRecords;
101     char * resultSetId;
102     Odr_int *resultSetIdleTime;
103     
104     Z_SRW_record *records;
105     int num_records;
106
107     Z_SRW_diagnostic *diagnostics;
108     int num_diagnostics;
109     Odr_int *nextRecordPosition;
110
111     Z_SRW_extra_record **extra_records;  /* of size num_records */
112     Z_FacetList *facetList;
113 } Z_SRW_searchRetrieveResponse;
114
115 typedef struct {
116     char *recordPacking;
117     char *database;
118     char *stylesheet;
119 } Z_SRW_explainRequest;
120
121 typedef struct {
122     Z_SRW_record record;
123     Z_SRW_diagnostic *diagnostics;
124     int num_diagnostics;
125     Z_SRW_extra_record *extra_record;
126 } Z_SRW_explainResponse;
127     
128 typedef struct {
129     int query_type;
130     union {
131         char *cql;
132         char *xcql;
133         char *pqf;
134     } scanClause;
135     Odr_int *responsePosition;
136     Odr_int *maximumTerms;
137     char *stylesheet;
138     char *database;
139 } Z_SRW_scanRequest;
140
141 typedef struct {
142     char *value;
143     Odr_int *numberOfRecords;
144     char *displayTerm;
145     char *whereInList;
146 } Z_SRW_scanTerm;
147
148 typedef struct {
149     Z_SRW_scanTerm *terms;
150     int num_terms;
151     Z_SRW_diagnostic *diagnostics;
152     int num_diagnostics;
153 } Z_SRW_scanResponse;
154
155
156 typedef struct {
157     char *versionType;
158     char *versionValue;
159 } Z_SRW_recordVersion;
160
161 typedef struct {
162     char *database;
163     char *operation;
164     char *recordId;
165     Z_SRW_recordVersion *recordVersions;
166     int num_recordVersions;
167     Z_SRW_record *record;
168     Z_SRW_extra_record *extra_record;
169     char *extraRequestData_buf;
170     int extraRequestData_len;
171     char *stylesheet;
172 } Z_SRW_updateRequest;
173
174 typedef struct Z_SRW_extra_arg Z_SRW_extra_arg;
175 struct Z_SRW_extra_arg {
176     char *name;
177     char *value;
178     Z_SRW_extra_arg *next;
179 };
180
181 typedef struct {
182     char *operationStatus;
183     char *recordId;
184     Z_SRW_recordVersion *recordVersions;
185     int num_recordVersions;
186     Z_SRW_record *record;
187     Z_SRW_extra_record *extra_record;
188     char *extraResponseData_buf;
189     int extraResponseData_len;
190     Z_SRW_diagnostic *diagnostics;
191     int num_diagnostics;
192 } Z_SRW_updateResponse;
193
194 #define Z_SRW_searchRetrieve_request  1
195 #define Z_SRW_searchRetrieve_response 2
196 #define Z_SRW_explain_request 3
197 #define Z_SRW_explain_response 4
198 #define Z_SRW_scan_request 5
199 #define Z_SRW_scan_response 6
200 #define Z_SRW_update_request 7
201 #define Z_SRW_update_response 8
202
203 typedef struct {
204     int which;
205     union {
206         Z_SRW_searchRetrieveRequest *request;
207         Z_SRW_searchRetrieveResponse *response;
208         Z_SRW_explainRequest *explain_request;
209         Z_SRW_explainResponse *explain_response;
210         Z_SRW_scanRequest *scan_request;
211         Z_SRW_scanResponse *scan_response;
212         Z_SRW_updateRequest *update_request;
213         Z_SRW_updateResponse *update_response;
214     } u;
215     char *srw_version;
216     char *username; /* From HTTP header or request */
217     char *password; /* From HTTP header or request  */
218     Z_SRW_extra_arg *extra_args; /* extraRequestData SRU GET/POST */
219     char *extraResponseData_buf;
220     int extraResponseData_len;
221 } Z_SRW_PDU;
222
223 YAZ_EXPORT int yaz_srw_codec(ODR o, void * pptr,
224                              Z_SRW_PDU **handler_data,
225                              void *client_data, const char *ns);
226 YAZ_EXPORT int yaz_ucp_codec(ODR o, void * pptr,
227                              Z_SRW_PDU **handler_data,
228                              void *client_data, const char *ns);
229 YAZ_EXPORT Z_SRW_PDU *yaz_srw_get_core_v_1_1(ODR o);
230 YAZ_EXPORT Z_SRW_PDU *yaz_srw_get_pdu(ODR o, int which, const char *version);
231 YAZ_EXPORT Z_SRW_PDU *yaz_srw_get(ODR o, int which);
232 YAZ_EXPORT Z_SRW_recordVersion *yaz_srw_get_record_versions(ODR o, int num);
233 YAZ_EXPORT Z_SRW_extra_record *yaz_srw_get_extra_record(ODR o);
234 YAZ_EXPORT Z_SRW_record *yaz_srw_get_record(ODR o);
235 YAZ_EXPORT Z_SRW_record *yaz_srw_get_records(ODR o, int num);
236
237 YAZ_EXPORT int yaz_diag_bib1_to_srw (int bib1_code);
238
239 YAZ_EXPORT int yaz_diag_srw_to_bib1(int srw_code);
240
241 YAZ_EXPORT const char *yaz_srw_pack_to_str(int pack);
242 YAZ_EXPORT int yaz_srw_str_to_pack(const char *str);
243
244 /** \brief deprecated */
245 YAZ_EXPORT char *yaz_uri_val(const char *path, const char *name, ODR o);
246
247 /** \brief deprecated */
248 YAZ_EXPORT void yaz_uri_val_int(const char *path, const char *name,
249                                 ODR o, Odr_int **intp);
250
251 YAZ_EXPORT int yaz_uri_to_array(const char *path, ODR o,
252                                 char ***name, char ***val);
253 YAZ_EXPORT void yaz_array_to_uri(char **path, ODR o,
254                                  char **name, char **value);
255
256 /** \brief encodes URI component
257     \param dst destination string (should be at least 3*strlen(uri)+1)
258     \param uri URI component C-string (source)
259 */
260 YAZ_EXPORT void yaz_encode_uri_component(char *dst, const char *uri);
261
262 /** \brief decodes URI component
263     \param dst destination string (should be at least strlen(uri)+1)
264     \param uri URI component buffer (source)
265     \param len number of bytes to decode from uri
266 */
267 YAZ_EXPORT void yaz_decode_uri_component(char *dst, const char *uri,
268                                          size_t len);
269
270 YAZ_EXPORT int yaz_srw_decode(Z_HTTP_Request *hreq, Z_SRW_PDU **srw_pdu,
271                               Z_SOAP **soap_package, ODR decode, char **charset);
272
273 YAZ_EXPORT int yaz_sru_decode(Z_HTTP_Request *hreq, Z_SRW_PDU **srw_pdu,
274                               Z_SOAP **soap_package, ODR decode, 
275                               char **charset,
276                               Z_SRW_diagnostic **, int *num_diagnostic);
277
278 /** \brief decode SOLR response (HTTP)
279     \param o ODR for result
280     \param hres HTTP response to be decoded
281     \param pdup SRW response pointer (set if successful)
282     \retval -1 fail
283     \retval 0 OK
284 */
285 YAZ_EXPORT int yaz_solr_decode_response(ODR o, Z_HTTP_Response *hres,
286                                         Z_SRW_PDU **pdup);
287
288
289 YAZ_EXPORT void yaz_add_srw_diagnostic(ODR o, Z_SRW_diagnostic **d,
290                                        int *num, int code,
291                                        const char *addinfo);
292     
293 YAZ_EXPORT void yaz_add_sru_update_diagnostic(ODR o, Z_SRW_diagnostic **d,
294                                               int *num, int code,
295                                               const char *addinfo);
296
297 YAZ_EXPORT void yaz_mk_std_diagnostic(ODR o, Z_SRW_diagnostic *d, 
298                                       int code, const char *details);
299
300 YAZ_EXPORT void yaz_add_srw_diagnostic_uri(ODR o, Z_SRW_diagnostic **d,
301                                            int *num, const char *uri,
302                                            const char *message,
303                                            const char *details);
304
305 YAZ_EXPORT void yaz_mk_srw_diagnostic(ODR o, Z_SRW_diagnostic *d, 
306                                       const char *uri, const char *message,
307                                       const char *details);
308
309 YAZ_EXPORT int yaz_sru_get_encode(Z_HTTP_Request *hreq, Z_SRW_PDU *srw_pdu,
310                                   ODR encode, const char *charset);
311 YAZ_EXPORT int yaz_sru_post_encode(Z_HTTP_Request *hreq, Z_SRW_PDU *srw_pdu,
312                                    ODR encode, const char *charset);
313 YAZ_EXPORT int yaz_sru_soap_encode(Z_HTTP_Request *hreq, Z_SRW_PDU *srw_pdu,
314                                    ODR odr, const char *charset);
315
316 /** \brief encode SOLR request (HTTP)
317     \param hreq HTTP request to be modified (with encoded request)
318     \param srw_pdu SRW request
319     \param encode ODR for result
320     \param charset character set for request (may be NULL)
321     \retval -1 fail
322     \retval 0 OK
323 */
324 YAZ_EXPORT int yaz_solr_encode_request(Z_HTTP_Request *hreq, Z_SRW_PDU *srw_pdu,
325                                        ODR encode, const char *charset);
326
327 YAZ_EXPORT char *yaz_negotiate_sru_version(char *input_ver);
328
329 YAZ_EXPORT
330 void yaz_encode_sru_extra(Z_SRW_PDU *sr, ODR odr, const char *extra_args);
331
332
333 #define YAZ_XMLNS_SRU_v1_0 "http://www.loc.gov/zing/srw/v1.0/"
334 #define YAZ_XMLNS_SRU_v1_1 "http://www.loc.gov/zing/srw/"
335 #define YAZ_XMLNS_DIAG_v1_1 "http://www.loc.gov/zing/srw/diagnostic/"
336 #define YAZ_XMLNS_UPDATE_v0_9 "http://www.loc.gov/zing/srw/update/"
337
338 YAZ_EXPORT
339 int yaz_srw_check_content_type(Z_HTTP_Response *hres);
340
341 YAZ_EXPORT
342 int sru_decode_surrogate_diagnostics(const char *buf, size_t len,
343                                      Z_SRW_diagnostic **diag,
344                                      int *num, ODR odr);
345
346 YAZ_EXPORT
347 void yaz_mk_sru_surrogate(ODR o, Z_SRW_record *record, int pos,
348                           int code, const char *details);
349
350 /** \brief encode SRU database for HTTP path
351     \param out memory handle for resulting encoded database string
352     \param db source database
353     \returns encoded database path (includes leading /)
354 */
355 YAZ_EXPORT
356 char *yaz_encode_sru_dbpath_odr(ODR out, const char *db);
357
358 /** \brief encode SRU database for HTTP path
359     \param dst destination buffer (should be at least strlen(db) +2 in size)
360     \param db source database
361    
362     The resulting database (dst) includes a leading /
363 */
364 YAZ_EXPORT
365 void yaz_encode_sru_dbpath_buf(char *dst, const char *db);
366
367 YAZ_END_CDECL
368
369 #endif
370 /*
371  * Local variables:
372  * c-basic-offset: 4
373  * c-file-style: "Stroustrup"
374  * indent-tabs-mode: nil
375  * End:
376  * vim: shiftwidth=4 tabstop=8 expandtab
377  */
378