X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fintroduction.xml;h=b8f136b85115085c4e20581a8568a79c9620a963;hb=f7471d960fb2671c714bdfcd74dae39ce8112652;hp=470344ba3d1d316ab0d5f2a892120a32fbaa69bd;hpb=33c05384cfbca55da4ff97e5b2047b16596c72f7;p=yaz-moved-to-github.git diff --git a/doc/introduction.xml b/doc/introduction.xml index 470344b..b8f136b 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,17 +1,34 @@ - + 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: + The &yaz; + toolkit offers several different levels of access to the + ISO23950/Z39.50 + and ILL protocols. + The level that you need to use depends on your requirements, and + the role (server or client) that you want to implement. + If you're developing a client application you should consider the + ZOOM API. + It is, by far, the easiest way to develop clients in C. + Server implementers should consider the + generic frontend server. + None of those high-level APIs support the whole protocol, but + they do include most facilities used in existing Z39.50 + applications. + + + If you're using 'exotic' functionality (meaning anything not included in + the high-level APIs), developing non-standard extensions to Z39.50 or you're + going to develop an ILL application you'll have to learn the lower + level APIs of &yaz;. + + + The basic low level modules, which are independent of the role (client or server), + consist of three primary interfaces: - &asn;, which provides a C representation of the Z39.50/SR + &asn;, which provides a C representation of the Z39.50 protocol packages (PDUs). &odr;, which encodes and decodes the packages according @@ -23,7 +40,7 @@ The &asn; module represents the ASN.1 definition of - the SR/Z39.50 protocol. It establishes a set of type and + the 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 @@ -31,7 +48,7 @@ provided by the &odr; (Open Data Representation) subsystem. - &odr; is a basic mechanism for representing an + &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 @@ -68,14 +85,14 @@ (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 remainder of the connection's lifetime, you don't have + use (TCP/IP or SSL). + For the remainder 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 + level API. It's the API that most closely models the Z39.50 service/protocol definition, and it provides unlimited access to all fields and facilities of the protocol definitions.