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     char *extra_response_data;   /**< SRW extra XML response (output) */
 155 } bend_scan_rr;
 156
 157 /** \brief Information for SRU record update handler */
 158 typedef struct bend_update_rr {
 159     int num_bases;      /**< number of databases (input) */
 160     char **basenames;   /**< databases to update (input) */
 161     Z_ReferenceId *referenceId; /**< reference ID (input) */
 162     ODR stream;         /**< encoding stream (input) */
 163     ODR print;          /**< printing stream (input) */
 164     char *operation;
 165     char *operation_status;
 166     char *record_id;
 167     Z_SRW_recordVersion *record_versions;
 168     int num_versions;
 169     char *record_packing;
 170     char *record_schema;
 171     char *record_data;
 172     char *extra_record_data;
 173     char *extra_request_data;
 174     char *extra_response_data;
 175     char *uri;
 176     char *message;
 177     char *details;
 178 } bend_update_rr;
 179
 180 /** \brief Information for Z39.50 delete result set handler */
 181 typedef struct bend_delete_rr {
 182     int function;
 183     int num_setnames;
 184     char **setnames;
 185     Z_ReferenceId *referenceId;
 186     int delete_status;    /**< status for the whole operation */
 187     int *statuses;    /**< status each set - indexed as setnames */
 188     ODR stream;
 189     ODR print;
 190 } bend_delete_rr;
 191
 192 /** \brief Information for Z39.50 sort handler */
 193 typedef struct bend_sort_rr
 194 {
 195     int num_input_setnames;
 196     char **input_setnames;
 197     char *output_setname;
 198     Z_SortKeySpecList *sort_sequence;
 199     ODR stream;
 200     ODR print;
 201     Z_ReferenceId *referenceId;
 202
 203     int sort_status;
 204     int errcode;
 205     char *errstring;
 206 } bend_sort_rr;
 207
 208 /** \brief Information for Z39.50 extended services handler */
 209 typedef struct bend_esrequest_rr
 210 {
 211     int ItemNo;
 212     Z_ExtendedServicesRequest *esr;
 213
 214     ODR stream;                /* encoding stream */
 215     ODR decode;                /* decoding stream */
 216     ODR print;                 /* printing stream */
 217     Z_ReferenceId *referenceId;/* reference ID */
 218     bend_association association;
 219     int errcode;               /* 0==success, -1==accepted, >0 = failure */
 220     char *errstring;           /* system error string or NULL */
 221     Z_TaskPackage *taskPackage;
 222 } bend_esrequest_rr;
 223
 224 /** \brief Information for Z39.50 segment handler */
 225 typedef struct bend_segment_rr {
 226     Z_Segment *segment;
 227     ODR stream;
 228     ODR decode;
 229     ODR print;
 230     bend_association association;
 231 } bend_segment_rr;
 232
 233 /** \brief Information for SRU Explain handler */
 234 typedef struct {
 235     ODR stream;
 236     ODR decode;
 237     ODR print;
 238     char *explain_buf;
 239     char *database;
 240     char *schema;
 241     void *server_node_ptr;
 242 } bend_explain_rr;
 243
 244 /** \brief Information for the Init handler
 245
 246 This includes both request
 247 information (to be read) and response information which should be
 248 set by the bend_init handler
 249 */
 250 typedef struct bend_initrequest
 251 {
 252     /** \brief user/name/password to be read */
 253     Z_IdAuthentication *auth;
 254     /** \brief encoding stream (for results) */
 255     ODR stream;
 256     /** \brief printing stream */
 257     ODR print;
 258     /** \brief decoding stream (use stream for results) */
 259     ODR decode;
 260     /** \brief reference ID */
 261     Z_ReferenceId *referenceId;
 262     /** \brief peer address of client */
 263     char *peer_name;
 264
 265     /** \brief character set and language negotiation
 266
 267     see include/yaz/z-charneg.h
 268     */
 269     Z_CharSetandLanguageNegotiation *charneg_request;
 270
 271     /** \brief character negotiation response */
 272     Z_External *charneg_response;
 273
 274     /** \brief character set (encoding) for query terms
 275
 276     This is NULL by default. It should be set to the native character
 277     set that the backend assumes for query terms */
 278     char *query_charset;
 279
 280     /** \brief whehter query_charset also applies to recors
 281
 282     Is 0 (No) by default. Set to 1 (yes) if records is in the same
 283     character set as queries. If in doubt, use 0 (No).
 284     */
 285     int records_in_same_charset;
 286
 287     char *implementation_id;
 288     char *implementation_name;
 289     char *implementation_version;
 290
 291     /** \brief Z39.50 sort handler */
 292     int (*bend_sort)(void *handle, bend_sort_rr *rr);
 293     /** \brief SRU/Z39.50 search handler */
 294     int (*bend_search)(void *handle, bend_search_rr *rr);
 295     /** \brief SRU/Z39.50 fetch handler */
 296     int (*bend_fetch)(void *handle, bend_fetch_rr *rr);
 297     /** \brief SRU/Z39.50 present handler */
 298     int (*bend_present)(void *handle, bend_present_rr *rr);
 299     /** \brief Z39.50 extended services handler */
 300     int (*bend_esrequest) (void *handle, bend_esrequest_rr *rr);
 301     /** \brief Z39.50 delete result set handler */
 302     int (*bend_delete)(void *handle, bend_delete_rr *rr);
 303     /** \brief Z39.50 scan handler */
 304     int (*bend_scan)(void *handle, bend_scan_rr *rr);
 305     /** \brief Z39.50 segment facility handler */
 306     int (*bend_segment)(void *handle, bend_segment_rr *rr);
 307     /** \brief SRU explain handler */
 308     int (*bend_explain)(void *handle, bend_explain_rr *rr);
 309     /** \brief SRU scan handler */
 310     int (*bend_srw_scan)(void *handle, bend_scan_rr *rr);
 311     /** \brief SRU record update handler */
 312     int (*bend_srw_update)(void *handle, bend_update_rr *rr);
 313
 314     /** \brief whether named result sets are supported (0=disable, 1=enable) */
 315     int named_result_sets;
 316 } bend_initrequest;
 317
 318 /** \brief result for init handler (must be filled by handler) */
 319 typedef struct bend_initresult
 320 {
 321     int errcode;               /* 0==OK */
 322     char *errstring;           /* system error string or NULL */
 323     void *handle;              /* private handle to the backend module */
 324 } bend_initresult;
 325
 326 /** \brief control block for server */
 327 typedef struct statserv_options_block
 328 {
 329     int dynamic;                  /**< fork on incoming requests */
 330     int threads;                  /**< use threads */
 331     int one_shot;                 /**< one session then exit(1) */
 332     char apdufile[ODR_MAXNAME+1]; /**< file for pretty-printed PDUs */
 333     char logfile[ODR_MAXNAME+1];  /**< file for diagnostic output */
 334     char default_listen[1024];    /**< 0 == no default listen */
 335     enum oid_proto default_proto; /**< PROTO_SR or PROTO_Z3950 */
 336     int idle_timeout;             /**< how many minutes to wait before closing */
 337     int maxrecordsize;            /**< maximum value for negotiation */
 338     char configname[ODR_MAXNAME+1]; /**< given to the backend in bend_init */
 339     char setuid[ODR_MAXNAME+1];     /**< setuid to this user after binding */
 340     void (*bend_start)(struct statserv_options_block *p);
 341     void (*bend_stop)(struct statserv_options_block *p);
 342     int (*options_func)(int argc, char **argv);
 343     int (*check_ip)(void *cd, const char *addr, int len, int type);
 344     char daemon_name[128];
 345     int inetd;                    /**< Do we use the inet deamon or not */
 346
 347     void *handle;                 /**< Handle */
 348     bend_initresult *(*bend_init)(bend_initrequest *r);
 349     void (*bend_close)(void *handle);
 350 #ifdef WIN32
 351     /* We only have these members for the windows version */
 352     /* They seemed a bit large to have them there in general */
 353     char service_name[128];         /**< NT Service Name */
 354     char app_name[128];             /**< Application Name */
 355     char service_dependencies[128]; /**< The services we are dependent on */
 356     char service_display_name[128]; /**< The service display name */
 357 #endif /* WIN32 */
 358     struct bend_soap_handler *soap_handlers;
 359     char pid_fname[128];            /**< pid fname */
 360     int background;                 /**< auto daemon */
 361     char cert_fname[128];           /**< SSL certificate fname */
 362     char xml_config[128];           /**< XML config filename */
 363     int keepalive;                  /**< keep alive if HTTP 1.1 (default: 1) */
 364 } statserv_options_block;
 365
 366 YAZ_EXPORT int statserv_main(
 367     int argc, char **argv,
 368     bend_initresult *(*bend_init)(bend_initrequest *r),
 369     void (*bend_close)(void *handle));
 370
 371 YAZ_EXPORT statserv_options_block *statserv_getcontrol(void);
 372 YAZ_EXPORT void statserv_setcontrol(statserv_options_block *block);
 373 YAZ_EXPORT int check_ip_tcpd(void *cd, const char *addr, int len, int type);
 374
 375 YAZ_EXPORT int bend_assoc_is_alive(bend_association assoc);
 376
 377 YAZ_END_CDECL
 378
 379 #endif
 380 /*
 381  * Local variables:
 382  * c-basic-offset: 4
 383  * c-file-style: "Stroustrup"
 384  * indent-tabs-mode: nil
 385  * End:
 386  * vim: shiftwidth=4 tabstop=8 expandtab
 387  */
 388