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