From adae7ab7df270a3187630876b8d4668038a42e88 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Sun, 23 Feb 2003 14:25:34 +0000 Subject: [PATCH] Revised introduction. Added figure with YAZ module layers. --- doc/Makefile.am | 11 ++-- doc/apilayer.obj | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/apilayer.png | Bin 0 -> 1021 bytes doc/introduction.xml | 71 +++++++++++++++++------- 4 files changed, 207 insertions(+), 22 deletions(-) create mode 100644 doc/apilayer.obj create mode 100644 doc/apilayer.png diff --git a/doc/Makefile.am b/doc/Makefile.am index 04339cd..d89c719 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -## $Id: Makefile.am,v 1.40 2003-02-21 12:20:22 adam Exp $ +## $Id: Makefile.am,v 1.41 2003-02-23 14:25:34 adam Exp $ docdir=$(datadir)/doc/@PACKAGE@ @@ -28,9 +28,10 @@ MANFILES=yaz-client.1 yaz-client-ssl.1 yaz-ztest.8 \ REFFILES=yaz-client.sgml yaz-ztest.sgml yaz-config.sgml \ yaz-man.sgml zoomsh.sgml -SUPPORTFILES=yazhtml.dsl yazphp.dsl yazprint.dsl tkl.xsl xml.dcl id.eps +SUPPORTFILES=yazhtml.dsl yazphp.dsl yazprint.dsl tkl.xsl xml.dcl id.eps \ + apilayer.obj -doc_DATA = $(HTMLFILES) yaz.pdf id.png +doc_DATA = $(HTMLFILES) yaz.pdf id.png apilayer.png EXTRA_DIST = $(XMLFILES) $(SUPPORTFILES) $(MANFILES) $(REFFILES) $(doc_DATA) @@ -75,3 +76,7 @@ yaz.pdf: $(XMLFILES) $(srcdir)/id.png index.tkl: $(XMLFILES) tkl.xsl xsltproc tkl.xsl yaz.xml +apilayer.png: + tgif -print -xbm apilayer.obj + xbmtopbm apilayer.png + diff --git a/doc/apilayer.obj b/doc/apilayer.obj new file mode 100644 index 0000000..a2e423f --- /dev/null +++ b/doc/apilayer.obj @@ -0,0 +1,147 @@ +%TGIF 4.1.42-QPL +state(1,37,100.000,0,0,0,16,1,9,0,0,0,0,3,0,1,0,'Helvetica',0,80640,0,0,1,5,0,0,1,1,0,16,0,0,1,1,1,0,1485,1050,0,0,2880,0). +% +% @(#)$Header: /home/cvsroot/yaz/doc/apilayer.obj,v 1.1 2003-02-23 14:25:34 adam Exp $ +% %W% +% +unit("1 pixel/pixel"). +color_info(19,65535,0,[ + "magenta", 65535, 0, 65535, 65535, 0, 65535, 1, + "red", 65535, 0, 0, 65535, 0, 0, 1, + "green", 0, 65535, 0, 0, 65535, 0, 1, + "blue", 0, 0, 65535, 0, 0, 65535, 1, + "yellow", 65535, 65535, 0, 65535, 65535, 0, 1, + "pink", 65535, 49931, 50971, 65535, 49344, 52171, 1, + "cyan", 0, 65535, 65535, 0, 65535, 65535, 1, + "CadetBlue", 22885, 40569, 40569, 24415, 40606, 41120, 1, + "white", 65535, 65535, 65535, 65535, 65535, 65535, 1, + "black", 0, 0, 0, 0, 0, 0, 1, + "DarkSlateGray", 10402, 19764, 18724, 12079, 20303, 20303, 1, + "#00000000c000", 0, 0, 48891, 0, 0, 49152, 1, + "#820782070000", 34327, 33287, 0, 33287, 33287, 0, 1, + "#3cf3fbee34d2", 14563, 64494, 14563, 15603, 64494, 13522, 1, + "#3cf3fbed34d3", 14563, 64494, 14563, 15603, 64493, 13523, 1, + "#ffffa6990000", 65535, 42649, 0, 65535, 42649, 0, 1, + "#ffff0000fffe", 65535, 0, 65535, 65535, 0, 65534, 1, + "#fffe0000fffe", 65535, 0, 65535, 65534, 0, 65534, 1, + "#fffe00000000", 65535, 0, 0, 65534, 0, 0, 1 +]). +script_frac("0.6"). +fg_bg_colors('black','white'). +dont_reencode("FFDingbests:ZapfDingbats"). +page(1,"",1,''). +text('black',95,51,2,0,1,159,34,6,14,3,0,0,0,0,2,159,34,0,0,"",0,0,0,0,65,'',[ +minilines(159,34,0,0,0,0,0,[ +mini_line(159,14,3,0,0,0,[ +str_block(0,159,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,159,14,3,0,-1,0,0,0,0,0, + "Client/Server Application")]) +]), +mini_line(0,14,3,0,0,0,[ +str_block(0,0,14,3,0,0,0,0,0,[ +str_seg('black','Helvetica',0,80640,0,14,3,0,0,0,0,0,0,0, + "")]) +]) +])]). +text('black',190,121,2,0,1,40,34,17,14,3,0,0,0,0,2,40,34,0,0,"",0,0,0,0,135,'',[ +minilines(40,34,0,0,0,0,0,[ +mini_line(33,14,3,0,0,0,[ +str_block(0,33,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,33,14,3,0,-1,0,0,0,0,0, + "SRW")]) +]), +mini_line(40,14,3,0,0,0,[ +str_block(0,40,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,40,14,3,0,-1,0,0,0,0,0, + "SOAP")]) +]) +])]). +text('black',120,121,2,0,1,44,34,21,14,3,0,0,0,0,2,44,34,0,0,"",0,0,0,0,135,'',[ +minilines(44,34,0,0,0,0,0,[ +mini_line(44,14,3,0,0,0,[ +str_block(0,44,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,44,14,3,0,-1,0,0,0,0,0, + "Z39.50")]) +]), +mini_line(41,14,3,0,0,0,[ +str_block(0,41,14,3,0,-3,0,0,0,[ +str_seg('black','Helvetica',0,80640,41,14,3,0,-3,0,0,0,0,0, + "ASN.1")]) +]) +])]). +text('black',190,186,1,0,1,37,17,25,14,3,0,0,0,0,2,37,17,0,0,"",0,0,0,0,200,'',[ +minilines(37,17,0,0,0,0,0,[ +mini_line(37,14,3,0,0,0,[ +str_block(0,37,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,37,14,3,0,-1,0,0,0,0,0, + "HTTP")]) +]) +])]). +text('black',240,266,1,0,1,26,17,53,14,3,0,0,0,0,2,26,17,0,0,"",0,0,0,0,280,'',[ +minilines(26,17,0,0,0,0,0,[ +mini_line(26,14,3,0,0,0,[ +str_block(0,26,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,26,14,3,0,-1,0,0,0,0,0, + "SSL")]) +]) +])]). +box('black','',35,230,305,255,0,1,1,197,0,0,0,0,0,'1',0,[ +]). +box('black','',175,180,305,215,0,1,1,198,0,0,0,0,0,'1',0,[ +]). +box('black','',175,115,240,165,0,1,1,200,0,0,0,0,0,'1',0,[ +]). +box('black','',100,115,170,165,0,1,1,203,0,0,0,0,0,'1',0,[ +]). +box('black','',205,255,305,290,0,1,1,214,0,0,0,0,0,'1',0,[ +]). +text('black',95,231,1,0,1,83,17,224,14,3,0,0,0,0,2,83,17,0,0,"",0,0,0,0,245,'',[ +minilines(83,17,0,0,0,0,0,[ +mini_line(83,14,3,0,0,0,[ +str_block(0,83,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,83,14,3,0,-1,0,0,0,0,0, + "COMSTACK")]) +]) +])]). +text('black',80,186,1,0,1,71,17,254,14,3,0,0,0,0,2,71,17,0,0,"",0,0,0,0,200,'',[ +minilines(71,17,0,0,0,0,0,[ +mini_line(71,14,3,0,0,0,[ +str_block(0,71,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,71,14,3,0,-1,0,0,0,0,0, + "ODR (BER)")]) +]) +])]). +box('black','',35,180,170,215,0,1,1,266,0,0,0,0,0,'1',0,[ +]). +box('black','',35,45,305,90,0,1,1,268,0,0,0,0,0,'1',0,[ +]). +box('black','',240,115,305,165,0,1,1,292,5,0,0,0,0,'1',0,[ +]). +text('black',255,121,2,0,1,29,34,293,14,3,0,0,0,0,2,29,34,0,0,"",0,0,0,0,135,'',[ +minilines(29,34,0,0,0,0,0,[ +mini_line(28,14,3,0,0,0,[ +str_block(0,28,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,28,14,3,0,-1,0,0,0,0,0, + "SRU")]) +]), +mini_line(29,14,3,0,0,0,[ +str_block(0,29,14,3,0,0,0,0,0,[ +str_seg('black','Helvetica',0,80640,29,14,3,0,0,0,0,0,0,0, + "GET")]) +]) +])]). +text('black',50,121,2,0,1,41,34,303,14,3,0,0,0,0,2,41,34,0,0,"",0,0,0,0,135,'',[ +minilines(41,34,0,0,0,0,0,[ +mini_line(21,14,3,0,0,0,[ +str_block(0,21,14,3,0,-1,0,0,0,[ +str_seg('black','Helvetica',0,80640,21,14,3,0,-1,0,0,0,0,0, + "ILL")]) +]), +mini_line(41,14,3,0,0,0,[ +str_block(0,41,14,3,0,-3,0,0,0,[ +str_seg('black','Helvetica',0,80640,41,14,3,0,-3,0,0,0,0,0, + "ASN.1")]) +]) +])]). +box('black','',35,115,100,165,0,1,1,305,0,0,0,0,0,'1',0,[ +]). diff --git a/doc/apilayer.png b/doc/apilayer.png new file mode 100644 index 0000000000000000000000000000000000000000..cde890ad01a81eed13aff7def4390152848570be GIT binary patch literal 1021 zcmV{(E*h5{ ze6i52P8ey&!5}vnX$(ttB4%f%^Jk??N!Z1by={FUEJ1i6B|}7S3MhrzNgRlY_E!&(SpM?+x1zDN)n0qB z{{x7V*T2@=;W62G!o7_Rwe#D{sGsEQA=}`wz)vL(0QSWtmAKiCe3~&Vy1QAP2x)VeM z)Uy>?!V-jwATY$QlZG^Xp*2hP?-!%)78c&<)`c}o#5(=uPR^GMgueHQA^5BX&6EN~ zdI}UN%&M;qIe$o~Av-OIb?bJ{DJiKl?E`Aly&%7nBTaT2C$OkbK!;us$RuYUNMJ|V zg~*IT88d{*A?f%LskAH^FxJrr8Y3YsTjF;N5jED)>9Ut|)K=7xtA+>`S|aPLLG)xW zxoGlS?(G^fCp=3Kdp=1TBqFR~iK@tq!bb!=S#4^<`3_!<`U1-O3OF043#v3CXO^h$ z8X^~G>7AS}A5T8T>nOurO}gTC-KTSMZIV72QeQfarqnQ!e_K8yviRd8)S?d$dV-C}vpC@#mSIg1Je2@NC{8_)BHzjC(n7(I z%L2rSbd#fitH@+731TX85Y-n4QQal5x^!S@eCur%)k|Mw}ClWUL+3z>Aq z?OK|1a&3|!fNPYSex+AD!gOnfssCqbBs_nFgH6H)O_D}9eb(wS@{aXz8eu}5{4L2l z%HcF}QX+lI7WiaI|sf@{6hqE%l!)ff0jGks+! z9(i<|z{WaDC8?2 + Introduction @@ -161,12 +161,13 @@ toolkit offers several different levels of access to the ISO23950/Z39.50, ILL and - SRW protocols. + SRW + 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. + 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 @@ -179,22 +180,54 @@ 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: - + + + + The YAZ toolkit modules is shown in figure . + +
+ YAZ layers + + + + + + + + +
+ + There are four layers. - &asn;, which provides a C representation of the Z39.50 - 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. - + + A client or server application (or both). + This layer includes ZOOM and the generic frontend server. + + + + + The second layer provides a C represenation of the + protocol units (packages) for Z39.50 ASN.1, ILL ASN.1, + SRW SOAP. + + + + + The third layer encodes and decodes protocol data units to + simple packages (buffer with certain length). The &odr; module + encodes and decodes BER whereas the HTTP modules encodes and + decodes HTTP ruquests/responses. + + + + + The lowest layer is &comstack; which exchanges the encoded packages + with a peer process over a network. + + - + + The &asn; module represents the ASN.1 definition of the Z39.50 protocol. It establishes a set of type and structure definitions, with one structure for each of the top-level @@ -248,7 +281,7 @@ create a connection endpoint, you need to specify what transport to 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; + to worry about the underlying transport protocol at all - the &comstack; will ensure that the correct mechanism is used. @@ -259,7 +292,7 @@ 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 + 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 -- 1.7.10.4