doc/api.xml

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