X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fasn.xml;h=78ee8148a1c0ce6a43c4301eb7078ed064602757;hp=85bdc94f80c5617361c4d63583f63036f2fd301f;hb=053367cbe356fb3ce0def34b065dae589d700daf;hpb=ab0fd2f75e554d1c9c0e722abf073f9840f7739b diff --git a/doc/asn.xml b/doc/asn.xml index 85bdc94..78ee814 100644 --- a/doc/asn.xml +++ b/doc/asn.xml @@ -1,19 +1,26 @@ - - The ASN.1 Module + 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 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 - + A structure representing a complex ASN.1 type doesn't in itself contain the members of that type. Instead, the structure contains @@ -31,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 @@ -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 @@ -66,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 @@ -94,11 +101,11 @@ Z_<type> *zget_<type>(ODR o); - + eg.: - + Z_InitRequest *zget_InitRequest(ODR o); @@ -112,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 @@ -198,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 { @@ -239,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 @@ -253,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 @@ -262,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); @@ -274,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 @@ -294,17 +239,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 @@ -321,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 @@ -331,16 +276,17 @@ 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 + +
+ Default settings for PDU Initialize Request @@ -363,10 +309,10 @@ typedef struct Z_ext_typeent optionsOdr_bitmaskEmpty bitmask - preferredMessageSizeint30*1024 + preferredMessageSizeOdr_int30*1024 - maximumRecordSizeint30*1024 + maximumRecordSizeOdr_int30*1024 idAuthenticationZ_IdAuthenticationNULL @@ -390,7 +336,8 @@ typedef struct Z_ext_typeent
- Default settings for PDU Initialize + <table frame="top" id="asn.default.initialize.response"> + <title>Default settings for PDU Initialize Response @@ -414,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)" @@ -441,7 +388,8 @@ typedef struct Z_ext_typeent
- Default settings for PDU Search Request +
+ Default settings for PDU Search Request @@ -458,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 @@ -503,7 +451,8 @@ typedef struct Z_ext_typeent
- Default settings for PDU Search Response +
+ Default settings for PDU Search Response @@ -516,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 @@ -552,7 +501,8 @@ typedef struct Z_ext_typeent
- Default settings for PDU Present Request +
+ Default settings for PDU Present Request @@ -572,13 +522,13 @@ typedef struct Z_ext_typeent resultSetIdchar*"default" - resultSetStartPointint1 + resultSetStartPointOdr_int1 - numberOfRecordsRequestedint10 + numberOfRecordsRequestedOdr_int10 - num_rangesint0 + num_rangesOdr_int0 additionalRangesZ_RangeNULL @@ -590,13 +540,13 @@ typedef struct Z_ext_typeent preferredRecordSyntaxOdr_oidNULL - maxSegmentCountintNULL + maxSegmentCountOdr_intNULL - maxRecordSizeintNULL + maxRecordSizeOdr_intNULL - maxSegmentSizeintNULL + maxSegmentSizeOdr_intNULL otherInfoZ_OtherInformationNULL @@ -604,8 +554,9 @@ typedef struct Z_ext_typeent
- - Default settings for PDU Present Response + +
+ Default settings for PDU Present Response @@ -622,13 +573,13 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - numberOfRecordsReturnedint0 + numberOfRecordsReturnedOdr_int0 - nextResultSetPositionint0 + nextResultSetPositionOdr_int0 - presentStatusintZ_PRES_SUCCESS + presentStatusOdr_intZ_PresentStatus_success recordsZ_RecordsNULL @@ -639,8 +590,9 @@ typedef struct Z_ext_typeent
- - Default settings for Delete Result Set Request + + <table frame="top" id="asn.default.delete.result.set.request"> + <title>Default settings for Delete Result Set Request @@ -658,10 +610,10 @@ typedef struct Z_ext_typeent Z_ReferenceIdNULL - deleteFunctionintZ_DeleteRequest_list + deleteFunctionOdr_intZ_DeleteResultSetRequest_list - num_idsint0 + num_idsOdr_int0 resultSetListchar**NULL @@ -673,7 +625,8 @@ typedef struct Z_ext_typeent
- Default settings for Delete Result Set Response + <table frame="top" id="asn.default.delete.result.set.response"> + <title>Default settings for Delete Result Set Response @@ -691,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 @@ -718,7 +671,8 @@ typedef struct Z_ext_typeent
- Default settings for Scan Request + <table frame="top" id="asn.default.scan.request"> + <title>Default settings for Scan Request @@ -736,7 +690,7 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - num_databaseNamesint0 + num_databaseNamesOdr_int0 databaseNameschar**NULL @@ -748,13 +702,13 @@ typedef struct Z_ext_typeent termListAndStartPointZ_AttributesPlus... NULL - stepSizeintNULL + stepSizeOdr_intNULL - numberOfTermsRequestedint20 + numberOfTermsRequestedOdr_int20 - preferredPositionInResponseintNULL + preferredPositionInResponseOdr_intNULL otherInfoZ_OtherInformationNULL @@ -763,7 +717,8 @@ typedef struct Z_ext_typeent
- Default settings for Scan Response + <table frame="top" id="asn.default.scan.response"> + <title>Default settings for Scan Response @@ -777,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 @@ -806,8 +761,8 @@ typedef struct Z_ext_typeent
- Default settings for Trigger Resource - Control Request +
+ Default settings for Trigger Resource Control Request @@ -820,30 +775,30 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL - requestedActionint + requestedActionOdr_int Z_TriggerResourceCtrl_resou.. prefResourceReportFormatOdr_oidNULL - resultSetWantedbool_tNULL + resultSetWantedOdr_boolNULL otherInfoZ_OtherInformationNULL - +
- Default settings for Resource - Control Request +
+ Default settings for Resource Control Request @@ -856,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 @@ -882,8 +837,8 @@ typedef struct Z_ext_typeent
- Default settings for Resource - Control Response +
+ Default settings for Resource Control Response @@ -896,7 +851,7 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL @@ -912,9 +867,9 @@ typedef struct Z_ext_typeent
- - Default settings for Access - Control Request + +
+ Default settings for Access Control Request @@ -927,7 +882,7 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL @@ -944,8 +899,8 @@ typedef struct Z_ext_typeent
- Default settings for Access - Control Response +
+ Default settings for Access Control Response @@ -958,7 +913,7 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL @@ -978,7 +933,8 @@ typedef struct Z_ext_typeent
- Default settings for Segment +
+ Default settings for Segment @@ -991,15 +947,15 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL - numberOfRecordsReturnedintvalue=0 + numberOfRecordsReturnedOdr_intvalue=0 - num_segmentRecordsint0 + num_segmentRecordsOdr_int0 segmentRecordsZ_NamePlusRecordNULL @@ -1010,7 +966,8 @@ typedef struct Z_ext_typeent
- Default settings for Close +
+ Default settings for Close @@ -1028,7 +985,7 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - closeReasonintZ_Close_finished + closeReasonOdr_intZ_Close_finished diagnosticInformationchar*NULL @@ -1042,7 +999,7 @@ typedef struct Z_ext_typeent otherInfoZ_OtherInformationNULL - +
@@ -1060,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: -->