include/yaz/backend.h

   1 /* This file is part of the YAZ toolkit.
   2  * Copyright (C) 1995-2009 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 backend.h
  30  * \brief Header for GFS
  31  *
  32  * This header includes all public definitions for the
  33  * Generic Frontend Server (GFS).
  34  */
  35
  36 #ifndef BACKEND_H
  37 #define BACKEND_H
  38
  39 #include <yaz/yconfig.h>
  40 #include <yaz/proto.h>
  41 #include <yaz/srw.h>
  42 #include <yaz/oid_db.h>
  43
  44 YAZ_BEGIN_CDECL
  45
  46 typedef struct request *bend_request;
  47 typedef struct association *bend_association;
  48
  49 /** \brief Information for Z39.50/SRU search handler
  50
  51     This structure is passed to the search handler. Some members
  52     are read-only (input), some are read-write (input and ouput),
  53     and others are write-only.
  54  */
  55 typedef struct {
  56     char *setname;             /**< result set ID (input) */
  57     int replace_set;           /**< replace set indicator (input) */
  58     int num_bases;             /**< number of databases (input) */
  59     char **basenames;          /**< databases to search (input) */
  60     Z_ReferenceId *referenceId;/**< reference ID (input) */
  61     Z_Query *query;            /**< query structure (input) */
  62     ODR stream;                /**< encode stream (input) */
  63     ODR decode;                /**< decode stream (input) */
  64     ODR print;                 /**< print stream (input) */
  65
  66     bend_request request;      /**< GFS request handle (input) */
  67     bend_association association; /**< GFS association / sesssion (input) */
  68     int *fd;                   /**< select fd - not working (output) */
  69     Odr_int hits;              /**< hits (output) */
  70     int errcode;               /**< Diagnostic code / 0 for no error (output) */
  71     char *errstring;           /**< Additional info (output) */
  72     Z_OtherInformation *search_info; /**< extra search info result (output) */
  73     char *srw_sortKeys;        /**< SRU sortKeys info (input) */
  74     char *srw_setname;         /**< SRU generated resultsetID (output) */
  75     int *srw_setnameIdleTime;  /**< SRU result set idle time (output) */
  76     int estimated_hit_count;   /**< 1=estimated hits; 0=exact (output) */
  77     int partial_resultset;     /**< 1=partial results; 0=full (output)*/
  78     Z_SRW_extra_arg *extra_args; /**< SRU extra request parameters (input) */
  79     char *extra_response_data;   /**< SRW extra XML response (output) */
  80 } bend_search_rr;
  81
  82 /** \brief Information for present handler. Does not replace bend_fetch. */
  83 typedef struct {
  84     char *setname;             /**< result set ID (input) */
  85     int start;                 /**< range start, starting from 1 (input) */
  86     int number;                /**< number of records to fetch (input) */
  87     Odr_oid *format;           /**< record syntax OID (input) */
  88     Z_ReferenceId *referenceId;/**< reference ID (input) */
  89     Z_RecordComposition *comp; /**< Formatting instructions (input) */
  90     ODR stream;                /**< encoding stream (input) */
  91     ODR print;                 /**< printing stream (input) */
  92     bend_request request;      /**< GFS request handle (input) */
  93     bend_association association; /**< GFS association / sesssion (input) */
  94
  95     int errcode;               /**< Diagnostic code / 0 for no error (output) */
  96     char *errstring;           /**< Additional info (output) */
  97 } bend_present_rr;
  98
  99 /** \brief Information for fetch record handler */
 100 typedef struct bend_fetch_rr {
 101     char *setname;             /**< result set ID (input) */
 102     int number;                /**< record position (1,2,etc) (input) */
 103     Z_ReferenceId *referenceId;/**< reference ID (input) */
 104     Odr_oid *request_format;   /**< record syntax OID (input) */
 105     Z_RecordComposition *comp; /**< Formatting instructions (input) */
 106     ODR stream;                /**< encoding stream (input) */
 107     ODR print;                 /**< printing stream (input) */
 108
 109     char *basename;            /**< name of database for record (output) */
 110     int len;                   /**< record length or -1 if structured (output)*/
 111     char *record;              /**< record buffer (output) */
 112     int last_in_set;           /**< 1=last in set; 0=not last (output)  */
 113     Odr_oid *output_format;    /**< record syntax OIT (output) */
 114     int errcode;               /**< Diagnostic code / 0 for no error (output) */
 115     char *errstring;           /**< Additional info (output) */
 116     int surrogate_flag;        /**< 1=surrogate diagnostic(SD); 0=NSD (output)*/
 117     char *schema;              /**< string record schema (input/output) */
 118 } bend_fetch_rr;
 119
 120 /** \brief Information for scan entry */
 121 struct scan_entry {
 122     char *term;         /**< the returned scan term (output) */
 123     Odr_int occurrences;/**< >=hits or -1 if error (output) */
 124     int errcode;        /**< Bib-1 diagnostic; only when occur = -1 (output) */
 125     char *errstring;    /**< Additional string (output) */
 126     char *display_term;
 127 };
 128
 129 typedef enum {
 130     BEND_SCAN_SUCCESS,  /**< ok */
 131     BEND_SCAN_PARTIAL   /**< not all entries could be found */
 132 } bend_scan_status;
 133
 134 /** \brief Information for SRU / Z39.50 scan handler */
 135 typedef struct bend_scan_rr {
 136     int num_bases;      /**< number of databases (input) */
 137     char **basenames;   /**< databases to scan (input) */
 138     Odr_oid *attributeset; /**< attribute-set for term (input) */
 139     Z_ReferenceId *referenceId; /**< reference ID (input) */
 140     Z_AttributesPlusTerm *term; /**< start term (input) */
 141     ODR stream;         /**< encoding stream (input) */
 142     ODR print;          /**< printing stream (input) */
 143
 144     Odr_int *step_size;     /**< step size */
 145     Odr_int term_position;  /**< desired index of term in result list/returned */
 146     int num_entries;    /**< number of entries requested/returned */
 147
 148     /* scan term entries. The called handler does not have
 149        to allocate this. Size of entries is num_entries (see above) */
 150     struct scan_entry *entries;
 151     bend_scan_status status;
 152     int errcode;
 153     char *errstring;
 154     char *scanClause;   /**< CQL scan clause */
 155     char *setname;      /**< Scan in result set (NULL if omitted) */
 156 } bend_scan_rr;
 157
 158 /** \brief Information for SRU record update handler */
 159 typedef struct bend_update_rr {
 160     int num_bases;      /**< number of databases (input) */
 161     char **basenames;   /**< databases to update (input) */
 162     Z_ReferenceId *referenceId; /**< reference ID (input) */
 163     ODR stream;         /**< encoding stream (input) */
 164     ODR print;          /**< printing stream (input) */
 165     char *operation;
 166     char *operation_status;
 167     char *record_id;
 168     Z_SRW_recordVersion *record_versions;
 169     int num_versions;
 170     char *record_packing;
 171     char *record_schema;
 172     char *record_data;
 173     char *extra_record_data;
 174     char *extra_request_data;
 175     char *extra_response_data;
 176     char *uri;
 177     char *message;
 178     char *details;
 179 } bend_update_rr;
 180
 181 /** \brief Information for Z39.50 delete result set handler */
 182 typedef struct bend_delete_rr {
 183     int function;
 184     int num_setnames;
 185     char **setnames;
 186     Z_ReferenceId *referenceId;
 187     int delete_status;    /**< status for the whole operation */
 188     Odr_int *statuses;    /**< status each set - indexed as setnames */
 189     ODR stream;
 190     ODR print;
 191 } bend_delete_rr;
 192
 193 /** \brief Information for Z39.50 sort handler */
 194 typedef struct bend_sort_rr
 195 {
 196     int num_input_setnames;
 197     char **input_setnames;
 198     char *output_setname;
 199     Z_SortKeySpecList *sort_sequence;
 200     ODR stream;
 201     ODR print;
 202     Z_ReferenceId *referenceId;
 203
 204     int sort_status;
 205     int errcode;
 206     char *errstring;
 207 } bend_sort_rr;
 208
 209 /** \brief Information for Z39.50 extended services handler */
 210 typedef struct bend_esrequest_rr
 211 {
 212     int ItemNo;
 213     Z_ExtendedServicesRequest *esr;
 214
 215     ODR stream;                /* encoding stream */
 216     ODR decode;                /* decoding stream */
 217     ODR print;                 /* printing stream */
 218     Z_ReferenceId *referenceId;/* reference ID */
 219     bend_request request;
 220     bend_association association;
 221     int errcode;               /* 0==success, -1==accepted, >0 = failure */
 222     char *errstring;           /* system error string or NULL */
 223     Z_TaskPackage *taskPackage;
 224 } bend_esrequest_rr;
 225
 226 /** \brief Information for Z39.50 segment handler */
 227 typedef struct bend_segment_rr {
 228     Z_Segment *segment;
 229     ODR stream;
 230     ODR decode;
 231     ODR print;
 232     bend_request request;
 233     bend_association association;
 234 } bend_segment_rr;
 235
 236 /** \brief Information for SRU Explain handler */
 237 typedef struct {
 238     ODR stream;
 239     ODR decode;
 240     ODR print;
 241     char *explain_buf;
 242     char *database;
 243     char *schema;
 244     void *server_node_ptr;
 245 } bend_explain_rr;
 246
 247 /** \brief Information for the Init handler
 248
 249 This includes both request
 250 information (to be read) and response information which should be
 251 set by the bend_init handler
 252 */
 253 typedef struct bend_initrequest
 254 {
 255     /** \brief user/name/password to be read */
 256     Z_IdAuthentication *auth;
 257     /** \brief encoding stream (for results) */
 258     ODR stream;
 259     /** \brief printing stream */
 260     ODR print;
 261     /** \brief decoding stream (use stream for results) */
 262     ODR decode;
 263     /** \brief reference ID */
 264     Z_ReferenceId *referenceId;
 265     /** \brief peer address of client */
 266     char *peer_name;
 267
 268     /** \brief character set and language negotiation
 269
 270     see include/yaz/z-charneg.h
 271     */
 272     Z_CharSetandLanguageNegotiation *charneg_request;
 273
 274     /** \brief character negotiation response */
 275     Z_External *charneg_response;
 276
 277     /** \brief character set (encoding) for query terms
 278
 279     This is NULL by default. It should be set to the native character
 280     set that the backend assumes for query terms */
 281     char *query_charset;
 282
 283     /** \brief whehter query_charset also applies to recors
 284
 285     Is 0 (No) by default. Set to 1 (yes) if records is in the same
 286     character set as queries. If in doubt, use 0 (No).
 287     */
 288     int records_in_same_charset;
 289
 290     char *implementation_id;
 291     char *implementation_name;
 292     char *implementation_version;
 293
 294     /** \brief Z39.50 sort handler */
 295     int (*bend_sort)(void *handle, bend_sort_rr *rr);
 296     /** \brief SRU/Z39.50 search handler */
 297     int (*bend_search)(void *handle, bend_search_rr *rr);
 298     /** \brief SRU/Z39.50 fetch handler */
 299     int (*bend_fetch)(void *handle, bend_fetch_rr *rr);
 300     /** \brief SRU/Z39.50 present handler */
 301     int (*bend_present)(void *handle, bend_present_rr *rr);
 302     /** \brief Z39.50 extended services handler */
 303     int (*bend_esrequest) (void *handle, bend_esrequest_rr *rr);
 304     /** \brief Z39.50 delete result set handler */
 305     int (*bend_delete)(void *handle, bend_delete_rr *rr);
 306     /** \brief Z39.50 scan handler */
 307     int (*bend_scan)(void *handle, bend_scan_rr *rr);
 308     /** \brief Z39.50 segment facility handler */
 309     int (*bend_segment)(void *handle, bend_segment_rr *rr);
 310     /** \brief SRU explain handler */
 311     int (*bend_explain)(void *handle, bend_explain_rr *rr);
 312     /** \brief SRU scan handler */
 313     int (*bend_srw_scan)(void *handle, bend_scan_rr *rr);
 314     /** \brief SRU record update handler */
 315     int (*bend_srw_update)(void *handle, bend_update_rr *rr);
 316
 317     /** \brief whether named result sets are supported (0=disable, 1=enable) */
 318     int named_result_sets;
 319 } bend_initrequest;
 320
 321 /** \brief result for init handler (must be filled by handler) */
 322 typedef struct bend_initresult
 323 {
 324     int errcode;               /* 0==OK */
 325     char *errstring;           /* system error string or NULL */
 326     void *handle;              /* private handle to the backend module */
 327 } bend_initresult;
 328
 329 YAZ_EXPORT void bend_request_send (bend_association a, bend_request req,
 330                                    Z_APDU *res);
 331
 332 YAZ_EXPORT bend_request bend_request_mk (bend_association a);
 333
 334 YAZ_EXPORT void bend_request_destroy (bend_request *req);
 335
 336 YAZ_EXPORT Z_ReferenceId *bend_request_getid (ODR odr, bend_request req);
 337 YAZ_EXPORT int bend_backend_respond (bend_association a, bend_request req);
 338 YAZ_EXPORT void bend_request_setdata(bend_request r, void *p);
 339 YAZ_EXPORT void *bend_request_getdata(bend_request r);
 340
 341 /** \brief control block for server */
 342 typedef struct statserv_options_block
 343 {
 344     int dynamic;                  /**< fork on incoming requests */
 345     int threads;                  /**< use threads */
 346     int one_shot;                 /**< one session then exit(1) */
 347     char apdufile[ODR_MAXNAME+1]; /**< file for pretty-printed PDUs */
 348     char logfile[ODR_MAXNAME+1];  /**< file for diagnostic output */
 349     char default_listen[1024];    /**< 0 == no default listen */
 350     enum oid_proto default_proto; /**< PROTO_SR or PROTO_Z3950 */
 351     int idle_timeout;             /**< how many minutes to wait before closing */
 352     int maxrecordsize;            /**< maximum value for negotiation */
 353     char configname[ODR_MAXNAME+1]; /**< given to the backend in bend_init */
 354     char setuid[ODR_MAXNAME+1];     /**< setuid to this user after binding */
 355     void (*bend_start)(struct statserv_options_block *p);
 356     void (*bend_stop)(struct statserv_options_block *p);
 357     int (*options_func)(int argc, char **argv);
 358     int (*check_ip)(void *cd, const char *addr, int len, int type);
 359     char daemon_name[128];
 360     int inetd;                    /**< Do we use the inet deamon or not */
 361
 362     void *handle;                 /**< Handle */
 363     bend_initresult *(*bend_init)(bend_initrequest *r);
 364     void (*bend_close)(void *handle);
 365 #ifdef WIN32
 366     /* We only have these members for the windows version */
 367     /* They seemed a bit large to have them there in general */
 368     char service_name[128];         /**< NT Service Name */
 369     char app_name[128];             /**< Application Name */
 370     char service_dependencies[128]; /**< The services we are dependent on */
 371     char service_display_name[128]; /**< The service display name */
 372 #endif /* WIN32 */
 373     struct bend_soap_handler *soap_handlers;
 374     char pid_fname[128];            /**< pid fname */
 375     int background;                 /**< auto daemon */
 376     char cert_fname[128];           /**< SSL certificate fname */
 377     char xml_config[128];           /**< XML config filename */
 378 } statserv_options_block;
 379
 380 YAZ_EXPORT int statserv_main(
 381     int argc, char **argv,
 382     bend_initresult *(*bend_init)(bend_initrequest *r),
 383     void (*bend_close)(void *handle));
 384 YAZ_EXPORT statserv_options_block *statserv_getcontrol(void);
 385 YAZ_EXPORT void statserv_setcontrol(statserv_options_block *block);
 386 YAZ_EXPORT int check_ip_tcpd(void *cd, const char *addr, int len, int type);
 387
 388 YAZ_EXPORT int bend_assoc_is_alive(bend_association assoc);
 389
 390 YAZ_END_CDECL
 391
 392 #endif
 393 /*
 394  * Local variables:
 395  * c-basic-offset: 4
 396  * c-file-style: "Stroustrup"
 397  * indent-tabs-mode: nil
 398  * End:
 399  * vim: shiftwidth=4 tabstop=8 expandtab
 400  */
 401