X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fasn.xml;h=78ee8148a1c0ce6a43c4301eb7078ed064602757;hp=e1262676768825ab26e0079b2986d76bb4d97ab7;hb=053367cbe356fb3ce0def34b065dae589d700daf;hpb=ce853cc4919ab346fd629e7727905d3ee6e1129f diff --git a/doc/asn.xml b/doc/asn.xml index e126267..78ee814 100644 --- a/doc/asn.xml +++ b/doc/asn.xml @@ -1,18 +1,25 @@ - - The ASN Module - Introduction + The Z39.50 ASN.1 Module + Introduction The &asn; module provides you with a set of C struct definitions for the - various PDUs of the protocol, as well as for the complex types + various PDUs of the Z39.50 protocol, as well as for the complex types appearing within the PDUs. For the primitive data types, the C representation often takes the form of an ordinary C language type, - such as int. For ASN.1 constructs that have no direct + such as Odr_int which is equivalent to an integral + C integer. For ASN.1 constructs that have no direct representation in C, such as general octet strings and bit strings, the &odr; module (see section The ODR Module) provides auxiliary definitions. + + The &asn; module is located in sub directory z39.50. + There you'll find C files that implements encoders and decoders for the + Z39.50 types. You'll also find the protocol definitions: + z3950v3.asn, esupdate.asn, + and others. + - Preparing PDUs + Preparing PDUs A structure representing a complex ASN.1 type doesn't in itself contain the @@ -47,8 +54,8 @@ structure before freeing the structure itself. - You can use the odr_malloc() function (see section - Using ODR for details). When you use + You can use the odr_malloc() function (see + for details). When you use odr_malloc(), you can release all of the allocated data in a single operation, independent of any pointers and relations between the data. odr_malloc() is based on a @@ -89,7 +96,7 @@ individual types). - The prototype for the individual PDU types generally look like this: + The prototype for the individual PDU types generally look like this: Z_<type> *zget_<type>(ODR o); @@ -104,12 +111,13 @@ - The &odr; handle should generally be your encoding stream, but it needn't be. + The &odr; handle should generally be your encoding stream, but it + needn't be. - As well as the individual PDU functions, a function - zget_APDU() is - provided, which allocates a toplevel Z-APDU of the type requested: + As well as the individual PDU functions, a function + zget_APDU() is provided, which allocates + a top-level Z-APDU of the type requested: @@ -124,76 +132,14 @@ - Object Identifiers - - When you refer to object identifiers in your application, you need to - be aware that SR and Z39.50 use two different set of OIDs to refer to - the same objects. To handle this easily, &yaz; provides a utility module - to &asn; which provides an internal representation of the OIDs used in - both protocols. Each oid is described by a structure: - - - -typedef struct oident -{ - enum oid_proto proto; - enum oid_class class; - enum oid_value value; - int oidsuffix[OID_SIZE]; - char *desc; -} oident; - - - - The proto field can be set to either - PROTO_SR or PROTO_Z3950. - The class might be, say, - CLASS_RECSYN, and the value might be - VAL_USMARC for the USMARC record format. Functions - - - -int *oid_ent_to_oid(struct oident *ent, int *dst); -struct oident *oid_getentbyoid(int *o); - - - - are provided to map between object identifiers and database entries. - If you store a member of the oid_proto type in - your association state information, it's a simple matter, at runtime, - to generate the correct OID when you need it. For decoding, you can - simply ignore the proto field, or if you're strict, you can verify - that your peer is using the OID family from the correct protocol. - The desc field is a short, human-readable name - for the PDU, useful mainly for diagnostic output. - - - - - The old function oid_getoidbyent still exists but is - not thread safe. Use oid_ent_to_oid instead - and pass an array of size OID_SIZE. - - - - - - Plans are underway to merge the two protocols into a single - definition, with one set of object identifiers. When this happens, the - oid module will no longer be required to support protocol - independence, but it should still be useful as a simple OID database. - - - - - EXTERNAL Data + EXTERNAL Data In order to achieve extensibility and adaptability to different application domains, the new version of the protocol defines many structures outside of the main ASN.1 specification, referencing them - through ASN.1 EXTERNAL constructs. To simplify the construction and access - to the externally referenced data, the &asn; module defines a + through ASN.1 EXTERNAL constructs. To simplify the construction and + access to the externally referenced data, the &asn; module defines a specialized version of the EXTERNAL construct, called Z_External.It is defined thus: @@ -263,7 +209,7 @@ typedef struct Z_External - Z_ext_typeent *z_ext_gettypebyref(oid_value ref); + Z_ext_typeent *z_ext_gettypebyref(const oid *oid); @@ -277,7 +223,7 @@ typedef struct Z_External typedef struct Z_ext_typeent { - oid_value dref; /* the direct-reference OID value. */ + int oid[OID_SIZE]; /* the direct-reference OID. */ int what; /* discriminator value for the external CHOICE */ Odr_fun fun; /* decoder function */ } Z_ext_typeent; @@ -300,8 +246,8 @@ typedef struct Z_ext_typeent z_ext_gettypebyref to look for the provided direct-reference. If the return value is different from NULL, you can use the provided - function to decode the BER string (see section - Using ODR). + function to decode the BER string (see + ). @@ -314,9 +260,10 @@ typedef struct Z_ext_typeent If you need to add new, externally defined data types, you must update the struct above, in the source file prt-ext.h, as well as the encoder/decoder in the file prt-ext.c. - When changing the latter, remember to update both the arm - arrary and the list type_table, which drives the CHOICE - biasing that is necessary to tell the different, structured types apart + When changing the latter, remember to update both the + arm arrary and the list + type_table, which drives the CHOICE biasing that + is necessary to tell the different, structured types apart on decoding. @@ -331,19 +278,72 @@ typedef struct Z_ext_typeent - PDU Contents Table + PDU Contents Table - + We include, for reference, a listing of the fields of each top-level PDU, as well as their default settings. - Default settings for PDU Initialize Request +
+ Default settings for PDU Initialize Request - - - - + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + protocolVersionOdr_bitmaskEmpty bitmask + + + optionsOdr_bitmaskEmpty bitmask + + + preferredMessageSizeOdr_int30*1024 + + + maximumRecordSizeOdr_int30*1024 + + + idAuthenticationZ_IdAuthenticationNULL + + + implementationIdchar*"81" + + + implementationNamechar*"YAZ" + + + implementationVersionchar*YAZ_VERSION + + + userInformationFieldZ_UserInformationNULL + + + otherInfoZ_OtherInformationNULL + + + +
+ + + Default settings for PDU Initialize + Response + + + + + Field Type @@ -351,60 +351,49 @@ typedef struct Z_ext_typeent - referenceIdZ_ReferenceIdNULL - protocolVersionOdr_bitmaskEmpty bitmask - optionsOdr_bitmaskEmpty bitmask - - preferredMessageSizeint30*1024 + preferredMessageSizeOdr_int30*1024 - - maximumRecordSizeint30*1024 + maximumRecordSizeOdr_int30*1024 - - idAuthenticationZ_IdAuthenticationNULL + resultOdr_boolTRUE - - implementationIdchar*"YAZ (id=81)" + implementationIdchar*"id)" - - implementationNamechar*"Index Data/YAZ" + implementationNamechar*"YAZ" - implementationVersionchar*YAZ_VERSION - userInformationFieldZ_UserInformationNULL - otherInfoZ_OtherInformationNULL -
- Default settings for PDU Initialize Response +
+ Default settings for PDU Search Request - - - + + + Field @@ -413,60 +402,61 @@ typedef struct Z_ext_typeent - referenceIdZ_ReferenceIdNULL - - protocolVersionOdr_bitmaskEmpty bitmask + smallSetUpperBoundOdr_int0 - - optionsOdr_bitmaskEmpty bitmask + largeSetLowerBoundOdr_int1 - - preferredMessageSizeint30*1024 + mediumSetPresentNumberOdr_int0 - - maximumRecordSizeint30*1024 + replaceIndicatorOdr_boolTRUE - - resultbool_tTRUE + resultSetNamechar *"default" - - implementationIdchar*"YAZ (id=81)" + num_databaseNamesOdr_int0 - - implementationNamechar*"Index Data/YAZ" + databaseNameschar **NULL - - implementationVersionchar*YAZ_VERSION + smallSetElementSetNamesZ_ElementSetNames + NULL - - userInformationFieldZ_UserInformationNULL + mediumSetElementSetNamesZ_ElementSetNames + NULL + + + preferredRecordSyntaxOdr_oidNULL + + + queryZ_QueryNULL + + + additionalSearchInfoZ_OtherInformation + NULL - otherInfoZ_OtherInformationNULL -
- Default settings for PDU Search Request +
+ Default settings for PDU Search Response - - - + + + Field @@ -479,256 +469,540 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - - smallSetUpperBoundint0 + resultCountOdr_int0 - - largeSetLowerBoundint1 + numberOfRecordsReturnedOdr_int0 - - mediumSetPresentNumberint0 + nextResultSetPositionOdr_int0 - - replaceIndicatorbool_tTRUE + searchStatusOdr_boolTRUE - - resultSetNamechar *"default" + resultSetStatusOdr_intNULL - - num_databaseNamesint0 + presentStatusOdr_intNULL - - databaseNameschar **NULL + recordsZ_RecordsNULL - - smallSetElementSetNamesZ_ElementSetNamesNULL + additionalSearchInfo + Z_OtherInformationNULL - - mediumSetElementSetNamesZ_ElementSetNamesNULL + otherInfoZ_OtherInformationNULL + + +
+ + Default settings for PDU Present Request + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + resultSetIdchar*"default" + + + resultSetStartPointOdr_int1 + + + numberOfRecordsRequestedOdr_int10 + + + num_rangesOdr_int0 + + + additionalRangesZ_RangeNULL + + + recordCompositionZ_RecordCompositionNULL + preferredRecordSyntaxOdr_oidNULL + + maxSegmentCountOdr_intNULL + + + maxRecordSizeOdr_intNULL + + + maxSegmentSizeOdr_intNULL + + + otherInfoZ_OtherInformationNULL + + + +
+ + Default settings for PDU Present Response + + + + + + + Field + Type + Default Value + + + - queryZ_QueryNULL + referenceIdZ_ReferenceIdNULL + + + numberOfRecordsReturnedOdr_int0 + + + nextResultSetPositionOdr_int0 + + + presentStatusOdr_intZ_PresentStatus_success + + + recordsZ_RecordsNULL + + + otherInfoZ_OtherInformationNULL + + +
+ + Default settings for Delete Result Set Request + + + + + + + + Field + Type + Default Value + + + + referenceId + Z_ReferenceIdNULL + + + deleteFunctionOdr_intZ_DeleteResultSetRequest_list + + + num_idsOdr_int0 + + + resultSetListchar**NULL + - additionalSearchInfoZ_OtherInformationNULL + otherInfoZ_OtherInformationNULL + + +
+ + Default settings for Delete Result Set Response + + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + deleteOperationStatusOdr_int + Z_DeleteStatus_success + + num_statusesOdr_int0 + + + deleteListStatusesZ_ListStatus**NULL + + + numberNotDeletedOdr_intNULL + + + num_bulkStatusesOdr_int0 + + + bulkStatusesZ_ListStatusNUL + L + + deleteMessagechar*NULL + otherInfoZ_OtherInformationNULL + + +
+ + Default settings for Scan Request + + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + num_databaseNamesOdr_int0 + + + databaseNameschar**NULL + + + attributeSetOdr_oidNULL + + + termListAndStartPointZ_AttributesPlus... + NULL + + stepSizeOdr_intNULL + + + numberOfTermsRequestedOdr_int20 + + + preferredPositionInResponseOdr_intNULL + + + otherInfoZ_OtherInformationNULL +
- - Z_SearchResponse - ---------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - resultCount int 0 - numberOfRecordsReturned int 0 - nextResultSetPosition int 0 - searchStatus bool_t TRUE - resultSetStatus int NULL - presentStatus int NULL - records Z_Records NULL - additionalSearchInfo Z_OtherInformation NULL - otherInfo Z_OtherInformation NULL - + + Default settings for Scan Response + + + + + + + + Field + Type + Default Value + + + - - Z_PresentRequest - ---------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - resultSetId char* "default" - resultSetStartPoint int 1 - numberOfRecordsRequested int 10 - num_ranges int 0 - additionalRanges Z_Range NULL - recordComposition Z_RecordComposition NULL - preferredRecordSyntax Odr_oid NULL - maxSegmentCount int NULL - maxRecordSize int NULL - maxSegmentSize int NULL - otherInfo Z_OtherInformation NULL - + + referenceIdZ_ReferenceIdNULL + + + stepSizeOdr_intNULL + + + scanStatusOdr_intZ_Scan_success + + + numberOfEntriesReturnedOdr_int0 + + + positionOfTermOdr_intNULL + + + entriesZ_ListEntrisNULL + + + attributeSetOdr_oidNULL + + + otherInfoZ_OtherInformationNULL + + + +
- - Z_PresentResponse - ----------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - numberOfRecordsReturned int 0 - nextResultSetPosition int 0 - presentStatus int Z_PRES_SUCCESS - records Z_Records NULL - otherInfo Z_OtherInformation NULL - + + Default settings for Trigger Resource Control Request + + + + + + + Field + Type + Default Value + + + - - Z_DeleteResultSetRequest - ------------------------ - Field Type Default value - - referenceId Z_ReferenceId NULL - deleteFunction int Z_DeleteRequest_list - num_ids int 0 - resultSetList char** NULL - otherInfo Z_OtherInformation NULL - + + referenceIdZ_ReferenceIdNULL + + + requestedActionOdr_int + Z_TriggerResourceCtrl_resou.. + + + prefResourceReportFormatOdr_oidNULL + + + resultSetWantedOdr_boolNULL + + + otherInfoZ_OtherInformationNULL + - - Z_DeleteResultSetResponse - ------------------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - deleteOperationStatus int Z_DeleteStatus_success - num_statuses int 0 - deleteListStatuses Z_ListStatus** NULL - numberNotDeleted int NULL - num_bulkStatuses int 0 - bulkStatuses Z_ListStatus NULL - deleteMessage char* NULL - otherInfo Z_OtherInformation NULL - + + +
- - Z_ScanRequest - ------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - num_databaseNames int 0 - databaseNames char** NULL - attributeSet Odr_oid NULL - termListAndStartPoint Z_AttributesPlus... NULL - stepSize int NULL - numberOfTermsRequested int 20 - preferredPositionInResponse int NULL - otherInfo Z_OtherInformation NULL - + + Default settings for Resource Control Request + + + + + + + Field + Type + Default Value + + + - - Z_ScanResponse - -------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - stepSize int NULL - scanStatus int Z_Scan_success - numberOfEntriesReturned int 0 - positionOfTerm int NULL - entries Z_ListEntris NULL - attributeSet Odr_oid NULL - otherInfo Z_OtherInformation NULL - + + referenceIdZ_ReferenceIdNULL + + + suspendedFlagOdr_boolNULL + + + resourceReportZ_ExternalNULL + + + partialResultsAvailableOdr_intNULL + + + responseRequiredOdr_boolFALSE + + + triggeredRequestFlagOdr_boolNULL + + + otherInfoZ_OtherInformationNULL + + + +
- - Z_TriggerResourceControlRequest - ------------------------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - requestedAction int Z_TriggerResourceCtrl_resou.. - prefResourceReportFormat Odr_oid NULL - resultSetWanted bool_t NULL - otherInfo Z_OtherInformation NULL - + + Default settings for Resource Control Response + + + + + + + Field + Type + Default Value + + + - - Z_ResourceControlRequest - ------------------------ - Field Type Default value - - referenceId Z_ReferenceId NULL - suspendedFlag bool_t NULL - resourceReport Z_External NULL - partialResultsAvailable int NULL - responseRequired bool_t FALSE - triggeredRequestFlag bool_t NULL - otherInfo Z_OtherInformation NULL - + + referenceIdZ_ReferenceIdNULL + + + continueFlagbool_tTRUE + + + resultSetWantedbool_tNULL + + + otherInfoZ_OtherInformationNULL + + + +
- - Z_ResourceControlResponse - ------------------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - continueFlag bool_t TRUE - resultSetWanted bool_t NULL - otherInfo Z_OtherInformation NULL - + + Default settings for Access Control Request + + + + + + + Field + Type + Default Value + + + - - Z_AccessControlRequest - ---------------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - which enum Z_AccessRequest_simpleForm; - u union NULL - otherInfo Z_OtherInformation NULL - + + referenceIdZ_ReferenceIdNULL + + + whichenumZ_AccessRequest_simpleForm; + + + uunionNULL + + + otherInfoZ_OtherInformationNULL + + + +
- - Z_AccessControlResponse - ----------------------- - Field Type Default value - - referenceId Z_ReferenceId NULL - which enum Z_AccessResponse_simpleForm - u union NULL - diagnostic Z_DiagRec NULL - otherInfo Z_OtherInformation NULL - + + Default settings for Access Control Response + + + + + + + Field + Type + Default Value + + + - - Z_Segment - --------- - Field Type Default value - - referenceId Z_ReferenceId NULL - numberOfRecordsReturned int value=0 - num_segmentRecords int 0 - segmentRecords Z_NamePlusRecord NULL - otherInfo Z_OtherInformation NULL - + + referenceIdZ_ReferenceIdNULL + + + whichenumZ_AccessResponse_simpleForm + + + uunionNULL + + + diagnosticZ_DiagRecNULL + + + otherInfoZ_OtherInformationNULL + + + +
- - Z_Close - ------- - Field Type Default value + + Default settings for Segment + + + + + + + Field + Type + Default Value + + + - referenceId Z_ReferenceId NULL - closeReason int Z_Close_finished - diagnosticInformation char* NULL - resourceReportFormat Odr_oid NULL - resourceFormat Z_External NULL - otherInfo Z_OtherInformation NULL + + referenceIdZ_ReferenceIdNULL + + + numberOfRecordsReturnedOdr_intvalue=0 + + + num_segmentRecordsOdr_int0 + + + segmentRecordsZ_NamePlusRecordNULL + + otherInfoZ_OtherInformationNULL + + + +
- + + Default settings for Close + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + closeReasonOdr_intZ_Close_finished + + + diagnosticInformationchar*NULL + + + resourceReportFormatOdr_oidNULL + + + resourceFormatZ_ExternalNULL + + + otherInfoZ_OtherInformationNULL + + + + +
@@ -743,7 +1017,7 @@ typedef struct Z_ext_typeent sgml-indent-step:1 sgml-indent-data:t sgml-parent-document: "yaz.xml" - sgml-local-catalogs: "../../docbook/docbook.cat" + sgml-local-catalogs: nil sgml-namecase-general:t End: -->