X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fasn.xml;h=78ee8148a1c0ce6a43c4301eb7078ed064602757;hp=3420e635f34c8eda20168c6d8e2b085abbf20bbe;hb=7fbf3f2eceeb0978881992fbf1e77cd6fc3c4a9b;hpb=757c8c0ffb82023c9059d9a5997515f65ad68561 diff --git a/doc/asn.xml b/doc/asn.xml index 3420e63..78ee814 100644 --- a/doc/asn.xml +++ b/doc/asn.xml @@ -1,4 +1,3 @@ - The Z39.50 ASN.1 Module Introduction @@ -6,7 +5,8 @@ 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. @@ -15,12 +15,12 @@ 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, + z3950v3.asn, esupdate.asn, and others. Preparing PDUs - + A structure representing a complex ASN.1 type doesn't in itself contain the members of that type. Instead, the structure contains @@ -38,7 +38,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 @@ -73,7 +73,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 @@ -101,11 +101,11 @@ Z_<type> *zget_<type>(ODR o); - + eg.: - + Z_InitRequest *zget_InitRequest(ODR o); @@ -119,83 +119,21 @@ 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 - + In order to achieve extensibility and adaptability to different application domains, the new version of the protocol defines many @@ -205,7 +143,7 @@ struct oident *oid_getentbyoid(int *o); specialized version of the EXTERNAL construct, called Z_External.It is defined thus: - + typedef struct Z_External { @@ -246,7 +184,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 @@ -260,7 +198,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 @@ -269,9 +207,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); @@ -281,16 +219,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 @@ -301,7 +239,7 @@ 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 @@ -311,7 +249,7 @@ typedef struct Z_ext_typeent 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 @@ -328,7 +266,7 @@ typedef struct Z_ext_typeent is necessary to tell the different, structured types apart on decoding. - + Eventually, the EXTERNAL processing will most likely @@ -338,15 +276,15 @@ typedef struct Z_ext_typeent various modules. - + 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 @@ -371,10 +309,10 @@ typedef struct Z_ext_typeent optionsOdr_bitmaskEmpty bitmask - preferredMessageSizeint30*1024 + preferredMessageSizeOdr_int30*1024 - maximumRecordSizeint30*1024 + maximumRecordSizeOdr_int30*1024 idAuthenticationZ_IdAuthenticationNULL @@ -423,13 +361,13 @@ typedef struct Z_ext_typeent optionsOdr_bitmaskEmpty bitmask - preferredMessageSizeint30*1024 + preferredMessageSizeOdr_int30*1024 - maximumRecordSizeint30*1024 + maximumRecordSizeOdr_int30*1024 - resultbool_tTRUE + resultOdr_boolTRUE implementationIdchar*"id)" @@ -468,22 +406,22 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - smallSetUpperBoundint0 + smallSetUpperBoundOdr_int0 - largeSetLowerBoundint1 + largeSetLowerBoundOdr_int1 - mediumSetPresentNumberint0 + mediumSetPresentNumberOdr_int0 - replaceIndicatorbool_tTRUE + replaceIndicatorOdr_boolTRUE resultSetNamechar *"default" - num_databaseNamesint0 + num_databaseNamesOdr_int0 databaseNameschar **NULL @@ -527,27 +465,27 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL - resultCountint0 + resultCountOdr_int0 - numberOfRecordsReturnedint0 + numberOfRecordsReturnedOdr_int0 - nextResultSetPositionint0 + nextResultSetPositionOdr_int0 - searchStatusbool_tTRUE + searchStatusOdr_boolTRUE - resultSetStatusintNULL + resultSetStatusOdr_intNULL - presentStatusintNULL + presentStatusOdr_intNULL recordsZ_RecordsNULL @@ -584,13 +522,13 @@ typedef struct Z_ext_typeent resultSetIdchar*"default" - resultSetStartPointint1 + resultSetStartPointOdr_int1 - numberOfRecordsRequestedint10 + numberOfRecordsRequestedOdr_int10 - num_rangesint0 + num_rangesOdr_int0 additionalRangesZ_RangeNULL @@ -602,13 +540,13 @@ typedef struct Z_ext_typeent preferredRecordSyntaxOdr_oidNULL - maxSegmentCountintNULL + maxSegmentCountOdr_intNULL - maxRecordSizeintNULL + maxRecordSizeOdr_intNULL - maxSegmentSizeintNULL + maxSegmentSizeOdr_intNULL otherInfoZ_OtherInformationNULL @@ -616,7 +554,7 @@ typedef struct Z_ext_typeent
- + Default settings for PDU Present Response @@ -635,13 +573,13 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - numberOfRecordsReturnedint0 + numberOfRecordsReturnedOdr_int0 - nextResultSetPositionint0 + nextResultSetPositionOdr_int0 - presentStatusintZ_PresentStatus_success + presentStatusOdr_intZ_PresentStatus_success recordsZ_RecordsNULL @@ -652,7 +590,7 @@ typedef struct Z_ext_typeent
- + Default settings for Delete Result Set Request @@ -672,10 +610,10 @@ typedef struct Z_ext_typeent Z_ReferenceIdNULL - deleteFunctionintZ_DeleteResultSetRequest_list + deleteFunctionOdr_intZ_DeleteResultSetRequest_list - num_idsint0 + num_idsOdr_int0 resultSetListchar**NULL @@ -706,19 +644,19 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - deleteOperationStatusint + deleteOperationStatusOdr_int Z_DeleteStatus_success - num_statusesint0 + num_statusesOdr_int0 deleteListStatusesZ_ListStatus**NULL - numberNotDeletedintNULL + numberNotDeletedOdr_intNULL - num_bulkStatusesint0 + num_bulkStatusesOdr_int0 bulkStatusesZ_ListStatusNUL @@ -752,7 +690,7 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - num_databaseNamesint0 + num_databaseNamesOdr_int0 databaseNameschar**NULL @@ -764,13 +702,13 @@ typedef struct Z_ext_typeent termListAndStartPointZ_AttributesPlus... NULL - stepSizeintNULL + stepSizeOdr_intNULL - numberOfTermsRequestedint20 + numberOfTermsRequestedOdr_int20 - preferredPositionInResponseintNULL + preferredPositionInResponseOdr_intNULL otherInfoZ_OtherInformationNULL @@ -794,21 +732,21 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL - stepSizeintNULL + stepSizeOdr_intNULL - scanStatusintZ_Scan_success + scanStatusOdr_intZ_Scan_success - numberOfEntriesReturnedint0 + numberOfEntriesReturnedOdr_int0 - positionOfTermintNULL + positionOfTermOdr_intNULL entriesZ_ListEntrisNULL @@ -837,24 +775,24 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL - requestedActionint + requestedActionOdr_int Z_TriggerResourceCtrl_resou.. prefResourceReportFormatOdr_oidNULL - resultSetWantedbool_tNULL + resultSetWantedOdr_boolNULL otherInfoZ_OtherInformationNULL - +
@@ -873,24 +811,24 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL - suspendedFlagbool_tNULL + suspendedFlagOdr_boolNULL resourceReportZ_ExternalNULL - partialResultsAvailableintNULL + partialResultsAvailableOdr_intNULL - responseRequiredbool_tFALSE + responseRequiredOdr_boolFALSE - triggeredRequestFlagbool_tNULL + triggeredRequestFlagOdr_boolNULL otherInfoZ_OtherInformationNULL @@ -913,7 +851,7 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL @@ -929,7 +867,7 @@ typedef struct Z_ext_typeent - + Default settings for Access Control Request @@ -944,7 +882,7 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL @@ -975,7 +913,7 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL @@ -1009,15 +947,15 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL - numberOfRecordsReturnedintvalue=0 + numberOfRecordsReturnedOdr_intvalue=0 - num_segmentRecordsint0 + num_segmentRecordsOdr_int0 segmentRecordsZ_NamePlusRecordNULL @@ -1047,7 +985,7 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - closeReasonintZ_Close_finished + closeReasonOdr_intZ_Close_finished diagnosticInformationchar*NULL @@ -1061,7 +999,7 @@ typedef struct Z_ext_typeent otherInfoZ_OtherInformationNULL - +