X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fintroduction.xml;h=3ef6a0bf10baf07aa467aad10e979f7df61d797e;hb=ac5f8ad9508f5b3ada38117b0da7ae23c650ab1e;hp=5222a2d7fae5c968f60afa9961e56a34a55e3893;hpb=3b3deb4d093d747360a5eb0e02c6b4e9c8a89b84;p=yaz-moved-to-github.git diff --git a/doc/introduction.xml b/doc/introduction.xml index 5222a2d..3ef6a0b 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,17 +1,34 @@ - - 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: + 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 @@ -39,16 +56,21 @@ 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 + the actual definition in either z-core.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 + 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 - - int z_xxx(ODR o, Z_xxx **p, int optional, const char *name); - + + int z_xxx + ODR o + Z_xxx **p + int optional + const char *name + + (note the lower-case "z" in the function name) @@ -68,14 +90,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, SSL or UNIX sockets). + 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. @@ -87,8 +109,8 @@ can use SNACC or BERUtils instead, and still have the benefits of the transparent transport approach of the &comstack; module. Secondly, we realize 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;. + event-processing structure, in a way that is incompatible with + the &comstack; interface or some other part of &yaz;. @@ -102,7 +124,7 @@ 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: -->