From 43cc841d9cd8606d5abc780770985ae5d6214560 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Wed, 23 Oct 2002 21:23:29 +0000 Subject: [PATCH] YAZ++ API description --- doc/Makefile.am | 7 +- doc/api.xml | 363 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/installation.xml | 36 ++++- doc/yaz++.xml.in | 4 +- 4 files changed, 405 insertions(+), 5 deletions(-) create mode 100644 doc/api.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index f45eee0..54bd396 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -## $Id: Makefile.am,v 1.4 2002-10-23 12:46:07 adam Exp $ +## $Id: Makefile.am,v 1.5 2002-10-23 21:23:29 adam Exp $ docdir=$(datadir)/doc/@PACKAGE@ SUPPORTFILES = \ @@ -10,6 +10,7 @@ XMLFILES = \ installation.xml \ zoom.xml \ proxy.xml \ + api.xml \ yaz-proxy-ref.xml \ yaz-proxy-man.sgml \ license.xml \ @@ -17,11 +18,11 @@ XMLFILES = \ TOP=yaz++.xml MANFILES=yaz-proxy.8 -HTMLFILES = installation.html license.html otherinfo-encoding.html \ +HTMLFILES = api.html installation.html license.html otherinfo-encoding.html \ proxy-cache.html proxy.html proxy-keepalive.html proxy-optimizations.html \ proxy-target.html proxy-usage.html yazpp.html yaz-proxy.html \ zoom-connection.html zoom-exception.html zoom.html zoom-query.html \ - zoom-record.html zoom-resultset.html + zoom-record.html zoom-resultset.html windows.html implementations.html doc_DATA = $(HTMLFILES) yaz++.pdf diff --git a/doc/api.xml b/doc/api.xml new file mode 100644 index 0000000..e3b92b0 --- /dev/null +++ b/doc/api.xml @@ -0,0 +1,363 @@ + + + YAZ C++ API + + The YAZ C++ API is an client - and server API that exposes + all YAZ features. The API doesn't hide YAZ C datastructures, but + provides a set of useful high-level objects for creating clients - + and servers. + + + The following sections include a short description of the + interfaces and implementations (concrete classes). + + + In order to understand the structure, you should look at the + example client yaz-my-client.cpp and + the example server yaz-my-server.cpp. + If that is too easy, you can always turn to the implementation + of the proxy itself and send us a patch if you implement a new + useful feature. + + + + The documentation here is very limited. We plan to enhance it + provided there is interest for it. + + +
Interfaces +
IYazSocketObservable + + This interface is capable of observing sockets. + When a socket even occurs it invokes an object implementing the + IYazSocketObserver + interface. + + + #include <yaz++/socket-observer.h> + + class my_socketobservable : public IYazSocketObservable { + // Add an observer interested in socket fd + virtual void addObserver(int fd, IYazSocketObserver *observer) = 0; + // Delete an observer + virtual void deleteObserver(IYazSocketObserver *observer) = 0; + // Delete all observers + virtual void deleteObservers() = 0; + // Specify the events that the observer is intersted in. + virtual void maskObserver(IYazSocketObserver *observer, + int mask) = 0; + // Specify timeout + virtual void timeoutObserver(IYazSocketObserver *observer, + unsigned timeout)=0; + }; + +
+
IYazZSocketObserver + + This interface is interested in socket events supporting + the IYazSocketObservable + interface. + + + #include <yaz++/socket-observer.h> + + class my_socketobserver : public IYazSocketObserver { + public: + // Notify the observer that something happened to socket + virtual void socketNotify(int event) = 0; + } + +
+
IYaz_PDU_Observable + + This interface is is responsible for sending - and receiving PDUs over + the network (YAZ COMSTACK). When events occur, an instance + implementing IYaz_PDU_Observer + is notified. + + + #include <yaz++/pdu-observer.h> + + class my_pduobservable : public IYaz_PDU_Observable { + public: + // Send encoded PDU buffer of specified length + virtual int send_PDU(const char *buf, int len) = 0; + // Connect with server specified by addr. + virtual void connect(IYaz_PDU_Observer *observer, + const char *addr) = 0; + // Listen on address addr. + virtual void listen(IYaz_PDU_Observer *observer, const char *addr)=0; + // Close connection + virtual void close() = 0; + // Make clone of this object using this interface + virtual IYaz_PDU_Observable *clone() = 0; + // Destroy completely + virtual void destroy() = 0; + // Set Idle Time + virtual void idleTime (int timeout) = 0; + }; + +
+
IYaz_PDU_Observer + + This interface is interested in PDUs and using an object implementing + IYaz_PDU_Observable. + + + #include <yaz++/pdu-observer.h> + + class my_pduobserver : public IYaz_PDU_Observer { + public: + // A PDU has been received + virtual void recv_PDU(const char *buf, int len) = 0; + // Called when Iyaz_PDU_Observable::connect was successful. + virtual void connectNotify() = 0; + // Called whenever the connection was closed + virtual void failNotify() = 0; + // Called whenever there is a timeout + virtual void timeoutNotify() = 0; + // Make clone of observer using IYaz_PDU_Observable interface + virtual IYaz_PDU_Observer *sessionNotify( + IYaz_PDU_Observable *the_PDU_Observable, int fd) = 0; + }; + +
+
Yaz_Query + + Abstract query. + + + #include <yaz++/query.h> + class my_query : public Yaz_Query { + public: + // Print query in buffer described by str and len + virtual void print (char *str, int len) = 0; + }; + +
+
+ +
Implementations +
Yaz_SocketManager + + This class implements the + IYazSocketObservable interface and is a portable + socket wrapper around the select call. + This implementation is useful for daemons, + command line clients, etc. + + + #include <yaz++/socket-manager.h> + + class Yaz_SocketManager : public IYazSocketObservable { + public: + // Add an observer + virtual void addObserver(int fd, IYazSocketObserver *observer); + // Delete an observer + virtual void deleteObserver(IYazSocketObserver *observer); + // Delete all observers + virtual void deleteObservers(); + // Set event mask for observer + virtual void maskObserver(IYazSocketObserver *observer, int mask); + // Set timeout + virtual void timeoutObserver(IYazSocketObserver *observer, + unsigned timeout); + // Process one event. return > 0 if event could be processed; + int processEvent(); + Yaz_SocketManager(); + virtual ~Yaz_SocketManager(); + }; + +
+
Yaz_PDU_Assoc + + This class implements the interfaces + IYaz_PDU_Observable + and + IYazSocketObserver. + This object implements a non-blocking client/server channel + that transmits BER encoded PDUs (or those offered by YAZ COMSTACK). + + + #include <yaz++/pdu-assoc.h> + + class Yaz_PDU_Assoc : public IYaz_PDU_Observable, + IYazSocketObserver { + + public: + COMSTACK comstack(const char *type_and_host, void **vp); + // Create object using specified socketObservable + Yaz_PDU_Assoc(IYazSocketObservable *socketObservable); + // Create Object using existing comstack + Yaz_PDU_Assoc(IYazSocketObservable *socketObservable, + COMSTACK cs); + // Close socket and destroy object. + virtual ~Yaz_PDU_Assoc(); + // Clone the object + IYaz_PDU_Observable *clone(); + // Send PDU + int send_PDU(const char *buf, int len); + // connect to server (client role) + void connect(IYaz_PDU_Observer *observer, const char *addr); + // listen for clients (server role) + void listen(IYaz_PDU_Observer *observer, const char *addr); + // Socket notification + void socketNotify(int event); + // Close socket + void close(); + // Close and destroy + void destroy(); + // Set Idle Time + void idleTime (int timeout); + // Child start... + virtual void childNotify(COMSTACK cs); + }; + +
+ +
Yaz_Z_Assoc + + This class implements the interface + IYaz_PDU_Obserer. + This object implements a Z39.50 client/server channel AKA + Z-Association. + + + #include <yaz++/z-assoc.h> + + class Yaz_Z_Assoc : public IYaz_PDU_Observer { + public: + // Create object using the PDU Observer specified + Yaz_Z_Assoc(IYaz_PDU_Observable *the_PDU_Observable); + // Destroy assocation and close PDU Observer + virtual ~Yaz_Z_Assoc(); + // Receive PDU + void recv_PDU(const char *buf, int len); + // Connect notification + virtual void connectNotify() = 0; + // Failure notification + virtual void failNotify() = 0; + // Timeout notification + virtual void timeoutNotify() = 0; + // Timeout specify + void timeout(int timeout); + // Begin Z39.50 client role + void client(const char *addr); + // Begin Z39.50 server role + void server(const char *addr); + // Close connection + void close(); + + // Decode Z39.50 PDU. + Z_APDU *decode_Z_PDU(const char *buf, int len); + // Encode Z39.50 PDU. + int encode_Z_PDU(Z_APDU *apdu, char **buf, int *len); + // Send Z39.50 PDU + int send_Z_PDU(Z_APDU *apdu); + // Receive Z39.50 PDU + virtual void recv_Z_PDU(Z_APDU *apdu) = 0; + // Create Z39.50 PDU with reasonable defaults + Z_APDU *create_Z_PDU(int type); + // Request Alloc + ODR odr_encode (); + ODR odr_decode (); + ODR odr_print (); + void set_APDU_log(const char *fname); + const char *get_APDU_log(); + + // OtherInformation + void get_otherInfoAPDU(Z_APDU *apdu, Z_OtherInformation ***oip); + Z_OtherInformationUnit *update_otherInformation ( + Z_OtherInformation **otherInformationP, int createFlag, + int *oid, int categoryValue, int deleteFlag); + void set_otherInformationString ( + Z_OtherInformation **otherInformationP, + int *oid, int categoryValue, + const char *str); + void set_otherInformationString ( + Z_OtherInformation **otherInformation, + int oidval, int categoryValue, + const char *str); + void set_otherInformationString ( + Z_APDU *apdu, + int oidval, int categoryValue, + const char *str); + + Z_ReferenceId *getRefID(char* str); + Z_ReferenceId **get_referenceIdP(Z_APDU *apdu); + void transfer_referenceId(Z_APDU *from, Z_APDU *to); + + const char *get_hostname(); + }; + +
+
Yaz_IR_Assoc + + This object is just a specialization of + Yaz_Z_Assoc and provides + more facilities for the Z39.50 client role. + + + #include <yaz++/ir-assoc.h> + + class Yaz_IR_Assoc : public Yaz_Z_Assoc { + ... + }; + + + The example client, yaz-my-client.cpp, + uses this class. + +
+
Yaz_Z_Server + + This object is just a specialization of + Yaz_Z_Assoc and provides + more facilities for the Z39.50 server role. + + + #include <yaz++/z-server.h> + + class Yaz_Z_Server : public Yaz_Z_Server { + ... + }; + + + The example server, yaz-my-server.cpp, + uses this class. + +
+
Yaz_Proxy + + This object is a specialization of + Yaz_Z_Assoc and implements + the YAZ proxy. + + + #include <yaz++/proxy.h> + + class Yaz_Proxy : public Yaz_Z_Server { + ... + }; + + + The proxy server, yaz-proxy-main.cpp, + uses this class. + +
+
+ + diff --git a/doc/installation.xml b/doc/installation.xml index 831c310..113d6e5 100644 --- a/doc/installation.xml +++ b/doc/installation.xml @@ -1,5 +1,5 @@ - + Installation You need a C++ compiler to compile and use YAZ++. @@ -126,6 +126,40 @@ +
+ Building on Windows + + You'll find Visual Studio project files in sub directory + win. Open workspace yazxx.dsw + which includes the following projects: + + + yazxx.dsp + + Builds the yazxx.dll. + + + + yazclient.dsp + + Builds the sample client yazmyclient.exe. + + + + yazserver.dsp + + Builds the sample server yazmyserver.exe. + + + + yazserver.dsp + + Builds the proxy yazproxy.exe. + + + + +
+ YAZ++ @@ -34,6 +35,7 @@ &chap-installation; &chap-zoom; &chap-proxy; + &chap-api; &app-license; -- 1.7.10.4