+++ /dev/null
-<chapter id="api">
- <title>YAZ C++ API</title>
- <para>
- The YAZ C++ API is an client - and server API that exposes
- all YAZ features. The API doesn't hide YAZ C data structures, but
- provides a set of useful high-level objects for creating clients -
- and servers.
- </para>
- <para>
- All definitions from YAZ++ are part of namespace
- <literal>yazpp_1</literal>.
- </para>
- <para>
- The following sections include a short description of the
- interfaces and implementations (concrete classes).
- </para>
- <para>
- In order to understand the structure, you should look at the
- example client <filename>yaz-my-client.cpp</filename> and
- the example server <filename>yaz-my-server.cpp</filename>.
- 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.
- </para>
- <note>
- <para>
- The documentation here is very limited. We plan to enhance it -
- provided there is interest for it.
- </para>
- </note>
- <section id="interfaces"><title>Interfaces</title>
- <section id="ISocketObservable"><title>ISocketObservable</title>
- <para>
- This interface is capable of observing sockets.
- When a socket even occurs it invokes an object implementing the
- <link linkend="ISocketObserver">ISocketObserver</link>
- interface.
- </para>
- <synopsis>
- #include <yazpp/socket-observer.h>
-
- class my_socketobservable : public ISocketObservable {
- // Add an observer interested in socket fd
- virtual void addObserver(int fd, ISocketObserver *observer) = 0;
- // Delete an observer
- virtual void deleteObserver(ISocketObserver *observer) = 0;
- // Delete all observers
- virtual void deleteObservers() = 0;
- // Specify the events that the observer is interested in.
- virtual void maskObserver(ISocketObserver *observer,
- int mask) = 0;
- // Specify timeout
- virtual void timeoutObserver(ISocketObserver *observer,
- int timeout)=0;
- };
- </synopsis>
- </section>
- <section id="ISocketObserver"><title>ISocketObserver</title>
- <para>
- This interface is interested in socket events supporting
- the <link linkend="ISocketObservable">ISocketObservable</link>
- interface.
- </para>
- <synopsis>
- #include <yazpp/socket-observer.h>
-
- class my_socketobserver : public ISocketObserver {
- public:
- // Notify the observer that something happened to socket
- virtual void socketNotify(int event) = 0;
- }
- </synopsis>
- </section>
- <section id="IPDU_Observable"><title>IPDU_Observable</title>
- <para>
- This interface is is responsible for sending - and receiving PDUs over
- the network (YAZ COMSTACK). When events occur, an instance
- implementing <link linkend="IPDU_Observer">IPDU_Observer</link>
- is notified.
- </para>
- <synopsis>
- #include <yazpp/pdu-observer.h>
-
- class my_pduobservable : public IPDU_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(IPDU_Observer *observer,
- const char *addr) = 0;
- // Listen on address addr.
- virtual void listen(IPDU_Observer *observer, const char *addr)=0;
- // Close connection
- virtual void close() = 0;
- // Make clone of this object using this interface
- virtual IPDU_Observable *clone() = 0;
- // Destroy completely
- virtual void destroy() = 0;
- // Set Idle Time
- virtual void idleTime (int timeout) = 0;
- // Get peername
- virtual const char *getpeername() = 0;
-
- virtual ~IPDU_Observable();
- };
- </synopsis>
- </section>
- <section id="IPDU_Observer"><title>IPDU_Observer</title>
- <para>
- This interface is interested in PDUs and using an object implementing
- <link linkend="IPDU_Observable">IPDU_Observable</link>.
- </para>
- <synopsis>
- #include <yazpp/pdu-observer.h>
-
- class my_pduobserver : public IPDU_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 IPDU_Observable interface
- virtual IPDU_Observer *sessionNotify(
- IPDU_Observable *the_PDU_Observable, int fd) = 0;
- };
- </synopsis>
- </section>
- <section id="query"><title>Yaz_Query</title>
- <para>
- Abstract query.
- </para>
- <synopsis>
- #include <yazpp/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;
- };
- </synopsis>
- </section>
- </section>
-
- <section id="implementations"><title>Implementations</title>
- <section id="Yaz_SocketManager"><title>Yaz_SocketManager</title>
- <para>
- This class implements the <link linkend="ISocketObservable">
- ISocketObservable</link> interface and is a portable
- socket wrapper around the select call.
- This implementation is useful for daemons,
- command line clients, etc.
- </para>
- <synopsis>
- #include <yazpp/socket-manager.h>
-
- class SocketManager : public ISocketObservable {
- public:
- // Add an observer
- virtual void addObserver(int fd, ISocketObserver *observer);
- // Delete an observer
- virtual void deleteObserver(ISocketObserver *observer);
- // Delete all observers
- virtual void deleteObservers();
- // Set event mask for observer
- virtual void maskObserver(ISocketObserver *observer, int mask);
- // Set timeout
- virtual void timeoutObserver(ISocketObserver *observer,
- unsigned timeout);
- // Process one event. return > 0 if event could be processed;
- int processEvent();
- SocketManager();
- virtual ~SocketManager();
- };
- </synopsis>
- </section>
- <section id="PDU_Assoc">
- <title>PDU_Assoc</title>
- <para>
- This class implements the interfaces
- <link linkend="IPDU_Observable">IPDU_Observable</link>
- and
- <link linkend="ISocketObserver">ISocketObserver</link>.
- This object implements a non-blocking client/server channel
- that transmits BER encoded PDUs (or those offered by YAZ COMSTACK).
- </para>
- <synopsis>
- #include <yazpp/pdu-assoc.h>
-
- class PDU_Assoc : public IPDU_Observable,
- ISocketObserver {
-
- public:
- COMSTACK comstack(const char *type_and_host, void **vp);
- // Create object using specified socketObservable
- PDU_Assoc(ISocketObservable *socketObservable);
- // Create Object using existing comstack
- PDU_Assoc(ISocketObservable *socketObservable,
- COMSTACK cs);
- // Close socket and destroy object.
- virtual ~PDU_Assoc();
- // Clone the object
- IPDU_Observable *clone();
- // Send PDU
- int send_PDU(const char *buf, int len);
- // connect to server (client role)
- void connect(IPDU_Observer *observer, const char *addr);
- // listen for clients (server role)
- void listen(IPDU_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);
- };
- </synopsis>
- </section>
-
- <section id="Z_Assoc"><title>Z_Assoc</title>
- <para>
- This class implements the interface
- <link linkend="IPDU_Observer">IPDU_Obserer</link>.
- This object implements a Z39.50 client/server channel AKA
- Z-Association.
- </para>
- <synopsis>
- #include <yazpp/z-assoc.h>
-
- class Z_Assoc : public IPDU_Observer {
- public:
- // Create object using the PDU Observer specified
- Z_Assoc(IPDU_Observable *the_PDU_Observable);
- // Destroy association and close PDU Observer
- virtual ~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();
- };
- </synopsis>
- </section>
- <section id="IR_Assoc"><title>IR_Assoc</title>
- <para>
- This object is just a specialization of
- <link linkend="Z_Assoc">Z_Assoc</link> and provides
- more facilities for the Z39.50 client role.
- </para>
- <synopsis>
- #include <yazpp/ir-assoc.h>
-
- class IR_Assoc : public Z_Assoc {
- ...
- };
- </synopsis>
- <para>
- The example client, <filename>yaz-my-client.cpp</filename>,
- uses this class.
- </para>
- </section>
- <section id="Z_Server"><title>Z_Server</title>
- <para>
- This object is just a specialization of
- <link linkend="Z_Assoc">Z_Assoc</link> and provides
- more facilities for the Z39.50 server role.
- </para>
- <synopsis>
- #include <yazpp/z-server.h>
-
- class My_Server : public Z_Server {
- ...
- };
- </synopsis>
- <para>
- The example server, <filename>yaz-my-server.cpp</filename>,
- uses this class.
- </para>
- </section>
- </section>
- </chapter>
- <!-- Keep this comment at the end of the file
- Local variables:
- mode: sgml
- sgml-omittag:t
- sgml-shorttag:t
- sgml-minimize-attributes:nil
- sgml-always-quote-attributes:t
- sgml-indent-step:1
- sgml-indent-data:t
- sgml-parent-document: "yazpp.xml"
- sgml-local-catalogs: nil
- sgml-namecase-general:t
- End:
- -->
projects / yazpp-moved-to-github.git / blobdiff