X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fodr.xml;h=770ad9cd1be24fa56682c1cdb15f54f82d20b4d3;hp=cb1fc65f7b973746427b14b34d24b47147b01a64;hb=5541b773e8ee0e5c086946016c060f6f629bd410;hpb=ef696802e6afb3df60b27070a432a48f064dc777 diff --git a/doc/odr.xml b/doc/odr.xml index cb1fc65..770ad9c 100644 --- a/doc/odr.xml +++ b/doc/odr.xml @@ -1,6 +1,5 @@ - The ODR Module - + Introduction @@ -39,7 +38,7 @@ Using ODR - ODR Streams + ODR Streams Conceptually, the ODR stream is the source of encoded data in the @@ -74,7 +73,7 @@ - Memory Management + Memory Management Two forms of memory management take place in the &odr; system. The first @@ -95,7 +94,7 @@ - void *odr_malloc(ODR o, int size); + void *odr_malloc(ODR o, size_t size); @@ -105,7 +104,7 @@ - void odr_reset(ODR o, int size); + void odr_reset(ODR o); @@ -121,7 +120,7 @@ - int odr_total(ODR o); + size_t odr_total(ODR o); @@ -169,7 +168,7 @@ - Encoding and Decoding Data + Encoding and Decoding Data When encoding data, the ODR stream will write the encoded octet string @@ -259,11 +258,12 @@ data you wish to decode (eg, odr_integer() odr z_APDU()). - - Encoding and decoding functions + + + Encoding and decoding functions - int odr_integer(ODR o, int **p, int optional, const char *name); - + int odr_integer(ODR o, Odr_int **p, int optional, const char *name); + int z_APDU(ODR o, Z_APDU **p, int optional, const char *name); @@ -293,12 +293,13 @@ free(2) to release the memory. You can decode several data elements (by repeated calls to odr_setbuf() and your decoding function), and - new memory will be allocated each time. When you do call + new memory will be allocated each time. When you do call odr_reset(), everything decoded since the 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), @@ -307,36 +308,37 @@ informative operation. - + - Printing + 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. @@ -376,11 +378,11 @@ void do_nothing_useful(int value) 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. + 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 + as parameter, the user defined handle, a type ODR_OCTETSTRING, ODR_VISIBLESTRING which indicates the type of contents is being written. @@ -390,23 +392,23 @@ void do_nothing_useful(int value) 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, + 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 + is presentResponse, databaseOrSurDiagnostics, ?, record, ?, databaseRecord . The question mark appears due to unnamed constructions. - Diagnostics + Diagnostics The encoding/decoding functions all return 0 when an error occurs. @@ -440,7 +442,8 @@ void do_nothing_useful(int value) one of these constants: - ODR Error codes +
+ ODR Error codes @@ -489,7 +492,7 @@ void do_nothing_useful(int value) - char *odr_errlist[] + char *odr_errlist[] @@ -498,10 +501,11 @@ void do_nothing_useful(int value) - Summary and Synopsis + + Summary and Synopsis - #include <odr.h> + #include <yaz/odr.h> ODR odr_createmem(int direction); @@ -509,19 +513,17 @@ void do_nothing_useful(int value) void odr_reset(ODR o); - char *odr_getbuf(ODR o, int *len); + char *odr_getbuf(ODR o, int *len, int *size); - void odr_setbuf(ODR o, char *buf, int len); + void odr_setbuf(ODR o, char *buf, int len, int can_grow); void *odr_malloc(ODR o, int size); - ODR_MEM odr_extract_mem(ODR o); - - void odr_release_mem(ODR_MEM r); + NMEM odr_extract_mem(ODR o); int odr_geterror(ODR o); - void odr_perror(char *message); + void odr_perror(ODR o, const char *message); extern char *odr_errlist[]; @@ -541,11 +543,11 @@ void do_nothing_useful(int value) There is an ASN.1 tutorial available at this site. - This site also has standards for ASN.1 (X.680) and BER (X.690) + This site also has standards for ASN.1 (X.680) and BER (X.690) online. - + The ODR interface is based loosely on that of the Sun Microsystems XDR routines. @@ -558,9 +560,9 @@ void do_nothing_useful(int value) definition for a type once - and you have the functionality of encoding, decoding (and pretty-printing) all in one unit. The resulting C source code is quite compact, and is a pretty - straightforward representation of the source ASN.1 specification. + straightforward representation of the source ASN.1 specification. - + In many cases, the model of the XDR functions works quite well in this role. @@ -568,14 +570,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 @@ -583,13 +586,13 @@ void do_nothing_useful(int value) - int odr_integer(ODR o, int **p, int optional, const char *name); + int odr_integer(ODR o, Odr_int **p, int optional, const char *name); - (we don't allow values that can't be contained in a C integer.) + The Odr_int is just a simple integer. - + This form is typical of the primitive &odr; functions. They are named after the type of data that they encode or decode. They take an &odr; @@ -633,24 +636,24 @@ void do_nothing_useful(int value) similar manners: - BOOLEAN + BOOLEAN -int odr_bool(ODR o, bool_t **p, int optional, const char *name); +int odr_bool(ODR o, Odr_bool **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); +int odr_null(ODR o, Odr_null **p, int optional, const char *name); @@ -660,7 +663,7 @@ int odr_null(ODR o, bool_t **p, int optional, const char *name); - OCTET STRING + OCTET STRING typedef struct odr_oct @@ -707,7 +710,7 @@ int odr_visiblestring(ODR o, char **p, int optional, - BIT STRING + BIT STRING int odr_bitstring(ODR o, Odr_bitmask **p, int optional, @@ -745,7 +748,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); @@ -754,19 +757,19 @@ 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 - odr_implicit_tag() or + odr_implicit_tag() or odr_explicit_tag() macros: @@ -784,7 +787,7 @@ int odr_explicit_tag(ODR o, Odr_fun fun, int class, int tag, - MyInt ::= [210] IMPLICIT INTEGER + MyInt ::= [210] IMPLICIT INTEGER @@ -792,7 +795,7 @@ int odr_explicit_tag(ODR o, Odr_fun fun, int class, int tag, -int myInt(ODR o, int **p, int optional, const char *name) +int myInt(ODR o, Odr_int **p, int optional, const char *name) { return odr_implicit_tag(o, odr_integer, p, ODR_CONTEXT, 210, optional, name); @@ -813,7 +816,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 @@ -864,10 +867,10 @@ MySequence ::= SEQUENCE { typedef struct MySequence { - int *intval; - bool_t *boolval; + Odr_int *intval; + Odr_bool *boolval; } MySequence; - + int mySequence(ODR o, MySequence **p, int optional, const char *name) { if (odr_sequence_begin(o, p, sizeof(**p), name) == 0) @@ -900,23 +903,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 } @@ -957,7 +962,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, @@ -969,7 +974,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 } @@ -1032,7 +1037,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 @@ -1066,7 +1071,7 @@ MyArray ::= SEQUENCE OF INTEGER typedef struct MyArray { int num_elements; - int **elements; + Odr_int **elements; } MyArray; @@ -1088,7 +1093,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 @@ -1100,7 +1105,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); @@ -1145,7 +1150,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. @@ -1170,7 +1175,7 @@ typedef struct odr_arm MyChoice ::= CHOICE { untagged INTEGER, - tagged [99] IMPLICIT INTEGER, + tagged [99] IMPLICIT INTEGER, other BOOLEAN } @@ -1190,9 +1195,9 @@ typedef struct MyChoice } which; union { - int *untagged; - int *tagged; - bool_t *other; + Odr_int *untagged; + Odr_int *tagged; + Odr_bool *other; } u; }; @@ -1204,7 +1209,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,