doc/api.xml

   1 <chapter id="api">
   2   <!-- $Id -->
   3   <title>YAZ C++ API</title>
   4   <para>
   5    The YAZ C++ API is an client - and server API that exposes
   6    all YAZ features. The API doesn't hide YAZ C datastructures, but
   7    provides a set of useful high-level objects for creating clients -
   8    and servers.
   9   </para>
  10   <para>
  11    The following sections include a short description of the
  12    interfaces and implementations (concrete classes).
  13   </para>
  14   <para>
  15    In order to understand the structure, you should look at the
  16    example client <filename>yaz-my-client.cpp</filename> and
  17    the example server <filename>yaz-my-server.cpp</filename>.
  18    If that is too easy, you can always turn to the implementation
  19    of the proxy itself and send us a patch if you implement a new
  20    useful feature.
  21   </para>
  22   <note>
  23    <para>
  24     The documentation here is very limited. We plan to enhance it
  25     provided there is interest for it.
  26    </para>
  27   </note>
  28   <section id="interfaces"><title>Interfaces</title>
  29    <section id="IYazSocketObservable"><title>IYazSocketObservable</title>
  30     <para>
  31      This interface is capable of observing sockets.
  32      When a socket even occurs it invokes an object implementing the
  33      <link linkend="IYazSocketObserver">IYazSocketObserver</link>
  34      interface.
  35     </para>
  36     <synopsis>
  37      #include &lt;yaz++/socket-observer.h>
  38
  39      class my_socketobservable : public IYazSocketObservable {
  40         // Add an observer interested in socket fd
  41         virtual void addObserver(int fd, IYazSocketObserver *observer) = 0;
  42         // Delete an observer
  43         virtual void deleteObserver(IYazSocketObserver *observer) = 0;
  44         // Delete all observers
  45         virtual void deleteObservers() = 0;
  46         // Specify the events that the observer is intersted in.
  47         virtual void maskObserver(IYazSocketObserver *observer,
  48                                   int mask) = 0;
  49         // Specify timeout
  50         virtual void timeoutObserver(IYazSocketObserver *observer,
  51                                      unsigned timeout)=0;
  52      };
  53     </synopsis>
  54    </section>
  55    <section id="IYazSocketObserver"><title>IYazZSocketObserver</title>
  56     <para>
  57      This interface is interested in socket events supporting
  58      the <link linkend="IYazSocketObservable">IYazSocketObservable</link>
  59      interface.
  60     </para>
  61     <synopsis>
  62      #include &lt;yaz++/socket-observer.h>
  63
  64      class my_socketobserver : public IYazSocketObserver {
  65          public:
  66           // Notify the observer that something happened to socket
  67           virtual void socketNotify(int event) = 0;
  68      }
  69     </synopsis>
  70    </section>
  71    <section id="IYaz_PDU_Observable"><title>IYaz_PDU_Observable</title>
  72     <para>
  73      This interface is is responsible for sending - and receiving PDUs over
  74      the network (YAZ COMSTACK). When events occur, an instance
  75      implementing <link linkend="IYaz_PDU_Observer">IYaz_PDU_Observer</link>
  76      is notified.
  77     </para>
  78     <synopsis>
  79      #include &lt;yaz++/pdu-observer.h>
  80
  81      class my_pduobservable : public IYaz_PDU_Observable {
  82        public:
  83          // Send encoded PDU buffer of specified length
  84          virtual int send_PDU(const char *buf, int len) = 0;
  85          // Connect with server specified by addr.
  86          virtual void connect(IYaz_PDU_Observer *observer,
  87                      const char *addr) = 0;
  88          // Listen on address addr.
  89          virtual void listen(IYaz_PDU_Observer *observer, const char *addr)=0;
  90          // Close connection
  91          virtual void close() = 0;
  92          // Make clone of this object using this interface
  93          virtual IYaz_PDU_Observable *clone() = 0;
  94          // Destroy completely
  95          virtual void destroy() = 0;
  96          // Set Idle Time
  97          virtual void idleTime (int timeout) = 0;
  98      };
  99     </synopsis>
 100    </section>
 101    <section id="IYaz_PDU_Observer"><title>IYaz_PDU_Observer</title>
 102     <para>
 103      This interface is interested in PDUs and using an object implementing
 104      <link linkend="IYaz_PDU_Observable">IYaz_PDU_Observable</link>.
 105     </para>
 106     <synopsis>
 107      #include &lt;yaz++/pdu-observer.h>
 108
 109      class my_pduobserver : public IYaz_PDU_Observer {
 110        public:
 111          // A PDU has been received
 112          virtual void recv_PDU(const char *buf, int len) = 0;
 113          // Called when Iyaz_PDU_Observable::connect was successful.
 114          virtual void connectNotify() = 0;
 115          // Called whenever the connection was closed
 116          virtual void failNotify() = 0;
 117          // Called whenever there is a timeout
 118          virtual void timeoutNotify() = 0;
 119          // Make clone of observer using IYaz_PDU_Observable interface
 120          virtual IYaz_PDU_Observer *sessionNotify(
 121          IYaz_PDU_Observable *the_PDU_Observable, int fd) = 0;
 122      };
 123     </synopsis>
 124    </section>
 125    <section id="query"><title>Yaz_Query</title>
 126     <para>
 127      Abstract query.
 128      </para>
 129     <synopsis>
 130      #include &lt;yaz++/query.h>
 131      class my_query : public Yaz_Query {
 132        public:
 133          // Print query in buffer described by str and len
 134          virtual void print (char *str, int len) = 0;
 135      };
 136     </synopsis>
 137    </section>
 138   </section>
 139
 140   <section id="implementations"><title>Implementations</title>
 141    <section><title>Yaz_SocketManager</title>
 142     <para>
 143      This class implements the <link linkend="IYazSocketObservable">
 144       IYazSocketObservable</link> interface and is a portable
 145      socket wrapper around the select call.
 146      This implementation is useful for daemons,
 147      command line clients, etc.
 148     </para>
 149     <synopsis>
 150      #include &lt;yaz++/socket-manager.h>
 151
 152      class Yaz_SocketManager : public IYazSocketObservable {
 153        public:
 154          // Add an observer
 155          virtual void addObserver(int fd, IYazSocketObserver *observer);
 156          // Delete an observer
 157          virtual void deleteObserver(IYazSocketObserver *observer);
 158          // Delete all observers
 159          virtual void deleteObservers();
 160          // Set event mask for observer
 161          virtual void maskObserver(IYazSocketObserver *observer, int mask);
 162          // Set timeout
 163          virtual void timeoutObserver(IYazSocketObserver *observer,
 164                                   unsigned timeout);
 165          // Process one event. return > 0 if event could be processed;
 166          int processEvent();
 167          Yaz_SocketManager();
 168          virtual ~Yaz_SocketManager();
 169      };
 170     </synopsis>
 171    </section>
 172    <section><title>Yaz_PDU_Assoc</title>
 173     <para>
 174      This class implements the interfaces
 175      <link linkend="IYaz_PDU_Observable">IYaz_PDU_Observable</link>
 176      and
 177      <link linkend="IYazSocketObserver">IYazSocketObserver</link>.
 178      This object implements a non-blocking client/server channel
 179      that transmits BER encoded PDUs (or those offered by YAZ COMSTACK).
 180     </para>
 181     <synopsis>
 182      #include &lt;yaz++/pdu-assoc.h>
 183
 184      class Yaz_PDU_Assoc : public IYaz_PDU_Observable,
 185                                  IYazSocketObserver {
 186
 187        public:
 188          COMSTACK comstack(const char *type_and_host, void **vp);
 189          // Create object using specified socketObservable
 190          Yaz_PDU_Assoc(IYazSocketObservable *socketObservable);
 191          // Create Object using existing comstack
 192          Yaz_PDU_Assoc(IYazSocketObservable *socketObservable,
 193                   COMSTACK cs);
 194          // Close socket and destroy object.
 195          virtual ~Yaz_PDU_Assoc();
 196          // Clone the object
 197          IYaz_PDU_Observable *clone();
 198          // Send PDU
 199          int send_PDU(const char *buf, int len);
 200          // connect to server (client role)
 201          void connect(IYaz_PDU_Observer *observer, const char *addr);
 202          // listen for clients (server role)
 203          void listen(IYaz_PDU_Observer *observer, const char *addr);
 204          // Socket notification
 205          void socketNotify(int event);
 206          // Close socket
 207          void close();
 208          // Close and destroy
 209          void destroy();
 210          // Set Idle Time
 211          void idleTime (int timeout);
 212          // Child start...
 213          virtual void childNotify(COMSTACK cs);
 214      };
 215     </synopsis>
 216    </section>
 217
 218    <section id="Yaz_Z_Assoc"><title>Yaz_Z_Assoc</title>
 219     <para>
 220      This class implements the interface
 221      <link linkend="IYaz_PDU_Observer">IYaz_PDU_Obserer</link>.
 222      This object implements a Z39.50 client/server channel AKA
 223      Z-Association.
 224     </para>
 225     <synopsis>
 226      #include &lt;yaz++/z-assoc.h>
 227
 228      class Yaz_Z_Assoc : public IYaz_PDU_Observer {
 229        public:
 230          // Create object using the PDU Observer specified
 231          Yaz_Z_Assoc(IYaz_PDU_Observable *the_PDU_Observable);
 232          // Destroy assocation and close PDU Observer
 233          virtual ~Yaz_Z_Assoc();
 234          // Receive PDU
 235          void recv_PDU(const char *buf, int len);
 236          // Connect notification
 237          virtual void connectNotify() = 0;
 238          // Failure notification
 239          virtual void failNotify() = 0;
 240          // Timeout notification
 241          virtual void timeoutNotify() = 0;
 242          // Timeout specify
 243          void timeout(int timeout);
 244          // Begin Z39.50 client role
 245          void client(const char *addr);
 246          // Begin Z39.50 server role
 247          void server(const char *addr);
 248          // Close connection
 249          void close();
 250
 251          // Decode Z39.50 PDU.
 252          Z_APDU *decode_Z_PDU(const char *buf, int len);
 253          // Encode Z39.50 PDU.
 254          int encode_Z_PDU(Z_APDU *apdu, char **buf, int *len);
 255          // Send Z39.50 PDU
 256          int send_Z_PDU(Z_APDU *apdu);
 257          // Receive Z39.50 PDU
 258          virtual void recv_Z_PDU(Z_APDU *apdu) = 0;
 259          // Create Z39.50 PDU with reasonable defaults
 260          Z_APDU *create_Z_PDU(int type);
 261          // Request Alloc
 262          ODR odr_encode ();
 263          ODR odr_decode ();
 264          ODR odr_print ();
 265          void set_APDU_log(const char *fname);
 266          const char *get_APDU_log();
 267
 268          // OtherInformation
 269          void get_otherInfoAPDU(Z_APDU *apdu, Z_OtherInformation ***oip);
 270          Z_OtherInformationUnit *update_otherInformation (
 271                Z_OtherInformation **otherInformationP, int createFlag,
 272                int *oid, int categoryValue, int deleteFlag);
 273          void set_otherInformationString (
 274                Z_OtherInformation **otherInformationP,
 275                int *oid, int categoryValue,
 276                const char *str);
 277          void set_otherInformationString (
 278                Z_OtherInformation **otherInformation,
 279                int oidval, int categoryValue,
 280                const char *str);
 281          void set_otherInformationString (
 282                Z_APDU *apdu,
 283                int oidval, int categoryValue,
 284                const char *str);
 285
 286          Z_ReferenceId *getRefID(char* str);
 287          Z_ReferenceId **get_referenceIdP(Z_APDU *apdu);
 288          void transfer_referenceId(Z_APDU *from, Z_APDU *to);
 289
 290          const char *get_hostname();
 291      };
 292     </synopsis>
 293    </section>
 294    <section id="Yaz_IR_Assoc"><title>Yaz_IR_Assoc</title>
 295     <para>
 296      This object is just a specialization of
 297      <link linkend="Yaz_Z_Assoc">Yaz_Z_Assoc</link> and provides
 298      more facilities for the Z39.50 client role.
 299     </para>
 300     <synopsis>
 301      #include &lt;yaz++/ir-assoc.h>
 302
 303      class Yaz_IR_Assoc : public Yaz_Z_Assoc {
 304        ...
 305      };
 306     </synopsis>
 307     <para>
 308      The example client, <filename>yaz-my-client.cpp</filename>,
 309      uses this class.
 310     </para>
 311    </section>
 312    <section id="Yaz_Z_Server"><title>Yaz_Z_Server</title>
 313     <para>
 314      This object is just a specialization of
 315      <link linkend="Yaz_Z_Assoc">Yaz_Z_Assoc</link> and provides
 316      more facilities for the Z39.50 server role.
 317     </para>
 318     <synopsis>
 319      #include &lt;yaz++/z-server.h>
 320
 321      class Yaz_Z_Server : public Yaz_Z_Server {
 322        ...
 323      };
 324     </synopsis>
 325     <para>
 326      The example server, <filename>yaz-my-server.cpp</filename>,
 327      uses this class.
 328     </para>
 329    </section>
 330    <section id="Yaz_Proxy"><title>Yaz_Proxy</title>
 331     <para>
 332      This object is a specialization of
 333      <link linkend="Yaz_Z_Assoc">Yaz_Z_Assoc</link> and implements
 334      the YAZ proxy.
 335     </para>
 336     <synopsis>
 337      #include &lt;yaz++/proxy.h>
 338
 339      class Yaz_Proxy : public Yaz_Z_Server {
 340        ...
 341      };
 342     </synopsis>
 343     <para>
 344      The proxy server, <filename>yaz-proxy-main.cpp</filename>,
 345      uses this class.
 346     </para>
 347    </section>
 348   </section>
 349  </chapter>
 350  <!-- Keep this comment at the end of the file
 351  Local variables:
 352  mode: sgml
 353  sgml-omittag:t
 354  sgml-shorttag:t
 355  sgml-minimize-attributes:nil
 356  sgml-always-quote-attributes:t
 357  sgml-indent-step:1
 358  sgml-indent-data:t
 359  sgml-parent-document: "yaz++.xml"
 360  sgml-local-catalogs: nil
 361  sgml-namecase-general:t
 362  End:
 363  -->