X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fasn.xml;h=c787d4f62402016f059b10038d8b9b05c4ff1a40;hp=2e3f8360915888f85be7a9bc6a1b2e79a7583654;hb=58b73e42cc56014e9a1f57474884c6bd4e97ccc1;hpb=79890eac643c81189343316b06f2d14445cbd023 diff --git a/doc/asn.xml b/doc/asn.xml index 2e3f836..c787d4f 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 @@ -125,69 +132,7 @@ - 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 @@ -264,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); @@ -278,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; @@ -301,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 + ). @@ -333,14 +278,15 @@ 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 @@ -363,19 +309,19 @@ typedef struct Z_ext_typeent optionsOdr_bitmaskEmpty bitmask - preferredMessageSizeint30*1024 + preferredMessageSizeOdr_int30*1024 - maximumRecordSizeint30*1024 + maximumRecordSizeOdr_int30*1024 idAuthenticationZ_IdAuthenticationNULL - implementationIdchar*"YAZ (id=81)" + implementationIdchar*"81" - implementationNamechar*"Index Data/YAZ" + implementationNamechar*"YAZ" implementationVersionchar*YAZ_VERSION @@ -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,19 +361,19 @@ typedef struct Z_ext_typeent optionsOdr_bitmaskEmpty bitmask - preferredMessageSizeint30*1024 + preferredMessageSizeOdr_int30*1024 - maximumRecordSizeint30*1024 + maximumRecordSizeOdr_int30*1024 - resultbool_tTRUE + resultOdr_boolTRUE - implementationIdchar*"YAZ (id=81)" + implementationIdchar*"id)" - implementationNamechar*"Index Data/YAZ" + implementationNamechar*"YAZ" implementationVersionchar*YAZ_VERSION @@ -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 @@ -521,22 +470,22 @@ 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 @@ -605,7 +555,8 @@ 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 @@ -640,7 +591,8 @@ 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 @@ -782,16 +737,16 @@ 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 @@ -825,14 +780,14 @@ typedef struct Z_ext_typeent referenceIdZ_ReferenceIdNULL - requestedActionint + requestedActionOdr_int Z_TriggerResourceCtrl_resou.. prefResourceReportFormatOdr_oidNULL - resultSetWantedbool_tNULL + resultSetWantedOdr_boolNULL otherInfoZ_OtherInformationNULL @@ -842,8 +797,8 @@ typedef struct Z_ext_typeent
- Default settings for Resource - Control Request +
+ Default settings for Resource Control Request @@ -861,19 +816,19 @@ 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 @@ -913,8 +868,8 @@ typedef struct Z_ext_typeent
- Default settings for Access - Control Request +
+ Default settings for Access Control Request @@ -944,8 +899,8 @@ typedef struct Z_ext_typeent
- Default settings for Access - Control Response +
+ Default settings for Access Control Response @@ -978,7 +933,8 @@ typedef struct Z_ext_typeent
- Default settings for Segment +
+ Default settings for Segment @@ -996,10 +952,10 @@ 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 @@ -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: -->