X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fodr.xml;h=3ae89c5e68ffc85310ac303cb1389167df768a1f;hb=4fb9818b0657f561397b29e55d87cc8d4f194436;hp=820fa2616e5ee886104f219e8a0ce376d8c94922;hpb=6ba14eb5dc7229aa17977882024a475b6d258368;p=yaz-moved-to-github.git diff --git a/doc/odr.xml b/doc/odr.xml index 820fa26..3ae89c5 100644 --- a/doc/odr.xml +++ b/doc/odr.xml @@ -1,4 +1,4 @@ - + The ODR Module Introduction @@ -13,8 +13,8 @@ If you are only interested in writing a Z39.50 implementation based on the PDUs that are already provided with &yaz;, you only need to concern - yourself with the section on managing ODR streams (section - Using ODR). Only if you need to + yourself with the section on managing ODR streams + (). Only if you need to implement ASN.1 beyond that which has been provided, should you worry about the second half of the documentation (section Programming with ODR). @@ -37,7 +37,7 @@ - Using ODR + Using ODR ODR Streams @@ -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; @@ -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