X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fasn.xml;h=bb84b528260101bf189fbd722ac0062535e331dd;hb=3c03c66fdcf640bbf4c611a48bf8c74989d077f6;hp=e1262676768825ab26e0079b2986d76bb4d97ab7;hpb=ce853cc4919ab346fd629e7727905d3ee6e1129f;p=yaz-moved-to-github.git diff --git a/doc/asn.xml b/doc/asn.xml index e126267..bb84b52 100644 --- a/doc/asn.xml +++ b/doc/asn.xml @@ -1,9 +1,8 @@ - - 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 @@ -11,9 +10,16 @@ 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 members of that type. Instead, the structure contains @@ -31,7 +37,7 @@ taste, there are at least three different approaches that you may take when you allocate the structures. - + You can use static or automatic local variables in the function that prepares the PDU. This is a simple approach, and it provides the most @@ -47,8 +53,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 @@ -66,7 +72,7 @@ some of its elements, while you leave other elements pointing to global or per-session default variables. - + The &asn; module provides an important aid in creating new PDUs. For each of the PDU types (say, Z_InitRequest), a @@ -89,115 +95,54 @@ 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); - + eg.: - + Z_InitRequest *zget_InitRequest(ODR o); - 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: - + Z_APDU *zget_APDU(ODR o, int which); - + The which parameter is (of course) the discriminator belonging to the Z_APDU CHOICE type. All of the interface described here is provided by the &asn; module, and you access it through the proto.h header file. - - - - 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: - + typedef struct Z_External { @@ -238,7 +183,7 @@ typedef struct Z_External } u; } Z_External; - + When decoding, the &asn; module will attempt to determine which syntax describes the data by looking at the reference fields @@ -252,7 +197,7 @@ typedef struct Z_External For non-ASN.1 data such as MARC records, use the octet_aligned arm of the union. - + Some servers return ASN.1 structured data values (eg. database records) as BER-encoded records placed in the @@ -261,9 +206,9 @@ typedef struct Z_External these records. To help you decode the records in the application, the function - + - Z_ext_typeent *z_ext_gettypebyref(oid_value ref); + Z_ext_typeent *z_ext_gettypebyref(const oid *oid); @@ -273,16 +218,16 @@ typedef struct Z_External Z_ext_typeent is defined as: - + 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; - + The what member contains the Z_External union discriminator value for the @@ -293,17 +238,17 @@ typedef struct Z_ext_typeent record syntax, the value of fun would be z_SUTRS (a function pointer). - + If you receive an EXTERNAL which contains an octet-string value that you suspect of being an ASN.1-structured data value, you can use 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 + ). - + If you want to send EXTERNALs containing ASN.1-structured values in the occtet-aligned branch of the CHOICE, this @@ -314,12 +259,13 @@ 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. - + Eventually, the EXTERNAL processing will most likely @@ -329,21 +275,74 @@ typedef struct Z_ext_typeent various modules. - + - 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 + + + preferredMessageSizeint30*1024 + + + maximumRecordSizeint30*1024 + + + idAuthenticationZ_IdAuthenticationNULL + + + implementationIdchar*"81" + + + implementationNamechar*"YAZ" + + + implementationVersionchar*YAZ_VERSION + + + userInformationFieldZ_UserInformationNULL + + + otherInfoZ_OtherInformationNULL + + + +
+ + + Default settings for PDU Initialize + Response + + + + + Field Type @@ -351,60 +350,49 @@ typedef struct Z_ext_typeent - referenceIdZ_ReferenceIdNULL - protocolVersionOdr_bitmaskEmpty bitmask - optionsOdr_bitmaskEmpty bitmask - preferredMessageSizeint30*1024 - maximumRecordSizeint30*1024 - - idAuthenticationZ_IdAuthenticationNULL + resultbool_tTRUE - - 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 +401,61 @@ typedef struct Z_ext_typeent - referenceIdZ_ReferenceIdNULL - - protocolVersionOdr_bitmaskEmpty bitmask + smallSetUpperBoundint0 - - optionsOdr_bitmaskEmpty bitmask + largeSetLowerBoundint1 - - preferredMessageSizeint30*1024 + mediumSetPresentNumberint0 - - maximumRecordSizeint30*1024 + replaceIndicatorbool_tTRUE - - resultbool_tTRUE + resultSetNamechar *"default" - - implementationIdchar*"YAZ (id=81)" + num_databaseNamesint0 - - 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 @@ -475,260 +464,544 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL - - smallSetUpperBoundint0 + resultCountint0 - - largeSetLowerBoundint1 + numberOfRecordsReturnedint0 - - mediumSetPresentNumberint0 + nextResultSetPositionint0 - - replaceIndicatorbool_tTRUE + searchStatusbool_tTRUE - - resultSetNamechar *"default" + resultSetStatusintNULL - - num_databaseNamesint0 + presentStatusintNULL - - 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" + + + resultSetStartPointint1 + + + numberOfRecordsRequestedint10 + + + num_rangesint0 + + + additionalRangesZ_RangeNULL + + + recordCompositionZ_RecordCompositionNULL + preferredRecordSyntaxOdr_oidNULL - - queryZ_QueryNULL + maxSegmentCountintNULL - - additionalSearchInfoZ_OtherInformationNULL + maxRecordSizeintNULL + + + maxSegmentSizeintNULL + + + otherInfoZ_OtherInformationNULL + + + +
+ + + Default settings for PDU Present Response + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + numberOfRecordsReturnedint0 + + + nextResultSetPositionint0 + + + presentStatusintZ_PresentStatus_success + + + recordsZ_RecordsNULL + + + otherInfoZ_OtherInformationNULL + + + +
+ + + Default settings for Delete Result Set Request + + + + + + + + Field + Type + Default Value + + + + referenceId + Z_ReferenceIdNULL + + + deleteFunctionintZ_DeleteResultSetRequest_list + + + num_idsint0 + + + resultSetListchar**NULL - 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 - - - - 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 - - - - 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 - - - - 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 - - - - 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 - - - - 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 - - - - 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 - - - - 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 - - - - 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 Delete Result Set Response + + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + deleteOperationStatusint + Z_DeleteStatus_success + + num_statusesint0 + + + deleteListStatusesZ_ListStatus**NULL + + + numberNotDeletedintNULL + + + num_bulkStatusesint0 + + + bulkStatusesZ_ListStatusNUL + L + + deleteMessagechar*NULL + + + otherInfoZ_OtherInformationNULL + + + +
- - Z_AccessControlRequest - ---------------------- - Field Type Default value + + Default settings for Scan Request + + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + num_databaseNamesint0 + + + databaseNameschar**NULL + + + attributeSetOdr_oidNULL + + + termListAndStartPointZ_AttributesPlus... + NULL + + stepSizeintNULL + + + numberOfTermsRequestedint20 + + + preferredPositionInResponseintNULL + + + otherInfoZ_OtherInformationNULL + + + +
- referenceId Z_ReferenceId NULL - which enum Z_AccessRequest_simpleForm; - u union NULL - otherInfo Z_OtherInformation NULL - + + Default settings for Scan Response + + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + stepSizeintNULL + + + scanStatusintZ_Scan_success + + + numberOfEntriesReturnedint0 + + + positionOfTermintNULL + + + entriesZ_ListEntrisNULL + + + attributeSetOdr_oidNULL + + + otherInfoZ_OtherInformationNULL + + + +
- - Z_AccessControlResponse - ----------------------- - Field Type Default value + + Default settings for Trigger Resource Control Request + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + requestedActionint + Z_TriggerResourceCtrl_resou.. + + + prefResourceReportFormatOdr_oidNULL + + + resultSetWantedbool_tNULL + + + otherInfoZ_OtherInformationNULL + + + + +
- referenceId Z_ReferenceId NULL - which enum Z_AccessResponse_simpleForm - u union NULL - diagnostic Z_DiagRec NULL - otherInfo Z_OtherInformation NULL - + + Default settings for Resource Control Request + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + suspendedFlagbool_tNULL + + + resourceReportZ_ExternalNULL + + + partialResultsAvailableintNULL + + + responseRequiredbool_tFALSE + + + triggeredRequestFlagbool_tNULL + + + otherInfoZ_OtherInformationNULL + + + +
- - Z_Segment - --------- - Field Type Default value + + Default settings for Resource Control Response + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + continueFlagbool_tTRUE + + + resultSetWantedbool_tNULL + + + otherInfoZ_OtherInformationNULL + + + +
+ + + Default settings for Access Control Request + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + whichenumZ_AccessRequest_simpleForm; + + + uunionNULL + + + otherInfoZ_OtherInformationNULL + + + +
- referenceId Z_ReferenceId NULL - numberOfRecordsReturned int value=0 - num_segmentRecords int 0 - segmentRecords Z_NamePlusRecord NULL - otherInfo Z_OtherInformation NULL - + + Default settings for Access Control Response + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + whichenumZ_AccessResponse_simpleForm + + + uunionNULL + + + diagnosticZ_DiagRecNULL + + + otherInfoZ_OtherInformationNULL + + + +
- - Z_Close - ------- - Field Type Default value + + Default settings for Segment + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + numberOfRecordsReturnedintvalue=0 + + + num_segmentRecordsint0 + + + segmentRecordsZ_NamePlusRecordNULL + + otherInfoZ_OtherInformationNULL + + + +
- referenceId Z_ReferenceId NULL - closeReason int Z_Close_finished - diagnosticInformation char* NULL - resourceReportFormat Odr_oid NULL - resourceFormat Z_External NULL - otherInfo Z_OtherInformation NULL + + Default settings for Close + + + + + + + Field + Type + Default Value + + + - + + referenceIdZ_ReferenceIdNULL + + + closeReasonintZ_Close_finished + + + diagnosticInformationchar*NULL + + + resourceReportFormatOdr_oidNULL + + + resourceFormatZ_ExternalNULL + + + otherInfoZ_OtherInformationNULL + + + + +
@@ -743,7 +1016,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: -->