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 typedef struct {
  51     char *setname;             /* name to give to this set */
  52     int replace_set;           /* replace set, if it already exists */
  53     int num_bases;             /* number of databases in list */
  54     char **basenames;          /* databases to search */
  55     Z_ReferenceId *referenceId;/* reference ID */
  56     Z_Query *query;            /* query structure */
  57     ODR stream;                /* encode stream */
  58     ODR decode;                /* decode stream */
  59     ODR print;                 /* print stream */
  60
  61     bend_request request;
  62     bend_association association;
  63     int *fd;
  64     Odr_int hits;                  /* number of hits */
  65     int errcode;               /* 0==OK */
  66     char *errstring;           /* system error string or NULL */
  67     Z_OtherInformation *search_info; /* additional search info */
  68     char *srw_sortKeys;        /* holds SRU/SRW sortKeys info */
  69     char *srw_setname;         /* holds SRU/SRW generated resultsetID */
  70     int *srw_setnameIdleTime;  /* holds SRU/SRW life-time */
  71     int estimated_hit_count;   /* if hit count is estimated */
  72     int partial_resultset;     /* if result set is partial */
  73     Z_SRW_extra_arg *extra_args; /* extra URL arguments */
  74     char *extra_response_data;   /* extra XML response. */
  75 } bend_search_rr;
  76
  77 /** \brief Information for present handler. Does not replace bend_fetch. */
  78 typedef struct {
  79     char *setname;             /* set name */
  80     int start;
  81     int number;                /* record number */
  82     Odr_oid *format;           /* format, transfer syntax (OID) */
  83     Z_ReferenceId *referenceId;/* reference ID */
  84     Z_RecordComposition *comp; /* Formatting instructions */
  85     ODR stream;                /* encoding stream - memory source if required */
  86     ODR print;                 /* printing stream */
  87     bend_request request;
  88     bend_association association;
  89
  90     int errcode;               /* 0==OK */
  91     char *errstring;           /* system error string or NULL */
  92 } bend_present_rr;
  93
  94 /** \brief Information for fetch record handler */
  95 typedef struct bend_fetch_rr {
  96     char *setname;             /* set name */
  97     int number;                /* record number */
  98     Z_ReferenceId *referenceId;/* reference ID */
  99     Odr_oid *request_format;        /* format, transfer syntax (OID) */
 100     Z_RecordComposition *comp; /* Formatting instructions */
 101     ODR stream;                /* encoding stream - memory source if req */
 102     ODR print;                 /* printing stream */
 103
 104     char *basename;            /* name of database that provided record */
 105     int len;                   /* length of record or -1 if structured */
 106     char *record;              /* record */
 107     int last_in_set;           /* is it?  */
 108     Odr_oid *output_format;        /* response format/syntax (OID) */
 109     int errcode;               /* 0==success */
 110     char *errstring;           /* system error string or NULL */
 111     int surrogate_flag;        /* surrogate diagnostic */
 112     char *schema;              /* string record schema input/output */
 113 } bend_fetch_rr;
 114
 115 /** \brief Information for scan entry */
 116 struct scan_entry {
 117     char *term;         /* the returned scan term */
 118     Odr_int occurrences;/* no of occurrences or -1 if error (see below) */
 119     int errcode;        /* Bib-1 diagnostic code; only used when occur.= -1 */
 120     char *errstring;    /* Additional string */
 121     char *display_term;
 122 };
 123
 124 typedef enum {
 125     BEND_SCAN_SUCCESS,  /* ok */
 126     BEND_SCAN_PARTIAL   /* not all entries could be found */
 127 } bend_scan_status;
 128
 129 /** \brief Information for SRU / Z39.50 scan handler */
 130 typedef struct bend_scan_rr {
 131     int num_bases;      /* number of elements in databaselist */
 132     char **basenames;   /* databases to search */
 133     Odr_oid *attributeset;
 134     Z_ReferenceId *referenceId; /* reference ID */
 135     Z_AttributesPlusTerm *term;
 136     ODR stream;         /* encoding stream - memory source if required */
 137     ODR print;          /* printing stream */
 138
 139     Odr_int *step_size;     /* step size */
 140     Odr_int term_position;  /* desired index of term in result list/returned */
 141     int num_entries;    /* number of entries requested/returned */
 142
 143     /* scan term entries. The called handler does not have
 144        to allocate this. Size of entries is num_entries (see above) */
 145     struct scan_entry *entries;
 146     bend_scan_status status;
 147     int errcode;
 148     char *errstring;
 149     char *scanClause;   /* CQL scan clause */
 150     char *setname;      /* Scan in result set (NULL if omitted) */
 151 } bend_scan_rr;
 152
 153 /** \brief Information for SRU record update handler */
 154 typedef struct bend_update_rr {
 155     int num_bases;      /* number of elements in databaselist */
 156     char **basenames;   /* databases to search */
 157     Z_ReferenceId *referenceId; /* reference ID */
 158     ODR stream;         /* encoding stream - memory source if required */
 159     ODR print;          /* printing stream */
 160     char *operation;
 161     char *operation_status;
 162     char *record_id;
 163     Z_SRW_recordVersion *record_versions;
 164     int num_versions;
 165     char *record_packing;
 166     char *record_schema;
 167     char *record_data;
 168     char *extra_record_data;
 169     char *extra_request_data;
 170     char *extra_response_data;
 171     char *uri;
 172     char *message;
 173     char *details;
 174 } bend_update_rr;
 175
 176 /** \brief Information for Z39.50 delete result set handler */
 177 typedef struct bend_delete_rr {
 178     int function;
 179     int num_setnames;
 180     char **setnames;
 181     Z_ReferenceId *referenceId;
 182     int delete_status;    /* status for the whole operation */
 183     Odr_int *statuses;    /* status each set - indexed as setnames */
 184     ODR stream;
 185     ODR print;
 186 } bend_delete_rr;
 187
 188 /** \brief Information for Z39.50 sort handler */
 189 typedef struct bend_sort_rr
 190 {
 191     int num_input_setnames;
 192     char **input_setnames;
 193     char *output_setname;
 194     Z_SortKeySpecList *sort_sequence;
 195     ODR stream;
 196     ODR print;
 197     Z_ReferenceId *referenceId;/* reference ID */
 198
 199     int sort_status;
 200     int errcode;
 201     char *errstring;
 202 } bend_sort_rr;
 203
 204 /** \brief Information for Z39.50 extended services handler */
 205 typedef struct bend_esrequest_rr
 206 {
 207     int ItemNo;
 208     Z_ExtendedServicesRequest *esr;
 209
 210     ODR stream;                /* encoding stream */
 211     ODR decode;                /* decoding stream */
 212     ODR print;                 /* printing stream */
 213     Z_ReferenceId *referenceId;/* reference ID */
 214     bend_request request;
 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_request request;
 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 YAZ_EXPORT void bend_request_send (bend_association a, bend_request req,
 325                                    Z_APDU *res);
 326
 327 YAZ_EXPORT bend_request bend_request_mk (bend_association a);
 328
 329 YAZ_EXPORT void bend_request_destroy (bend_request *req);
 330
 331 YAZ_EXPORT Z_ReferenceId *bend_request_getid (ODR odr, bend_request req);
 332 YAZ_EXPORT int bend_backend_respond (bend_association a, bend_request req);
 333 YAZ_EXPORT void bend_request_setdata(bend_request r, void *p);
 334 YAZ_EXPORT void *bend_request_getdata(bend_request r);
 335
 336 /** \brief control block for server */
 337 typedef struct statserv_options_block
 338 {
 339     int dynamic;                  /* fork on incoming requests */
 340     int threads;                  /* use threads */
 341     int one_shot;                 /* one session then exit(1) */
 342     char apdufile[ODR_MAXNAME+1]; /* file for pretty-printed PDUs */
 343     char logfile[ODR_MAXNAME+1];  /* file for diagnostic output */
 344     char default_listen[1024];    /* 0 == no default listen */
 345     enum oid_proto default_proto; /* PROTO_SR or PROTO_Z3950 */
 346     int idle_timeout;             /* how many minutes to wait before closing */
 347     int maxrecordsize;            /* maximum value for negotiation */
 348     char configname[ODR_MAXNAME+1];  /* given to the backend in bend_init */
 349     char setuid[ODR_MAXNAME+1];     /* setuid to this user after binding */
 350     void (*bend_start)(struct statserv_options_block *p);
 351     void (*bend_stop)(struct statserv_options_block *p);
 352     int (*options_func)(int argc, char **argv);
 353     int (*check_ip)(void *cd, const char *addr, int len, int type);
 354     char daemon_name[128];
 355     int inetd;                    /* Do we use the inet deamon or not */
 356
 357     void *handle;                 /* Handle */
 358     bend_initresult *(*bend_init)(bend_initrequest *r);
 359     void (*bend_close)(void *handle);
 360 #ifdef WIN32
 361     /* We only have these members for the windows version */
 362     /* They seemed a bit large to have them there in general */
 363     char service_name[128];         /* NT Service Name */
 364     char app_name[128];             /* Application Name */
 365     char service_dependencies[128]; /* The services we are dependent on */
 366     char service_display_name[128]; /* The service display name */
 367 #endif /* WIN32 */
 368     struct bend_soap_handler *soap_handlers;
 369     char pid_fname[128];            /* pid fname */
 370     int background;                 /* auto daemon */
 371     char cert_fname[128];           /* SSL certificate fname */
 372     char xml_config[128];           /* XML config filename */
 373 } statserv_options_block;
 374
 375 YAZ_EXPORT int statserv_main(
 376     int argc, char **argv,
 377     bend_initresult *(*bend_init)(bend_initrequest *r),
 378     void (*bend_close)(void *handle));
 379 YAZ_EXPORT statserv_options_block *statserv_getcontrol(void);
 380 YAZ_EXPORT void statserv_setcontrol(statserv_options_block *block);
 381 YAZ_EXPORT int check_ip_tcpd(void *cd, const char *addr, int len, int type);
 382
 383 YAZ_EXPORT int bend_assoc_is_alive(bend_association assoc);
 384
 385 YAZ_END_CDECL
 386
 387 #endif
 388 /*
 389  * Local variables:
 390  * c-basic-offset: 4
 391  * c-file-style: "Stroustrup"
 392  * indent-tabs-mode: nil
 393  * End:
 394  * vim: shiftwidth=4 tabstop=8 expandtab
 395  */
 396