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