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 data structures, but
   7    provides a set of useful high-level objects for creating clients -
   8    and servers.
   9   </para>
  10   <para>
  11    All definitions from YAZ++ are part of namespace
  12    <literal>yazpp_1</literal>.
  13   </para>
  14   <para>
  15    The following sections include a short description of the
  16    interfaces and implementations (concrete classes).
  17   </para>
  18   <para>
  19    In order to understand the structure, you should look at the
  20    example client <filename>yaz-my-client.cpp</filename> and
  21    the example server <filename>yaz-my-server.cpp</filename>.
  22    If that is too easy, you can always turn to the implementation
  23    of the proxy itself and send us a patch if you implement a new
  24    useful feature.
  25   </para>
  26   <note>
  27    <para>
  28     The documentation here is very limited. We plan to enhance it -
  29     provided there is interest for it.
  30    </para>
  31   </note>
  32   <section id="interfaces"><title>Interfaces</title>
  33    <section id="ISocketObservable"><title>ISocketObservable</title>
  34     <para>
  35      This interface is capable of observing sockets.
  36      When a socket even occurs it invokes an object implementing the
  37      <link linkend="ISocketObserver">ISocketObserver</link>
  38      interface.
  39     </para>
  40     <synopsis>
  41      #include &lt;yazpp/socket-observer.h>
  42
  43      class my_socketobservable : public ISocketObservable {
  44         // Add an observer interested in socket fd
  45         virtual void addObserver(int fd, ISocketObserver *observer) = 0;
  46         // Delete an observer
  47         virtual void deleteObserver(ISocketObserver *observer) = 0;
  48         // Delete all observers
  49         virtual void deleteObservers() = 0;
  50         // Specify the events that the observer is interested in.
  51         virtual void maskObserver(ISocketObserver *observer,
  52                                   int mask) = 0;
  53         // Specify timeout
  54         virtual void timeoutObserver(ISocketObserver *observer,
  55                                      int timeout)=0;
  56      };
  57     </synopsis>
  58    </section>
  59    <section id="ISocketObserver"><title>ISocketObserver</title>
  60     <para>
  61      This interface is interested in socket events supporting
  62      the <link linkend="ISocketObservable">ISocketObservable</link>
  63      interface.
  64     </para>
  65     <synopsis>
  66      #include &lt;yazpp/socket-observer.h>
  67
  68      class my_socketobserver : public ISocketObserver {
  69          public:
  70           // Notify the observer that something happened to socket
  71           virtual void socketNotify(int event) = 0;
  72      }
  73     </synopsis>
  74    </section>
  75    <section id="IPDU_Observable"><title>IPDU_Observable</title>
  76     <para>
  77      This interface is is responsible for sending - and receiving PDUs over
  78      the network (YAZ COMSTACK). When events occur, an instance
  79      implementing <link linkend="IPDU_Observer">IPDU_Observer</link>
  80      is notified.
  81     </para>
  82     <synopsis>
  83      #include &lt;yazpp/pdu-observer.h>
  84
  85      class my_pduobservable : public IPDU_Observable {
  86        public:
  87          // Send encoded PDU buffer of specified length
  88          virtual int send_PDU(const char *buf, int len) = 0;
  89          // Connect with server specified by addr.
  90          virtual void connect(IPDU_Observer *observer,
  91                      const char *addr) = 0;
  92          // Listen on address addr.
  93          virtual void listen(IPDU_Observer *observer, const char *addr)=0;
  94          // Close connection
  95          virtual void close() = 0;
  96          // Make clone of this object using this interface
  97          virtual IPDU_Observable *clone() = 0;
  98          // Destroy completely
  99          virtual void destroy() = 0;
 100          // Set Idle Time
 101          virtual void idleTime (int timeout) = 0;
 102          // Get peername
 103          virtual const char *getpeername() = 0;
 104
 105          virtual ~IPDU_Observable();
 106      };
 107     </synopsis>
 108    </section>
 109    <section id="IPDU_Observer"><title>IPDU_Observer</title>
 110     <para>
 111      This interface is interested in PDUs and using an object implementing
 112      <link linkend="IPDU_Observable">IPDU_Observable</link>.
 113     </para>
 114     <synopsis>
 115      #include &lt;yazpp/pdu-observer.h>
 116
 117      class my_pduobserver : public IPDU_Observer {
 118        public:
 119          // A PDU has been received
 120          virtual void recv_PDU(const char *buf, int len) = 0;
 121          // Called when Iyaz_PDU_Observable::connect was successful.
 122          virtual void connectNotify() = 0;
 123          // Called whenever the connection was closed
 124          virtual void failNotify() = 0;
 125          // Called whenever there is a timeout
 126          virtual void timeoutNotify() = 0;
 127          // Make clone of observer using IPDU_Observable interface
 128          virtual IPDU_Observer *sessionNotify(
 129          IPDU_Observable *the_PDU_Observable, int fd) = 0;
 130      };
 131     </synopsis>
 132    </section>
 133    <section id="query"><title>Yaz_Query</title>
 134     <para>
 135      Abstract query.
 136      </para>
 137     <synopsis>
 138      #include &lt;yazpp/query.h>
 139      class my_query : public Yaz_Query {
 140        public:
 141          // Print query in buffer described by str and len
 142          virtual void print (char *str, int len) = 0;
 143      };
 144     </synopsis>
 145    </section>
 146   </section>
 147
 148   <section id="implementations"><title>Implementations</title>
 149    <section><title>Yaz_SocketManager</title>
 150     <para>
 151      This class implements the <link linkend="ISocketObservable">
 152       ISocketObservable</link> interface and is a portable
 153      socket wrapper around the select call.
 154      This implementation is useful for daemons,
 155      command line clients, etc.
 156     </para>
 157     <synopsis>
 158      #include &lt;yazpp/socket-manager.h>
 159
 160      class SocketManager : public ISocketObservable {
 161        public:
 162          // Add an observer
 163          virtual void addObserver(int fd, ISocketObserver *observer);
 164          // Delete an observer
 165          virtual void deleteObserver(ISocketObserver *observer);
 166          // Delete all observers
 167          virtual void deleteObservers();
 168          // Set event mask for observer
 169          virtual void maskObserver(ISocketObserver *observer, int mask);
 170          // Set timeout
 171          virtual void timeoutObserver(ISocketObserver *observer,
 172                                   unsigned timeout);
 173          // Process one event. return > 0 if event could be processed;
 174          int processEvent();
 175          SocketManager();
 176          virtual ~SocketManager();
 177      };
 178     </synopsis>
 179    </section>
 180    <section><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  -->