X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fasn.xml;h=78ee8148a1c0ce6a43c4301eb7078ed064602757;hp=adf59de1051e473c70cfdeb8718a44006dd55a95;hb=053367cbe356fb3ce0def34b065dae589d700daf;hpb=4cc34f9a4eec65d0eb629d070150dd55c5977522 diff --git a/doc/asn.xml b/doc/asn.xml index adf59de..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,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 @@ -370,10 +309,10 @@ typedef struct Z_ext_typeent optionsOdr_bitmaskEmpty bitmask - preferredMessageSizeint30*1024 + preferredMessageSizeOdr_int30*1024 - maximumRecordSizeint30*1024 + maximumRecordSizeOdr_int30*1024 idAuthenticationZ_IdAuthenticationNULL @@ -397,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 @@ -421,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)" @@ -448,7 +388,8 @@ typedef struct Z_ext_typeent
- Default settings for PDU Search Request +
+ Default settings for PDU Search Request @@ -465,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 @@ -510,7 +451,8 @@ typedef struct Z_ext_typeent
- Default settings for PDU Search Response +
+ Default settings for PDU Search Response @@ -523,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 @@ -559,7 +501,8 @@ typedef struct Z_ext_typeent
- Default settings for PDU Present Request +
+ Default settings for PDU Present Request @@ -579,13 +522,13 @@ typedef struct Z_ext_typeent resultSetIdchar*"default" - resultSetStartPointint1 + resultSetStartPointOdr_int1 - numberOfRecordsRequestedint10 + numberOfRecordsRequestedOdr_int10 - num_rangesint0 + num_rangesOdr_int0 additionalRangesZ_RangeNULL @@ -597,13 +540,13 @@ typedef struct Z_ext_typeent preferredRecordSyntaxOdr_oidNULL - maxSegmentCountintNULL + maxSegmentCountOdr_intNULL - maxRecordSizeintNULL + maxRecordSizeOdr_intNULL - maxSegmentSizeintNULL + maxSegmentSizeOdr_intNULL otherInfoZ_OtherInformationNULL @@ -611,8 +554,9 @@ typedef struct Z_ext_typeent
- - Default settings for PDU Present Response + +
+ Default settings for PDU Present Response @@ -629,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 @@ -646,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 @@ -665,10 +610,10 @@ typedef struct Z_ext_typeent Z_ReferenceIdNULL - deleteFunctionintZ_DeleteRequest_list + deleteFunctionOdr_intZ_DeleteResultSetRequest_list - num_idsint0 + num_idsOdr_int0 resultSetListchar**NULL @@ -680,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 @@ -698,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 @@ -725,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 @@ -743,7 +690,7 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - num_databaseNamesint0 + num_databaseNamesOdr_int0 databaseNameschar**NULL @@ -755,13 +702,13 @@ typedef struct Z_ext_typeent termListAndStartPointZ_AttributesPlus... NULL - stepSizeintNULL + stepSizeOdr_intNULL - numberOfTermsRequestedint20 + numberOfTermsRequestedOdr_int20 - preferredPositionInResponseintNULL + preferredPositionInResponseOdr_intNULL otherInfoZ_OtherInformationNULL @@ -770,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 @@ -784,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 @@ -813,8 +761,8 @@ typedef struct Z_ext_typeent
- Default settings for Trigger Resource - Control Request +
+ Default settings for Trigger Resource Control Request @@ -827,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 @@ -863,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 @@ -889,8 +837,8 @@ typedef struct Z_ext_typeent
- Default settings for Resource - Control Response +
+ Default settings for Resource Control Response @@ -903,7 +851,7 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL @@ -919,9 +867,9 @@ typedef struct Z_ext_typeent
- - Default settings for Access - Control Request + +
+ Default settings for Access Control Request @@ -934,7 +882,7 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL @@ -951,8 +899,8 @@ typedef struct Z_ext_typeent
- Default settings for Access - Control Response +
+ Default settings for Access Control Response @@ -965,7 +913,7 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL @@ -985,7 +933,8 @@ typedef struct Z_ext_typeent
- Default settings for Segment +
+ Default settings for Segment @@ -998,15 +947,15 @@ typedef struct Z_ext_typeent - + referenceIdZ_ReferenceIdNULL - numberOfRecordsReturnedintvalue=0 + numberOfRecordsReturnedOdr_intvalue=0 - num_segmentRecordsint0 + num_segmentRecordsOdr_int0 segmentRecordsZ_NamePlusRecordNULL @@ -1017,7 +966,8 @@ typedef struct Z_ext_typeent
- Default settings for Close +
+ Default settings for Close @@ -1035,7 +985,7 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - closeReasonintZ_Close_finished + closeReasonOdr_intZ_Close_finished diagnosticInformationchar*NULL @@ -1049,7 +999,7 @@ typedef struct Z_ext_typeent otherInfoZ_OtherInformationNULL - +