X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fintroduction.xml;h=785bc82a21c408e8dc53d0f91e77f8dbcc8e9706;hp=5cc082ea46e71879827bfa8fdeb88f5d122dc059;hb=ce853cc4919ab346fd629e7727905d3ee6e1129f;hpb=088c938eb8a4c6e4db96603e30b3558fd3d67580 diff --git a/doc/introduction.xml b/doc/introduction.xml index 5cc082e..785bc82 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,93 +1,108 @@ - -Introduction + + Introduction + + + The &yaz; toolkit offers several different levels of access to the + Z39.50 and SR protocols. The level that you need to use depends on + your requirements, and the role (server or client) that you + want to implement. + + The basic level, which is independent of the role, consists of three + primary interfaces: + + + &asn;, which provides a C representation of the Z39.50/SR + protocol packages (PDUs). + + &odr;, which encodes and decodes the packages according + to the BER specification. + + &comstack;, which exchanges the encoded packages with + a peer process over a network. + + + + The &asn; module represents the ASN.1 definition of + the SR/Z39.50 protocol. It establishes a set of type and + structure definitions, with one structure for each of the top-level + PDUs, and one structure or type for each of the contained ASN.1 types. + For primitive types, or other types that are defined by the ASN.1 + standard itself (such as the EXTERNAL type), the C representation is + provided by the &odr; (Open Data Representation) subsystem. + + + &odr; is a basic mechanism for representing an + ASN.1 type in the C programming language, and for implementing BER + encoders and decoders for values of that type. The types defined in + the &asn; module generally have the prefix Z_, and + a suffix corresponding to the name of the type in the ASN.1 + specification of the protocol (generally Z39.50-1995). In the case of + base types (those originating in the ASN.1 standard itself), the prefix + Odr_ is sometimes seen. Either way, look for + the actual definition in either proto.h (for the types + from the protocol), odr.h (for the primitive ASN.1 + types, or odr_use.h (for the ASN.1 + useful types). The &asn; library also + provides functions (which are, in turn, defined using &odr; + primitives) for encoding and decoding data values. Their general form is - -The &yaz; toolkit offers several different levels of access to the -Z39.50 and SR protocols. The level that you need to use depends on -your requirements, and the role (server or client) that you -want to implement. - -The basic level, which is independent of the role, consists of three -primary interfaces: + + int z_xxx(ODR o, Z_xxx **p, int optional, const char *name); + + (note the lower-case "z" in the function name) + - -&asn;, which provides a C representation of the Z39.50/SR -protocol packages (PDUs). - -&odr;, which encodes and decodes the packages according -to the BER specification. - -&comstack;, which exchanges the encoded packages with -a peer process over a network. - - + + + If you are using the premade definitions of the &asn; module, and you + are not adding new protocol of your own, the only parts of &odr; that you + need to worry about are documented in section + Using ODR. + + -The &asn; module represents the ASN.1 definition of -the SR/Z39.50 protocol. It establishes a set of type and -structure definitions, with one structure for each of the top-level -PDUs, and one structure or type for each of the contained ASN.1 types. -For primitive types, or other types that are defined by the ASN.1 -standard itself (such as the EXTERNAL type), the C representation is provided -by the &odr; (Open Data Representation) subsystem. - - -&odr; is a basic mechanism for representing an -ASN.1 type in the C programming language, and for implementing BER -encoders and decoders for values of that type. The types defined in -the &asn; module generally have the prefix Z_, and a suffix -corresponding to the name of the type in the ASN.1 -specification of the protocol (generally Z39.50-1995). In the case of -base types (those originating in the ASN.1 standard itself), the prefix -Odr_ is sometimes seen. Either way, look for -the actual definition in either proto.h (for the types -from the protocol), odr.h (for the primitive ASN.1 -types, or odr_use.h (for the ASN.1 -useful types). The &asn; library also -provides functions (which are, in turn, defined using &odr; -primitives) for encoding and decoding data values. Their general form is + + When you have created a BER-encoded buffer, you can use the &comstack; + subsystem to transmit (or receive) data over the network. The &comstack; + module provides simple functions for establishing a connection + (passively or actively, depending on the role of your application), + and for exchanging BER-encoded PDUs over that connection. When you + create a connection endpoint, you need to specify what transport to + use (OSI or TCP/IP), and which protocol you want to use (SR or + Z39.50). For the remainer of the connection's lifetime, you don't have + to worry about the underlying transport protocol at all - the &comstack; + will ensure that the correct mechanism is used. + + + We call the combined interfaces to &odr;, &asn;, and &comstack; the service + level API. It's the API that most closely models the Z39.50/SR + service/protocol definition, and it provides unlimited access to all + fields and facilities of the protocol definitions. + + + The reason that the &yaz; service-level API is a conglomerate of the + APIs from three different submodules is twofold. First, we wanted to allow + the user a choice of different options for each major task. For instance, + if you don't like the protocol API provided by &odr;/&asn;, you + can use SNACC or BERUtils instead, and still have the benefits of the + transparent transport approach of the &comstack; module. Secondly, + we realise that you may have to fit the toolkit into an existing + event-processing structure, in a way that + is incompatible with the &comstack; interface or some other part of &yaz;. + + - -int z_xxx(ODR o, Z_xxx **p, int optional, const char *name); - -(note the lower-case "z" in the function name) - - - - -If you are using the premade definitions of the &asn; module, and you -are not adding new protocol of your own, the only parts of &odr; that you -need to worry about are documented in section -Using ODR. - - - - -When you have created a BER-encoded buffer, you can use the &comstack; -subsystem to transmit (or receive) data over the network. The &comstack; -module provides simple functions for establishing a connection -(passively or actively, depending on the role of your application), -and for exchanging BER-encoded PDUs over that connection. When you -create a connection endpoint, you need to specify what transport to -use (OSI or TCP/IP), and which protocol you want to use (SR or -Z39.50). For the remainer of the connection's lifetime, you don't have -to worry about the underlying transport protocol at all - the &comstack; -will ensure that the correct mechanism is used. - - -We call the combined interfaces to &odr;, &asn;, and &comstack; the service -level API. It's the API that most closely models the Z39.50/SR -service/protocol definition, and it provides unlimited access to all -fields and facilities of the protocol definitions. - - -The reason that the &yaz; service-level API is a conglomerate of the -APIs from three different submodules is twofold. First, we wanted to allow the -user a choice of different options for each major task. For instance, -if you don't like the protocol API provided by &odr;/&asn;, you -can use SNACC or BERUtils instead, and still have the benefits of the -transparent transport approach of the &comstack; module. Secondly, -we realise that you may have to fit the toolkit into an existing -event-processing structure, in a way that -is incompatible with the &comstack; interface or some other part of &yaz;. - - \ No newline at end of file +