include/proto.h

   1 /*
   2  * Copyright (c) 1995, Index Data.
   3  *
   4  * Permission to use, copy, modify, distribute, and sell this software and
   5  * its documentation, in whole or in part, for any purpose, is hereby granted,
   6  * provided that:
   7  *
   8  * 1. This copyright and permission notice appear in all copies of the
   9  * software and its documentation. Notices of copyright or attribution
  10  * which appear at the beginning of any file must remain unchanged.
  11  *
  12  * 2. The name of Index Data or the individual authors may not be used to
  13  * endorse or promote products derived from this software without specific
  14  * prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
  17  * EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  18  * WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  19  * IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
  20  * INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
  21  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
  22  * NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
  23  * LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  24  * OF THIS SOFTWARE.
  25  *
  26  * $Log: proto.h,v $
  27  * Revision 1.7  1995-05-16 08:50:37  quinn
  28  * License, documentation, and memory fixes
  29  *
  30  * Revision 1.6  1995/05/15  11:55:55  quinn
  31  * Work on asynchronous activity.
  32  *
  33  * Revision 1.5  1995/04/17  11:28:18  quinn
  34  * Smallish
  35  *
  36  * Revision 1.4  1995/04/10  10:22:47  quinn
  37  * Added SCAN
  38  *
  39  * Revision 1.3  1995/03/30  12:18:09  quinn
  40  * Added info.
  41  *
  42  * Revision 1.2  1995/03/30  10:26:48  quinn
  43  * Added Term structure
  44  *
  45  * Revision 1.1  1995/03/30  09:39:42  quinn
  46  * Moved .h files to include directory
  47  *
  48  * Revision 1.11  1995/03/30  09:08:44  quinn
  49  * Added Resource control protocol
  50  *
  51  * Revision 1.10  1995/03/29  15:39:39  quinn
  52  * Adding some resource control elements, and a null-check to getentbyoid
  53  *
  54  * Revision 1.9  1995/03/29  08:06:18  quinn
  55  * Added a few v3 elements
  56  *
  57  * Revision 1.8  1995/03/22  10:12:49  quinn
  58  * Added Z_PRES constants.
  59  *
  60  * Revision 1.7  1995/03/20  09:45:12  quinn
  61  * Working towards v3
  62  *
  63  * Revision 1.5  1995/03/07  16:29:34  quinn
  64  * Added authentication stuff.
  65  *
  66  * Revision 1.4  1995/03/07  10:13:00  quinn
  67  * Added prototype for z_APDU()
  68  *
  69  * Revision 1.3  1995/02/14  11:54:23  quinn
  70  * Fixing include.
  71  *
  72  * Revision 1.2  1995/02/09  15:51:40  quinn
  73  * Works better now.
  74  *
  75  * Revision 1.1  1995/02/06  16:44:48  quinn
  76  * First hack at Z/SR protocol
  77  *
  78  */
  79
  80 #ifndef PROTO_H
  81 #define PROTO_H
  82
  83 #include <odr.h>
  84 #include <odr_use.h>
  85
  86 /* ----------------- GLOBAL AUXILIARY DEFS ----------------*/
  87
  88 typedef Odr_oct Z_ReferenceId;
  89 typedef char Z_DatabaseName;
  90 typedef char Z_ResultSetId;
  91 typedef Odr_oct Z_ResultsetId;
  92 typedef Odr_external Z_UserInformationField;
  93
  94 /* ----------------- INIT SERVICE  ----------------*/
  95
  96 typedef struct
  97 {
  98     char *groupId;       /* OPTIONAL */
  99     char *userId;         /* OPTIONAL */
 100     char *password;      /* OPTIONAL */
 101 } Z_IdPass;
 102
 103 typedef struct Z_IdAuthentication
 104 {
 105     enum
 106     {
 107         Z_IdAuthentication_open,
 108         Z_IdAuthentication_idPass,
 109         Z_IdAuthentication_anonymous,
 110         Z_IdAuthentication_other
 111     } which;
 112     union
 113     {
 114         char *open;
 115         Z_IdPass *idPass;
 116         void *anonymous;         /* NULL */
 117         Odr_external *other;
 118     } u;
 119 } Z_IdAuthentication;
 120
 121 #define Z_ProtocolVersion_1            0
 122 #define Z_ProtocolVersion_2            1
 123 #define Z_ProtocolVersion_3            2
 124
 125 #define Z_Options_search               0
 126 #define Z_Options_present              1
 127 #define Z_Options_delSet               2
 128 #define Z_Options_resourceReport       3
 129 #define Z_Options_triggerResourceCtrl  4
 130 #define Z_Options_resourceCtrl         5
 131 #define Z_Options_accessCtrl           6
 132 #define Z_Options_scan                 7
 133 #define Z_Options_sort                 8
 134 #define Z_Options_reserved             9
 135 #define Z_Options_extendedServices    10
 136 #define Z_Options_level_1Segmentation 11
 137 #define Z_Options_level_2Segmentation 12
 138 #define Z_Options_concurrentOperations 13
 139 #define Z_Options_namedResultSets     14
 140
 141 typedef struct Z_InitRequest
 142 {
 143     Z_ReferenceId *referenceId;                   /* OPTIONAL */
 144     Odr_bitmask *options;
 145     Odr_bitmask *protocolVersion;
 146     int *preferredMessageSize;
 147     int *maximumRecordSize;
 148     Z_IdAuthentication* idAuthentication;        /* OPTIONAL */
 149     char *implementationId;                      /* OPTIONAL */
 150     char *implementationName;                    /* OPTIONAL */
 151     char *implementationVersion;                 /* OPTIONAL */
 152     Z_UserInformationField *userInformationField; /* OPTIONAL */
 153 } Z_InitRequest;
 154
 155 typedef struct Z_InitResponse
 156 {
 157     Z_ReferenceId *referenceId;    /* OPTIONAL */
 158     Odr_bitmask *options;
 159     Odr_bitmask *protocolVersion;
 160     int *preferredMessageSize;
 161     int *maximumRecordSize;
 162     bool_t *result;
 163     char *implementationId;      /* OPTIONAL */
 164     char *implementationName;    /* OPTIONAL */
 165     char *implementationVersion; /* OPTIONAL */
 166     Z_UserInformationField *userInformationField; /* OPTIONAL */
 167 } Z_InitResponse;
 168
 169 typedef struct Z_NSRAuthentication
 170 {
 171     char *user;
 172     char *password;
 173     char *account;
 174 } Z_NSRAuthentication;
 175
 176 int z_NSRAuthentication(ODR o, Z_NSRAuthentication **p, int opt);
 177
 178 int z_StrAuthentication(ODR o, char **p, int opt);
 179
 180
 181 /* ------------------ RESOURCE CONTROL ----------------*/
 182
 183 typedef struct Z_TriggerResourceControlRequest
 184 {
 185     Z_ReferenceId *referenceId;    /* OPTIONAL */
 186     int *requestedAction;
 187 #define Z_TriggerResourceCtrl_resourceReport  1
 188 #define Z_TriggerResourceCtrl_resourceControl 2
 189 #define Z_TriggerResourceCtrl_cancel          3
 190     Odr_oid *prefResourceReportFormat;  /* OPTIONAL */
 191     bool_t *resultSetWanted;            /* OPTIONAL */
 192 } Z_TriggerResourceControlRequest;
 193
 194 typedef struct Z_ResourceControlRequest
 195 {
 196     Z_ReferenceId *referenceId;    /* OPTIONAL */
 197     bool_t *suspendedFlag;         /* OPTIONAL */
 198     Odr_external *resourceReport; /* OPTIONAL */
 199     int *partialResultsAvailable;  /* OPTIONAL */
 200 #define Z_ResourceControlRequest_subset    1
 201 #define Z_ResourceControlRequest_interim   2
 202 #define Z_ResourceControlRequest_none      3
 203     bool_t *responseRequired;
 204     bool_t *triggeredRequestFlag;  /* OPTIONAL */
 205 } Z_ResourceControlRequest;
 206
 207 typedef struct Z_ResourceControlResponse
 208 {
 209     Z_ReferenceId *referenceId;    /* OPTIONAL */
 210     bool_t *continueFlag;
 211     bool_t *resultSetWanted;       /* OPTIONAL */
 212 } Z_ResourceControlResponse;
 213
 214 /* ------------------ SEARCH SERVICE ----------------*/
 215
 216 typedef Odr_oid Z_PreferredRecordSyntax;
 217
 218 typedef struct Z_DatabaseSpecificUnit
 219 {
 220     char *databaseName;
 221     char *elementSetName;
 222 } Z_DatabaseSpecificUnit;
 223
 224 typedef struct Z_DatabaseSpecific
 225 {
 226     int num_elements;
 227     Z_DatabaseSpecificUnit **elements;
 228 } Z_DatabaseSpecific;
 229
 230 typedef struct Z_ElementSetNames
 231 {
 232     int which;
 233 #define Z_ElementSetNames_generic 0
 234 #define Z_ElementSetNames_databaseSpecific 1
 235     union
 236     {
 237         char *generic;
 238         Z_DatabaseSpecific *databaseSpecific;
 239     } u;
 240 } Z_ElementSetNames;
 241
 242 /* ---------------------- RPN QUERY --------------------------- */
 243
 244 typedef struct Z_AttributeElement
 245 {
 246     int *attributeType;
 247     int *attributeValue;
 248 } Z_AttributeElement;
 249
 250 #define Z_V3
 251 #ifdef Z_V3
 252
 253 typedef struct Z_Term
 254 {
 255     enum
 256     {
 257         Z_Term_general,
 258         Z_Term_numeric,
 259         Z_Term_characterString,
 260         Z_Term_oid,
 261         Z_Term_dateTime,
 262         Z_Term_external,
 263         Z_Term_integerAndUnit,
 264         Z_Term_null
 265     } which;
 266     union
 267     {
 268         Odr_oct *general; /* this is required for v2 */
 269         int *numeric;
 270         char *characterString;
 271         Odr_oid *oid;
 272         char *dateTime;
 273         Odr_external *external;
 274         /* Z_IntUnit *integerAndUnit; */
 275         void *null;
 276     } u;
 277 } Z_Term;
 278
 279 #endif
 280
 281 typedef struct Z_AttributesPlusTerm
 282 {
 283     int num_attributes;
 284     Z_AttributeElement **attributeList;
 285 #ifdef Z_V3
 286     Z_Term *term;
 287 #else
 288     Odr_oct *term;
 289 #endif
 290 } Z_AttributesPlusTerm;
 291
 292 typedef struct Z_ProximityOperator
 293 {
 294     bool_t *exclusion;          /* OPTIONAL */
 295     int *distance;
 296     bool_t *ordered;
 297     int *relationType;
 298     enum
 299     {
 300         Z_ProximityOperator_known,
 301         Z_ProximityOperator_private
 302     } which;
 303     union
 304     {
 305         int *known;
 306         int *private;
 307     } u;
 308 } Z_ProximityOperator;
 309
 310 typedef struct Z_Operator
 311 {
 312     enum
 313     {
 314         Z_Operator_and,
 315         Z_Operator_or,
 316         Z_Operator_and_not,
 317         Z_Operator_proximity
 318     } which;
 319     union
 320     {
 321         void *and;          /* these guys are nulls. */
 322         void *or;
 323         void *and_not;
 324         Z_ProximityOperator *proximity;
 325     } u;
 326 } Z_Operator;
 327
 328 typedef struct Z_Operand
 329 {
 330     int which;
 331 #define Z_Operand_APT 0
 332 #define Z_Operand_resultSetId 1
 333     union
 334     {
 335         Z_AttributesPlusTerm *attributesPlusTerm;
 336         Z_ResultSetId *resultSetId;
 337     } u;
 338 } Z_Operand;
 339
 340 typedef struct Z_Complex
 341 {
 342     struct Z_RPNStructure *s1;
 343     struct Z_RPNStructure *s2;
 344     Z_Operator *operator;
 345 } Z_Complex;
 346
 347 typedef struct Z_RPNStructure
 348 {
 349     int which;
 350 #define Z_RPNStructure_simple 0
 351 #define Z_RPNStructure_complex 1
 352     union
 353     {
 354         Z_Operand *simple;
 355         Z_Complex *complex;
 356     } u;
 357 } Z_RPNStructure;
 358
 359 typedef struct Z_RPNQuery
 360 {
 361     Odr_oid *attributeSetId;
 362     Z_RPNStructure *RPNStructure;
 363 } Z_RPNQuery;
 364
 365 /* -------------------------- SEARCHREQUEST -------------------------- */
 366
 367 typedef struct Z_Query
 368 {
 369     int which;
 370 #define Z_Query_type_1 1
 371 #define Z_Query_type_2 2
 372     union
 373     {
 374         Z_RPNQuery *type_1;
 375         Odr_oct *type_2;
 376     } u;
 377 } Z_Query;
 378
 379 typedef struct Z_SearchRequest
 380 {
 381     Z_ReferenceId *referenceId;   /* OPTIONAL */
 382     int *smallSetUpperBound;
 383     int *largeSetLowerBound;
 384     int *mediumSetPresentNumber;
 385     bool_t *replaceIndicator;
 386     char *resultSetName;
 387     int num_databaseNames;
 388     char **databaseNames;
 389     Z_ElementSetNames *smallSetElementSetNames;    /* OPTIONAL */
 390     Z_ElementSetNames *mediumSetElementSetNames;    /* OPTIONAL */
 391     Z_PreferredRecordSyntax *preferredRecordSyntax;  /* OPTIONAL */
 392     Z_Query *query;
 393 } Z_SearchRequest;
 394
 395 /* ------------------------ RECORD -------------------------- */
 396
 397 typedef Odr_external Z_DatabaseRecord;
 398
 399 typedef struct Z_DiagRec
 400 {
 401     Odr_oid *diagnosticSetId;
 402     int *condition;
 403     char *addinfo;
 404 } Z_DiagRec;
 405
 406 typedef struct Z_NamePlusRecord
 407 {
 408     char *databaseName;      /* OPTIONAL */
 409     int which;
 410 #define Z_NamePlusRecord_databaseRecord 0
 411 #define Z_NamePlusRecord_surrogateDiagnostic 1
 412     union
 413     {
 414         Z_DatabaseRecord *databaseRecord;
 415         Z_DiagRec *surrogateDiagnostic;
 416     } u;
 417 } Z_NamePlusRecord;
 418
 419 typedef struct Z_NamePlusRecordList
 420 {
 421     int num_records;
 422     Z_NamePlusRecord **records;
 423 } Z_NamePlusRecordList;
 424
 425 typedef struct Z_Records
 426 {
 427     int which;
 428 #define Z_Records_DBOSD 0
 429 #define Z_Records_NSD 1
 430     union
 431     {
 432         Z_NamePlusRecordList *databaseOrSurDiagnostics;
 433         Z_DiagRec *nonSurrogateDiagnostic;
 434     } u;
 435 } Z_Records;
 436
 437 /* ------------------------ SCAN SERVICE -------------------- */
 438
 439 typedef struct Z_AttributeList
 440 {
 441     int num_attributes;
 442     Z_AttributeElement **attributes;
 443 } Z_AttributeList;
 444
 445 typedef struct Z_AlternativeTerm
 446 {
 447     int num_terms;
 448     Z_AttributesPlusTerm **terms;
 449 } Z_AlternativeTerm;
 450
 451 typedef struct Z_OccurrenceByAttributes
 452 {
 453     Z_AttributeList *attributes;
 454 #if 0
 455     enum
 456     {
 457         Z_OByAtt_global,
 458         Z_ObyAtt_byDatabase
 459     } which;
 460     union
 461     {
 462 #endif
 463         int *global;
 464 #if 0
 465         /* Z_ByDatabase *byDatabase; */
 466     } u;
 467 #endif
 468 } Z_OccurrenceByAttributes;
 469
 470 typedef struct Z_TermInfo
 471 {
 472     Z_Term *term;
 473     Z_AttributeList *suggestedAttributes;  /* OPTIONAL */
 474     Z_AlternativeTerm *alternativeTerm;    /* OPTIONAL */
 475     int *globalOccurrences;                /* OPTIONAL */
 476     Z_OccurrenceByAttributes *byAttributes; /* OPTIONAL */
 477 } Z_TermInfo;
 478
 479 typedef struct Z_Entry
 480 {
 481     enum
 482     {
 483         Z_Entry_termInfo,
 484         Z_Entry_surrogateDiagnostic
 485     } which;
 486     union
 487     {
 488         Z_TermInfo *termInfo;
 489         Z_DiagRec *surrogateDiagnostic;
 490     } u;
 491 } Z_Entry;
 492
 493 typedef struct Z_Entries
 494 {
 495     int num_entries;
 496     Z_Entry **entries;
 497 } Z_Entries;
 498
 499 typedef struct Z_DiagRecs
 500 {
 501     int num_diagRecs;
 502     Z_DiagRec **diagRecs;
 503 } Z_DiagRecs;
 504
 505 typedef struct Z_ListEntries
 506 {
 507     enum
 508     {
 509         Z_ListEntries_entries,
 510         Z_ListEntries_nonSurrogateDiagnostics
 511     } which;
 512     union
 513     {
 514         Z_Entries *entries;
 515         Z_DiagRecs *nonSurrogateDiagnostics;
 516     } u;
 517 } Z_ListEntries;
 518
 519 typedef struct Z_ScanRequest
 520 {
 521     Z_ReferenceId *referenceId;       /* OPTIONAL */
 522     int num_databaseNames;
 523     char **databaseNames;
 524     Odr_oid *attributeSet;          /* OPTIONAL */
 525     Odr_any *eatme1;
 526     Z_AttributesPlusTerm *termListAndStartPoint;
 527     int *stepSize;                    /* OPTIONAL */
 528     int *numberOfTermsRequested;
 529     int *preferredPositionInResponse;   /* OPTIONAL */
 530 } Z_ScanRequest;
 531
 532 typedef struct Z_ScanResponse
 533 {
 534     Z_ReferenceId *referenceId;       /* OPTIONAL */
 535     int *stepSize;                    /* OPTIONAL */
 536     int *scanStatus;
 537 #define Z_Scan_success      0
 538 #define Z_Scan_partial_1    1
 539 #define Z_Scan_partial_2    2
 540 #define Z_Scan_partial_3    3
 541 #define Z_Scan_partial_4    4
 542 #define Z_Scan_partial_5    5
 543 #define Z_Scan_failure      6
 544     int *numberOfEntriesReturned;
 545     int *positionOfTerm;              /* OPTIONAL */
 546     Z_ListEntries *entries;           /* OPTIONAL */
 547     Odr_oid *attributeSet;            /* OPTIONAL */
 548 } Z_ScanResponse;
 549
 550 /* ------------------------ SEARCHRESPONSE ------------------ */
 551
 552 typedef struct Z_SearchResponse
 553 {
 554     Z_ReferenceId *referenceId;       /* OPTIONAL */
 555     int *resultCount;
 556     int *numberOfRecordsReturned;
 557     int *nextResultSetPosition;
 558     bool_t *searchStatus;
 559     int *resultSetStatus;              /* OPTIONAL */
 560 #define Z_RES_SUBSET        1
 561 #define Z_RES_INTERIM       2
 562 #define Z_RES_NONE          3
 563     int *presentStatus;                /* OPTIONAL */
 564 #define Z_PRES_SUCCESS      0
 565 #define Z_PRES_PARTIAL_1    1
 566 #define Z_PRES_PARTIAL_2    2
 567 #define Z_PRES_PARTIAL_3    3
 568 #define Z_PRES_PARTIAL_4    4
 569 #define Z_PRES_FAILURE      5
 570     Z_Records *records;                  /* OPTIONAL */
 571 } Z_SearchResponse;
 572
 573 /* ------------------------- PRESENT SERVICE -----------------*/
 574
 575 typedef struct Z_PresentRequest
 576 {
 577     Z_ReferenceId *referenceId;          /* OPTIONAL */
 578     Z_ResultSetId *resultSetId;
 579     int *resultSetStartPoint;
 580     int *numberOfRecordsRequested;
 581     Z_ElementSetNames *elementSetNames;  /* OPTIONAL */
 582     Z_PreferredRecordSyntax *preferredRecordSyntax;  /* OPTIONAL */
 583 } Z_PresentRequest;
 584
 585 typedef struct Z_PresentResponse
 586 {
 587     Z_ReferenceId *referenceId;        /* OPTIONAL */
 588     int *numberOfRecordsReturned;
 589     int *nextResultSetPosition;
 590     int *presentStatus;
 591     Z_Records *records;
 592 } Z_PresentResponse;
 593
 594 /* ------------------------ DELETE -------------------------- */
 595
 596 typedef struct Z_ListStatus
 597 {
 598     Z_ResultSetId *id;
 599     int *status;
 600 } Z_ListStatus;
 601
 602 typedef struct Z_DeleteResultSetRequest
 603 {
 604     Z_ReferenceId *referenceId;        /* OPTIONAL */
 605     int *deleteFunction;
 606 #define Z_DeleteRequest_list    0
 607 #define Z_DeleteRequest_all     1
 608     int num_ids;
 609     Z_ResultSetId *resultSetList;      /* OPTIONAL */
 610 } Z_DeleteResultSetRequest;
 611
 612 typedef enum Z_DeleteSetStatus
 613 {
 614     Z_Delete_success = 0,
 615     Z_Delete_resultSetDidNotExist,
 616     Z_Delete_previouslyDeletedByTarget,
 617     Z_Delete_systemProblemAtTarget,
 618     Z_Delete_accessNotAllowed,
 619     Z_Delete_resourceControlAtOrigin,
 620     Z_Delete_resourceControlAtTarget,
 621     Z_Delete_bulkDeleteNotSupported,
 622     Z_Delete_notAllRsltSetsDeletedOnBulkDlte,
 623     Z_Delete_notAllRequestedResultSetsDeleted,
 624     Z_Delete_resultSetInUse
 625 } Z_DeleteSetStatus;
 626
 627 typedef struct Z_DeleteResultSetResponse
 628 {
 629     Z_ReferenceId *referenceId;        /* OPTIONAL */
 630     int *deleteOperationStatus;
 631     int num_statuses;
 632     Z_ListStatus *deleteListStatuses;  /* OPTIONAL */
 633     int *numberNotDeleted;             /* OPTIONAL */
 634     int num_bulkstatuses;
 635     Z_ListStatus *bulkStatuses;        /* OPTIONAL */
 636     char *deleteMessage;               /* OPTIONAL */
 637 } Z_DeleteResultSetResponse;
 638
 639 /* ------------------------ APDU ---------------------------- */
 640
 641 typedef struct Z_APDU
 642 {
 643     enum
 644     {
 645         Z_APDU_initRequest,
 646         Z_APDU_initResponse,
 647         Z_APDU_searchRequest,
 648         Z_APDU_searchResponse,
 649         Z_APDU_presentRequest,
 650         Z_APDU_presentResponse,
 651         Z_APDU_resourceControlRequest,
 652         Z_APDU_resourceControlResponse,
 653         Z_APDU_triggerResourceControlRequest,
 654         Z_APDU_scanRequest,
 655         Z_APDU_scanResponse
 656     } which;
 657     union
 658     {
 659         Z_InitRequest  *initRequest;
 660         Z_InitResponse *initResponse;
 661         Z_SearchRequest *searchRequest;
 662         Z_SearchResponse *searchResponse;
 663         Z_PresentRequest *presentRequest;
 664         Z_PresentResponse *presentResponse;
 665         Z_ResourceControlRequest *resourceControlRequest;
 666         Z_ResourceControlResponse *resourceControlResponse;
 667         Z_TriggerResourceControlRequest *triggerResourceControlRequest;
 668         Z_ScanRequest *scanRequest;
 669         Z_ScanResponse *scanResponse;
 670     } u;
 671 } Z_APDU;
 672
 673 int z_APDU(ODR o, Z_APDU **p, int opt);
 674
 675 #endif