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