X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fodr.xml;h=627f5c91966e6af38424bc8e636af35aa1ae6f4d;hb=a041518cb98067d3f7c7130258b09de83cde8821;hp=6a135e9881d0f0a50a73fcce81ee821c31641f02;hpb=23403c6f31b26b0e819a47980c42f3fc8c57d84d;p=yaz-moved-to-github.git diff --git a/doc/odr.xml b/doc/odr.xml index 6a135e9..627f5c9 100644 --- a/doc/odr.xml +++ b/doc/odr.xml @@ -1,4 +1,3 @@ - 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 @@ -105,7 +104,7 @@ - void odr_reset(ODR o, int size); + void odr_reset(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 @@ -260,7 +259,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 +298,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), @@ -320,23 +321,23 @@ void do_nothing_useful(int value) if (!(decode = odr_createmem(ODR_DECODE))) return; - valp = &value; - if (odr_integer(encode, &valp, 0, 0) == 0) + valp = &value; + if (odr_integer(encode, &valp, 0, 0) == 0) { printf("encoding went bad\n"); return; } - bufferp = odr_getbuf(encode, &len); - printf("length of encoded data is %d\n", len); + bufferp = odr_getbuf(encode, &len, 0); + printf("length of encoded data is %d\n", len); /* now let's decode the thing again */ - odr_setbuf(decode, bufferp, len); - if (odr_integer(decode, &resvalp, 0, 0) == 0) + odr_setbuf(decode, bufferp, len, 0); + if (odr_integer(decode, &resvalp, 0, 0) == 0) { printf("decoding went bad\n"); return; } - printf("the value is %d\n", *resvalp); + printf("the value is %d\n", *resvalp); /* clean up */ odr_destroy(encode); @@ -355,7 +356,7 @@ void do_nothing_useful(int value) - 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. @@ -396,7 +397,7 @@ void do_nothing_useful(int value) 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 @@ -406,7 +407,7 @@ void do_nothing_useful(int value) - Diagnostics + Diagnostics The encoding/decoding functions all return 0 when an error occurs. @@ -440,7 +441,8 @@ void do_nothing_useful(int value) one of these constants: - ODR Error codes +
+ ODR Error codes @@ -489,7 +491,7 @@ void do_nothing_useful(int value) - char *odr_errlist[] + char *odr_errlist[] @@ -498,10 +500,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 +512,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[]; @@ -568,14 +569,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 @@ -633,21 +635,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); @@ -660,7 +662,7 @@ int odr_null(ODR o, bool_t **p, int optional, const char *name); - OCTET STRING + OCTET STRING typedef struct odr_oct @@ -707,7 +709,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 +747,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,15 +756,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 @@ -784,7 +786,7 @@ int odr_explicit_tag(ODR o, Odr_fun fun, int class, int tag, - MyInt ::= [210] IMPLICIT INTEGER + MyInt ::= [210] IMPLICIT INTEGER @@ -813,7 +815,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 @@ -900,23 +902,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 +961,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 +973,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 +1036,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 @@ -1088,7 +1092,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 +1104,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 +1149,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 +1174,7 @@ typedef struct odr_arm MyChoice ::= CHOICE { untagged INTEGER, - tagged [99] IMPLICIT INTEGER, + tagged [99] IMPLICIT INTEGER, other BOOLEAN } @@ -1204,7 +1208,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,