X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fodr.xml;h=4ea7ed0a9bdd6f6835e522a98c1f8b3c7fcb7d97;hp=2824d6c481c5b855f8c5d79c548f137e4620bebe;hb=03531ce2d54914dde2e679aa6382eb04d9e8f1d6;hpb=4cc34f9a4eec65d0eb629d070150dd55c5977522 diff --git a/doc/odr.xml b/doc/odr.xml index 2824d6c..4ea7ed0 100644 --- a/doc/odr.xml +++ b/doc/odr.xml @@ -1,4 +1,4 @@ - + The ODR Module Introduction @@ -39,7 +39,7 @@ Using ODR - ODR Streams + ODR Streams Conceptually, the ODR stream is the source of encoded data in the @@ -74,7 +74,7 @@ - Memory Management + Memory Management Two forms of memory management take place in the &odr; system. The first @@ -169,7 +169,7 @@ - Encoding and Decoding Data + Encoding and Decoding Data When encoding data, the ODR stream will write the encoded octet string @@ -260,7 +260,8 @@ z_APDU()). - Encoding and decoding functions + + Encoding and decoding functions int odr_integer(ODR o, int **p, int optional, const char *name); @@ -298,7 +299,8 @@ last call to odr_reset() will be released. - Encoding and decoding of an integer + + Encoding and decoding of an integer The use of the double indirection can be a little confusing at first (its purpose will become clear later on, hopefully), @@ -355,7 +357,58 @@ void do_nothing_useful(int value) - Diagnostics + Printing + + When an ODR stream is created of type ODR_PRINT + the ODR module will print the contents of a PDU in a readable format. + By default output is written to the stderr stream. + This behavior can be changed, however, by calling the function + + odr_setprint(ODR o, FILE *file); + + before encoders or decoders are being invoked. + It is also possible to direct the output to a buffer (of indeed + another file), by using the more generic mechanism: + + void odr_set_stream(ODR o, void *handle, + void (*stream_write)(ODR o, void *handle, int type, + const char *buf, int len), + void (*stream_close)(void *handle)); + + Here the user provides an opaque handle and two handlers, + stream_write for writing, + and stream_close which is supposed + to close/free resources associated with handle. + The stream_close handler is optional and + if NULL for the function is provided, it will not be invoked. + The stream_write takes the ODR handle + as parameter, the user defined handle, a type + ODR_OCTETSTRING, ODR_VISIBLESTRING + which indicates the type of contents is being written. + + + Another utility useful for diagnostics (error handling) or as + part of the printing facilities is: + + const char **odr_get_element_path(ODR o); + + which returns a list of current elements that ODR deals with at the + moment. For the returned array, say ar, + ar[0] is the top level element, + ar[n] is the last. The last element has the + property that ar[n+1] == NULL. + + + Element Path for record + + For a database record part of a PresentResponse the + array returned by odr_get_element + is presentResponse, databaseOrSurDiagnostics, ?, record, ?, databaseRecord . The question mark appears due to + unnamed constructions. + + + + Diagnostics The encoding/decoding functions all return 0 when an error occurs. @@ -389,7 +442,8 @@ void do_nothing_useful(int value) one of these constants: - ODR Error codes +
+ ODR Error codes @@ -438,7 +492,7 @@ void do_nothing_useful(int value) - char *odr_errlist[] + char *odr_errlist[] @@ -447,7 +501,8 @@ void do_nothing_useful(int value) - Summary and Synopsis + + Summary and Synopsis #include <odr.h> @@ -489,9 +544,9 @@ void do_nothing_useful(int value) There is an ASN.1 tutorial available at - this site. + this site. This site also has standards for ASN.1 (X.680) and BER (X.690) - online. + online. @@ -517,14 +572,15 @@ void do_nothing_useful(int value) SEQUENCE members which don't exist in XDR. - The Primitive ASN.1 Types + + The Primitive ASN.1 Types ASN.1 defines a number of primitive types (many of which correspond roughly to primitive types in structured programming languages, such as C). - INTEGER + INTEGER The &odr; function for encoding or decoding (or printing) the ASN.1 @@ -582,21 +638,21 @@ void do_nothing_useful(int value) similar manners: - BOOLEAN + BOOLEAN int odr_bool(ODR o, bool_t **p, int optional, const char *name); - REAL + REAL Not defined. - NULL + NULL int odr_null(ODR o, bool_t **p, int optional, const char *name); @@ -609,7 +665,7 @@ int odr_null(ODR o, bool_t **p, int optional, const char *name); - OCTET STRING + OCTET STRING typedef struct odr_oct @@ -656,7 +712,7 @@ int odr_visiblestring(ODR o, char **p, int optional, - BIT STRING + BIT STRING int odr_bitstring(ODR o, Odr_bitmask **p, int optional, @@ -694,7 +750,7 @@ int ODR_MASK_GET(Odr_bitmask *b, int bitno); - OBJECT IDENTIFIER + OBJECT IDENTIFIER int odr_oid(ODR o, Odr_oid **p, int optional, const char *name); @@ -703,15 +759,15 @@ int odr_oid(ODR o, Odr_oid **p, int optional, const char *name); The C OID representation is simply an array of integers, terminated by the value -1 (the Odr_oid type is synonymous with - the int type). + the short type). We suggest that you use the OID database module (see - ) to handle object identifiers + ) to handle object identifiers in your application. - Tagging Primitive Types + Tagging Primitive Types The simplest way of tagging a type is to use the @@ -733,7 +789,7 @@ int odr_explicit_tag(ODR o, Odr_fun fun, int class, int tag, - MyInt ::= [210] IMPLICIT INTEGER + MyInt ::= [210] IMPLICIT INTEGER @@ -762,7 +818,7 @@ int myInt(ODR o, int **p, int optional, const char *name) - Constructed Types + Constructed Types Constructed types are created by combining primitive types. The @@ -849,23 +905,25 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name) - Tagging Constructed Types + + Tagging Constructed Types - See for information on how to tag + See for information on how to tag the primitive types, as well as types that are already defined. - Implicit Tagging + + Implicit Tagging Assume the type above had been defined as -MySequence ::= [10] IMPLICIT SEQUENCE { +MySequence ::= [10] IMPLICIT SEQUENCE { intval INTEGER, boolval BOOLEAN OPTIONAL } @@ -906,7 +964,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name) - Explicit Tagging + Explicit Tagging Explicit tagging of constructed types is a little more complicated, @@ -918,7 +976,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name) -MySequence ::= [10] IMPLICIT SEQUENCE { +MySequence ::= [10] IMPLICIT SEQUENCE { intval INTEGER, boolval BOOLEAN OPTIONAL } @@ -981,7 +1039,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name) - SEQUENCE OF + SEQUENCE OF To handle sequences (arrays) of a specific type, the function @@ -1037,7 +1095,7 @@ int myArray(ODR o, MyArray **p, int optional, const char *name) - CHOICE Types + CHOICE Types The choice type is used fairly often in some ASN.1 definitions, so @@ -1049,7 +1107,7 @@ int myArray(ODR o, MyArray **p, int optional, const char *name) -int odr_choice(ODR o, Odr_arm arm[], void *p, void *whichp, +int odr_choice(ODR o, Odr_arm arm[], void *p, void *whichp, const char *name); @@ -1094,7 +1152,7 @@ typedef struct odr_arm which The value of the discriminator that corresponds to - this CHOICE element. Typically, it will be a #defined constant, or + this CHOICE element. Typically, it will be a #defined constant, or an enum member. @@ -1119,7 +1177,7 @@ typedef struct odr_arm MyChoice ::= CHOICE { untagged INTEGER, - tagged [99] IMPLICIT INTEGER, + tagged [99] IMPLICIT INTEGER, other BOOLEAN } @@ -1153,7 +1211,7 @@ typedef struct MyChoice int myChoice(ODR o, MyChoice **p, int optional, const char *name) { - static Odr_arm arm[] = + static Odr_arm arm[] = { {-1, -1, -1, MyChoice_untagged, odr_integer, "untagged"}, {ODR_IMPLICIT, ODR_CONTEXT, 99, MyChoice_tagged, odr_integer,