include/yaz/srw.h

   1 /* This file is part of the YAZ toolkit.
   2  * Copyright (C) 1995-2013 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
  53     int recordPacking; /* recordXMLEscaping in SRU 2.0 */
  54 #define Z_SRW_recordPacking_string 0
  55 #define Z_SRW_recordPacking_XML 1
  56 #define Z_SRW_recordPacking_URL 2
  57
  58 #if 0
  59     int packing;   /* recordPacking in SRU 2.0 */
  60 #define Z_SRW_packed   0
  61 #define Z_SRW_unpacked     1
  62 #endif
  63
  64     char *recordData_buf;
  65     int recordData_len;
  66     Odr_int *recordPosition;
  67 } Z_SRW_record;
  68
  69 typedef struct {
  70     char *uri;
  71     char *details;
  72     char *message;
  73 } Z_SRW_diagnostic;
  74
  75 typedef struct {
  76
  77     char *queryType;
  78     char *query;
  79
  80 #define Z_SRW_sort_type_none 1
  81 #define Z_SRW_sort_type_sort 2
  82 #define Z_SRW_sort_type_xSort 3
  83     int sort_type;
  84     union {
  85         char *none;
  86         char *sortKeys;
  87         char *xSortKeys;
  88     } sort;
  89     Odr_int *startRecord;
  90     Odr_int *maximumRecords;
  91     char *recordSchema;
  92
  93     char *recordPacking;       /* recordXMLEscaping in SRU 2.0 */
  94     char *packing;             /* recordPacking in SRU 2.0 */
  95
  96     char *recordXPath;
  97     char *database;
  98     char *stylesheet;
  99     Odr_int *resultSetTTL;
 100     Z_FacetList *facetList;
 101 } Z_SRW_searchRetrieveRequest;
 102
 103 typedef struct {
 104     Odr_int *numberOfRecords;
 105     char *resultCountPrecision;
 106     char * resultSetId;
 107     Odr_int *resultSetIdleTime;
 108
 109     Z_SRW_record *records;
 110     int num_records;
 111
 112     Z_SRW_diagnostic *diagnostics;
 113     int num_diagnostics;
 114     Odr_int *nextRecordPosition;
 115
 116     Z_SRW_extra_record **extra_records;  /* of size num_records */
 117     Z_FacetList *facetList;
 118     char *suggestions;
 119 } Z_SRW_searchRetrieveResponse;
 120
 121 typedef struct {
 122     char *recordPacking;
 123     char *packing;
 124     char *database;
 125     char *stylesheet;
 126 } Z_SRW_explainRequest;
 127
 128 typedef struct {
 129     Z_SRW_record record;
 130     Z_SRW_diagnostic *diagnostics;
 131     int num_diagnostics;
 132     Z_SRW_extra_record *extra_record;
 133 } Z_SRW_explainResponse;
 134
 135 typedef struct {
 136     char *queryType;
 137     char *scanClause;
 138     Odr_int *responsePosition;
 139     Odr_int *maximumTerms;
 140     char *stylesheet;
 141     char *database;
 142 } Z_SRW_scanRequest;
 143
 144 typedef struct {
 145     char *value;
 146     Odr_int *numberOfRecords;
 147     char *displayTerm;
 148     char *whereInList;
 149 } Z_SRW_scanTerm;
 150
 151 typedef struct {
 152     Z_SRW_scanTerm *terms;
 153     int num_terms;
 154     Z_SRW_diagnostic *diagnostics;
 155     int num_diagnostics;
 156 } Z_SRW_scanResponse;
 157
 158
 159 typedef struct {
 160     char *versionType;
 161     char *versionValue;
 162 } Z_SRW_recordVersion;
 163
 164 typedef struct {
 165     char *database;
 166     char *operation;
 167     char *recordId;
 168     Z_SRW_recordVersion *recordVersions;
 169     int num_recordVersions;
 170     Z_SRW_record *record;
 171     Z_SRW_extra_record *extra_record;
 172     char *extraRequestData_buf;
 173     int extraRequestData_len;
 174     char *stylesheet;
 175 } Z_SRW_updateRequest;
 176
 177 typedef struct Z_SRW_extra_arg Z_SRW_extra_arg;
 178 struct Z_SRW_extra_arg {
 179     char *name;
 180     char *value;
 181     Z_SRW_extra_arg *next;
 182 };
 183
 184 typedef struct {
 185     char *operationStatus;
 186     char *recordId;
 187     Z_SRW_recordVersion *recordVersions;
 188     int num_recordVersions;
 189     Z_SRW_record *record;
 190     Z_SRW_extra_record *extra_record;
 191     char *extraResponseData_buf;
 192     int extraResponseData_len;
 193     Z_SRW_diagnostic *diagnostics;
 194     int num_diagnostics;
 195 } Z_SRW_updateResponse;
 196
 197 #define Z_SRW_searchRetrieve_request  1
 198 #define Z_SRW_searchRetrieve_response 2
 199 #define Z_SRW_explain_request 3
 200 #define Z_SRW_explain_response 4
 201 #define Z_SRW_scan_request 5
 202 #define Z_SRW_scan_response 6
 203 #define Z_SRW_update_request 7
 204 #define Z_SRW_update_response 8
 205
 206 typedef struct {
 207     int which;
 208     union {
 209         Z_SRW_searchRetrieveRequest *request;
 210         Z_SRW_searchRetrieveResponse *response;
 211         Z_SRW_explainRequest *explain_request;
 212         Z_SRW_explainResponse *explain_response;
 213         Z_SRW_scanRequest *scan_request;
 214         Z_SRW_scanResponse *scan_response;
 215         Z_SRW_updateRequest *update_request;
 216         Z_SRW_updateResponse *update_response;
 217     } u;
 218     char *srw_version;
 219     char *username; /* From HTTP header or request */
 220     char *password; /* From HTTP header or request  */
 221     Z_SRW_extra_arg *extra_args; /* extraRequestData SRU GET/POST */
 222     char *extraResponseData_buf;
 223     int extraResponseData_len;
 224 } Z_SRW_PDU;
 225
 226 YAZ_EXPORT int yaz_srw_codec(ODR o, void * pptr,
 227                              Z_SRW_PDU **handler_data,
 228                              void *client_data, const char *ns);
 229 YAZ_EXPORT int yaz_ucp_codec(ODR o, void * pptr,
 230                              Z_SRW_PDU **handler_data,
 231                              void *client_data, const char *ns);
 232 YAZ_EXPORT Z_SRW_PDU *yaz_srw_get_core_v_2_0(ODR o);
 233 YAZ_EXPORT Z_SRW_PDU *yaz_srw_get_pdu(ODR o, int which, const char *version);
 234 YAZ_EXPORT Z_SRW_PDU *yaz_srw_get(ODR o, int which);
 235 YAZ_EXPORT Z_SRW_recordVersion *yaz_srw_get_record_versions(ODR o, int num);
 236 YAZ_EXPORT Z_SRW_extra_record *yaz_srw_get_extra_record(ODR o);
 237 YAZ_EXPORT Z_SRW_record *yaz_srw_get_record(ODR o);
 238 YAZ_EXPORT Z_SRW_record *yaz_srw_get_records(ODR o, int num);
 239
 240 YAZ_EXPORT int yaz_diag_bib1_to_srw (int bib1_code);
 241
 242 YAZ_EXPORT int yaz_diag_srw_to_bib1(int srw_code);
 243
 244 YAZ_EXPORT const char *yaz_srw_pack_to_str(int pack);
 245 YAZ_EXPORT int yaz_srw_str_to_pack(const char *str);
 246
 247 /** \brief deprecated */
 248 YAZ_EXPORT char *yaz_uri_val(const char *path, const char *name, ODR o);
 249
 250 /** \brief deprecated */
 251 YAZ_EXPORT void yaz_uri_val_int(const char *path, const char *name,
 252                                 ODR o, Odr_int **intp);
 253
 254 YAZ_EXPORT int yaz_uri_to_array(const char *path, ODR o,
 255                                 char ***name, char ***val);
 256 YAZ_EXPORT void yaz_array_to_uri(char **path, ODR o,
 257                                  char **name, char **value);
 258
 259 /** \brief encodes URI component
 260     \param dst destination string (should be at least 3*strlen(uri)+1)
 261     \param uri URI component C-string (source)
 262 */
 263 YAZ_EXPORT void yaz_encode_uri_component(char *dst, const char *uri);
 264
 265 /** \brief decodes URI component
 266     \param dst destination string (should be at least strlen(uri)+1)
 267     \param uri URI component buffer (source)
 268     \param len number of bytes to decode from uri
 269 */
 270 YAZ_EXPORT void yaz_decode_uri_component(char *dst, const char *uri,
 271                                          size_t len);
 272
 273 YAZ_EXPORT int yaz_srw_decode(Z_HTTP_Request *hreq, Z_SRW_PDU **srw_pdu,
 274                               Z_SOAP **soap_package, ODR decode, char **charset);
 275
 276 YAZ_EXPORT int yaz_sru_decode(Z_HTTP_Request *hreq, Z_SRW_PDU **srw_pdu,
 277                               Z_SOAP **soap_package, ODR decode,
 278                               char **charset,
 279                               Z_SRW_diagnostic **, int *num_diagnostic);
 280
 281 /** \brief decode SOLR response (HTTP)
 282     \param o ODR for result
 283     \param hres HTTP response to be decoded
 284     \param pdup SRW response pointer (set if successful)
 285     \retval -1 fail
 286     \retval 0 OK
 287 */
 288 YAZ_EXPORT int yaz_solr_decode_response(ODR o, Z_HTTP_Response *hres,
 289                                         Z_SRW_PDU **pdup);
 290
 291
 292 YAZ_EXPORT void yaz_add_srw_diagnostic(ODR o, Z_SRW_diagnostic **d,
 293                                        int *num, int code,
 294                                        const char *addinfo);
 295
 296 YAZ_EXPORT void yaz_add_sru_update_diagnostic(ODR o, Z_SRW_diagnostic **d,
 297                                               int *num, int code,
 298                                               const char *addinfo);
 299
 300 YAZ_EXPORT void yaz_mk_std_diagnostic(ODR o, Z_SRW_diagnostic *d,
 301                                       int code, const char *details);
 302
 303 YAZ_EXPORT void yaz_add_srw_diagnostic_uri(ODR o, Z_SRW_diagnostic **d,
 304                                            int *num, const char *uri,
 305                                            const char *message,
 306                                            const char *details);
 307
 308 YAZ_EXPORT void yaz_mk_srw_diagnostic(ODR o, Z_SRW_diagnostic *d,
 309                                       const char *uri, const char *message,
 310                                       const char *details);
 311
 312 YAZ_EXPORT int yaz_sru_get_encode(Z_HTTP_Request *hreq, Z_SRW_PDU *srw_pdu,
 313                                   ODR encode, const char *charset);
 314 YAZ_EXPORT int yaz_sru_post_encode(Z_HTTP_Request *hreq, Z_SRW_PDU *srw_pdu,
 315                                    ODR encode, const char *charset);
 316 YAZ_EXPORT int yaz_sru_soap_encode(Z_HTTP_Request *hreq, Z_SRW_PDU *srw_pdu,
 317                                    ODR odr, const char *charset);
 318
 319 /** \brief encode SOLR request (HTTP)
 320     \param hreq HTTP request to be modified (with encoded request)
 321     \param srw_pdu SRW request
 322     \param encode ODR for result
 323     \param charset character set for request (may be NULL)
 324     \retval -1 fail
 325     \retval 0 OK
 326 */
 327 YAZ_EXPORT int yaz_solr_encode_request(Z_HTTP_Request *hreq, Z_SRW_PDU *srw_pdu,
 328                                        ODR encode, const char *charset);
 329
 330 YAZ_EXPORT char *yaz_negotiate_sru_version(char *input_ver);
 331
 332 YAZ_EXPORT
 333 void yaz_encode_sru_extra(Z_SRW_PDU *sr, ODR odr, const char *extra_args);
 334
 335
 336 #define YAZ_XMLNS_SRU_v1_0 "http://www.loc.gov/zing/srw/v1.0/"
 337 #define YAZ_XMLNS_SRU_v1_1 "http://www.loc.gov/zing/srw/"
 338 #define YAZ_XMLNS_DIAG_v1_1 "http://www.loc.gov/zing/srw/diagnostic/"
 339 #define YAZ_XMLNS_UPDATE_v0_9 "http://www.loc.gov/zing/srw/update/"
 340 #define YAZ_XMLNS_SRU_v2_mask "http://docs.oasis-open.org/ns/search-ws/*"
 341 #define YAZ_XMLNS_SRU_v1_response "http://www.loc.gov/*"
 342
 343 YAZ_EXPORT
 344 int yaz_srw_check_content_type(Z_HTTP_Response *hres);
 345
 346 YAZ_EXPORT
 347 int sru_decode_surrogate_diagnostics(const char *buf, size_t len,
 348                                      Z_SRW_diagnostic **diag,
 349                                      int *num, ODR odr);
 350
 351 YAZ_EXPORT
 352 void yaz_mk_sru_surrogate(ODR o, Z_SRW_record *record, int pos,
 353                           int code, const char *details);
 354
 355 /** \brief encode SRU database for HTTP path
 356     \param out memory handle for resulting encoded database string
 357     \param db source database
 358     \returns encoded database path (includes leading /)
 359 */
 360 YAZ_EXPORT
 361 char *yaz_encode_sru_dbpath_odr(ODR out, const char *db);
 362
 363 /** \brief encode SRU database for HTTP path
 364     \param dst destination buffer (should be at least strlen(db) +2 in size)
 365     \param db source database
 366
 367     The resulting database (dst) includes a leading /
 368 */
 369 YAZ_EXPORT
 370 void yaz_encode_sru_dbpath_buf(char *dst, const char *db);
 371
 372 YAZ_END_CDECL
 373
 374 #endif
 375 /*
 376  * Local variables:
 377  * c-basic-offset: 4
 378  * c-file-style: "Stroustrup"
 379  * indent-tabs-mode: nil
 380  * End:
 381  * vim: shiftwidth=4 tabstop=8 expandtab
 382  */
 383