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