X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fodr.xml;h=9a7e8c6a8935568067ec6474199b12891308141d;hb=ae3d95927f9d9d0a02a271ee6bdce89b26b3ff4e;hp=9a8e4060f7eee84561772b678e19038cb2eea800;hpb=bd7e251dac1b07c54884d26295f66b90cfb23131;p=yaz-moved-to-github.git diff --git a/doc/odr.xml b/doc/odr.xml index 9a8e406..9a7e8c6 100644 --- a/doc/odr.xml +++ b/doc/odr.xml @@ -1,4 +1,4 @@ - + The ODR Module Introduction @@ -132,7 +132,7 @@ 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 maintaining short-lived constructions such @@ -259,16 +259,14 @@ data you wish to decode (eg, odr_integer() odr z_APDU()). - - - Examples of encoding/decoding functions: - - - - int odr_integer(ODR o, int **p, int optional, const char *name); - - int z_APDU(ODR o, Z_APDU **p, int optional, const char *name); - + + Encoding and decoding functions + + int odr_integer(ODR o, int **p, int optional, const char *name); + + int z_APDU(ODR o, Z_APDU **p, int optional, const char *name); + + If the data is absent (or doesn't match the tag corresponding to @@ -300,16 +298,15 @@ last call to odr_reset() will be released. - - The use of the double indirection can be a little confusing at first - (its purpose will become clear later on, hopefully), - so an example is in order. We'll encode an integer value, and - immediately decode it again using a different stream. A useless, but - informative operation. - - - - + 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), + so an example is in order. We'll encode an integer value, and + immediately decode it again using a different stream. A useless, but + informative operation. + + - - - This looks like a lot of work, offhand. In practice, the &odr; streams - will typically be allocated once, in the beginning of your program - (or at the beginning of a new network session), and the encoding - and decoding will only take place in a few, isolated places in your - program, so the overhead is quite manageable. - - +]]> + + + This looks like a lot of work, offhand. In practice, the &odr; streams + will typically be allocated once, in the beginning of your program + (or at the beginning of a new network session), and the encoding + and decoding will only take place in a few, isolated places in your + program, so the overhead is quite manageable. + + + Diagnostics @@ -488,9 +486,18 @@ void do_nothing_useful(int value) other external forms. + + + There is an ASN.1 tutorial available at + this site. + This site also has standards for ASN.1 (X.680) and BER (X.690) + online. + + + - The interface is based loosely on that of the Sun Microsystems XDR - routines. + The ODR 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 @@ -502,7 +509,7 @@ void do_nothing_useful(int value) 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. @@ -525,13 +532,13 @@ void do_nothing_useful(int value) -int odr_integer(ODR o, int **p, int optional, const char *name); + int odr_integer(ODR o, int **p, int optional, const char *name); (we don't allow values that can't be contained in a C 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; @@ -679,7 +686,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 @@ -744,8 +751,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 @@ -826,7 +833,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 @@ -874,7 +882,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: @@ -964,7 +972,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name) 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