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