X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fodr.xml;h=8b1cc4f8faf5ddf8663a3b0665dc8accfc878fb4;hb=a54c709b3e2feff5762bfa7dfa8ee653b429d369;hp=de0b3ca4955cf6bb9cf911247ab509364df8636b;hpb=ce853cc4919ab346fd629e7727905d3ee6e1129f;p=yaz-moved-to-github.git diff --git a/doc/odr.xml b/doc/odr.xml index de0b3ca..8b1cc4f 100644 --- a/doc/odr.xml +++ b/doc/odr.xml @@ -1,7 +1,7 @@ - - The ODR Module + + The ODR Module - Introduction + Introduction &odr; is the BER-encoding/decoding subsystem of &yaz;. Care as been taken @@ -23,9 +23,9 @@ - This is important, so we'll repeat it for emphasis: You do not - need to read section Programming with ODR to - implement Z39.50 with &yaz;. + This is important, so we'll repeat it for emphasis: You do + not need to read section Programming with + ODR to implement Z39.50 with &yaz;. @@ -37,7 +37,7 @@ - Using ODR + Using ODR ODR Streams @@ -132,10 +132,10 @@ The memory subsystem of &odr; is fairly efficient at allocating and releasing little bits of memory. Rather than managing the individual, - small bits of space, the system maintains a freelist of larger chunks + small bits of space, the system maintains a free-list of larger chunks of memory, which are handed out in small bits. This scheme is generally known as a nibble memory system. - It is very useful for maintaing short-lived constructions such + It is very useful for maintaining short-lived constructions such as protocol PDUs. @@ -184,7 +184,7 @@ The integer pointed to by len is set to the length of the encoded data, and a pointer to that data is returned. *size is set to the size of the buffer (unless size is null, - signalling that you are not interested in the size). The next call to + signaling that you are not interested in the size). The next call to a primitive function using the same &odr; stream will overwrite the data, unless a different buffer has been supplied using the call @@ -235,7 +235,7 @@ - It is important to realise that the ODR stream will not release this + It is important to realize that the ODR stream will not release this memory when you call odr_reset(): It will merely update its internal pointers to prepare for the encoding of a new data value. @@ -244,7 +244,7 @@ be released only if the can_grow parameter to odr_setbuf() was nonzero. The can_grow parameter, in other words, is a way of - signalling who is to own the buffer, you or the ODR stream. If you never call + signaling who is to own the buffer, you or the ODR stream. If you never call odr_setbuf() on your encoding stream, which is typically the case, the buffer allocated by the stream will belong to the stream by default. @@ -480,7 +480,7 @@ void do_nothing_useful(int value) - Programming with ODR + Programming with ODR The API of &odr; is designed to reflect the structure of ASN.1, rather @@ -489,28 +489,25 @@ void do_nothing_useful(int value) - The interface is based loosely on that of the Sun Microsystems XDR routines. + The interface is based loosely on that of the Sun Microsystems XDR + routines. Specifically, each function which corresponds to an ASN.1 primitive type has a dual function. Depending on the settings of the ODR stream which is supplied as a parameter, the function may be used either to encode or decode data. The functions that can be built - using these primitive functions, to represent more complex datatypes, share - this quality. The result is that you only have to enter the 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. Although no ASN.1 compiler is supplied - with &odr; at this time, it shouldn't be too difficult to write one, or - perhaps even to adapt an existing compiler to output &odr; routines - (not surprisingly, writing encoders/decoders using &odr; turns out - to be boring work). + using these primitive functions, to represent more complex data types, + share this quality. The result is that you only have to enter the + 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. In many cases, the model of the XDR functions works quite well in this role. In others, it is less elegant. Most of the hassle comes from the optional - SEQUENCE memebers which don't exist in XDR. + SEQUENCE members which don't exist in XDR. The Primitive ASN.1 Types @@ -682,7 +679,7 @@ int ODR_MASK_GET(Odr_bitmask *b, int bitno); - The functions are modelled after the manipulation functions that + The functions are modeled after the manipulation functions that accompany the fd_set type used by the select(2) call. ODR_MASK_ZERO should always be called first on a @@ -697,7 +694,7 @@ int odr_oid(ODR o, Odr_oid **p, int optional, const char *name); - The C OID represenation is simply an array of integers, terminated by + 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). We suggest that you use the OID database module (see section @@ -747,8 +744,8 @@ int myInt(ODR o, int **p, int optional, const char *name) The function myInt() can then be used like any of the primitive functions provided by &odr;. Note that the behavior of - odr_explicit() - and odr_implicit() macros + odr_explicit_tag() + and odr_implicit_tag() macros act exactly the same as the functions they are applied to - they respond to error conditions, etc, in the same manner - they simply have three extra parameters. The class parameter may @@ -829,7 +826,8 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name) Note the 1 in the call to odr_bool(), to mark that the sequence member is optional. If either of the member types had been tagged, the macros - odr_implicit() or odr_explicit() + odr_implicit_tag() or + odr_explicit_tag() could have been used. The new function can be used exactly like the standard functions provided with &odr;. It will encode, decode or pretty-print a data value of the @@ -839,7 +837,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name) You could, of course, name your structures, types, and functions any way you please - as long as you're consistent, and your code is easily readable. odr_ok is just that - a predicate that returns the - state of the stream. It is used to ensure that the behaviour of the new + state of the stream. It is used to ensure that the behavior of the new type is compatible with the interface of the primitive types. @@ -877,7 +875,7 @@ int odr_implicit_settag(ODR o, int class, int tag); which overrides the tag of the type immediately following it. The - macro odr_implicit() works by calling + macro odr_implicit_tag() works by calling odr_implicit_settag() immediately before calling the function pointer argument. Your type function could look like this: @@ -926,10 +924,10 @@ MySequence ::= [10] IMPLICIT SEQUENCE { - int odr_constructed_begin(ODR o, void *p, int class, int tag, - const char *name); +int odr_constructed_begin(ODR o, void *p, int class, int tag, + const char *name); - int odr_constructed_end(ODR o); +int odr_constructed_end(ODR o); @@ -963,11 +961,11 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name) Notice that the interface here gets kind of nasty. The reason is simple: Explicitly tagged, constructed types are fairly rare in the protocols that we care about, so the - aesthetic annoyance (not to mention the dangers of a cluttered + esthetic annoyance (not to mention the dangers of a cluttered interface) is less than the time that would be required to develop a better interface. Nevertheless, it is far from satisfying, and it's a point that will be worked on in the future. One option for you would - be to simply apply the odr_explicit() macro to + be to simply apply the odr_explicit_tag() macro to the first function, and not have to worry about odr_constructed_* yourself. Incidentally, as you might have guessed, the @@ -980,7 +978,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name) SEQUENCE OF - To handle sequences (arrays) of a apecific type, the function + To handle sequences (arrays) of a specific type, the function @@ -1045,8 +1043,8 @@ int myArray(ODR o, MyArray **p, int optional, const char *name) - int odr_choice(ODR o, Odr_arm arm[], void *p, void *whichp, - const char *name); +int odr_choice(ODR o, Odr_arm arm[], void *p, void *whichp, + const char *name); @@ -1173,10 +1171,9 @@ int myChoice(ODR o, MyChoice **p, int optional, const char *name) In some cases (say, a non-optional choice which is a member of a sequence), you can "embed" the union and its discriminator in the -structure - belonging to the enclosing type, and you won't need to fiddle with - memory allocation to create a separate structure to wrap the - discriminator and union. + structure belonging to the enclosing type, and you won't need to + fiddle with memory allocation to create a separate structure to + wrap the discriminator and union. @@ -1186,7 +1183,7 @@ structure - The ASN.1 specifictions naturally requires that each member of a + The ASN.1 specifications naturally requires that each member of a CHOICE have a distinct tag, so they can be told apart on decoding. Sometimes it can be useful to define a CHOICE that has multiple types that share the same tag. You'll need some other mechanism, perhaps @@ -1199,7 +1196,7 @@ structure - void odr_choice_bias(ODR o, int what); +void odr_choice_bias(ODR o, int what); @@ -1220,7 +1217,7 @@ structure - Debugging + Debugging The protocol modules are suffering somewhat from a lack of diagnostic @@ -1245,7 +1242,7 @@ structure 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: -->