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 id="Yaz_SocketManager"><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 id="PDU_Assoc">
 181     <title>PDU_Assoc</title>
 182     <para>
 183      This class implements the interfaces
 184      <link linkend="IPDU_Observable">IPDU_Observable</link>
 185      and
 186      <link linkend="ISocketObserver">ISocketObserver</link>.
 187      This object implements a non-blocking client/server channel
 188      that transmits BER encoded PDUs (or those offered by YAZ COMSTACK).
 189     </para>
 190     <synopsis>
 191      #include &lt;yazpp/pdu-assoc.h>
 192
 193      class PDU_Assoc : public IPDU_Observable,
 194                                  ISocketObserver {
 195
 196        public:
 197          COMSTACK comstack(const char *type_and_host, void **vp);
 198          // Create object using specified socketObservable
 199          PDU_Assoc(ISocketObservable *socketObservable);
 200          // Create Object using existing comstack
 201          PDU_Assoc(ISocketObservable *socketObservable,
 202                   COMSTACK cs);
 203          // Close socket and destroy object.
 204          virtual ~PDU_Assoc();
 205          // Clone the object
 206          IPDU_Observable *clone();
 207          // Send PDU
 208          int send_PDU(const char *buf, int len);
 209          // connect to server (client role)
 210          void connect(IPDU_Observer *observer, const char *addr);
 211          // listen for clients (server role)
 212          void listen(IPDU_Observer *observer, const char *addr);
 213          // Socket notification
 214          void socketNotify(int event);
 215          // Close socket
 216          void close();
 217          // Close and destroy
 218          void destroy();
 219          // Set Idle Time
 220          void idleTime (int timeout);
 221          // Child start...
 222          virtual void childNotify(COMSTACK cs);
 223      };
 224     </synopsis>
 225    </section>
 226
 227    <section id="Z_Assoc"><title>Z_Assoc</title>
 228     <para>
 229      This class implements the interface
 230      <link linkend="IPDU_Observer">IPDU_Obserer</link>.
 231      This object implements a Z39.50 client/server channel AKA
 232      Z-Association.
 233     </para>
 234     <synopsis>
 235      #include &lt;yazpp/z-assoc.h>
 236
 237      class Z_Assoc : public IPDU_Observer {
 238        public:
 239          // Create object using the PDU Observer specified
 240          Z_Assoc(IPDU_Observable *the_PDU_Observable);
 241          // Destroy association and close PDU Observer
 242          virtual ~Z_Assoc();
 243          // Receive PDU
 244          void recv_PDU(const char *buf, int len);
 245          // Connect notification
 246          virtual void connectNotify() = 0;
 247          // Failure notification
 248          virtual void failNotify() = 0;
 249          // Timeout notification
 250          virtual void timeoutNotify() = 0;
 251          // Timeout specify
 252          void timeout(int timeout);
 253          // Begin Z39.50 client role
 254          void client(const char *addr);
 255          // Begin Z39.50 server role
 256          void server(const char *addr);
 257          // Close connection
 258          void close();
 259
 260          // Decode Z39.50 PDU.
 261          Z_APDU *decode_Z_PDU(const char *buf, int len);
 262          // Encode Z39.50 PDU.
 263          int encode_Z_PDU(Z_APDU *apdu, char **buf, int *len);
 264          // Send Z39.50 PDU
 265          int send_Z_PDU(Z_APDU *apdu);
 266          // Receive Z39.50 PDU
 267          virtual void recv_Z_PDU(Z_APDU *apdu) = 0;
 268          // Create Z39.50 PDU with reasonable defaults
 269          Z_APDU *create_Z_PDU(int type);
 270          // Request Alloc
 271          ODR odr_encode ();
 272          ODR odr_decode ();
 273          ODR odr_print ();
 274          void set_APDU_log(const char *fname);
 275          const char *get_APDU_log();
 276
 277          // OtherInformation
 278          void get_otherInfoAPDU(Z_APDU *apdu, Z_OtherInformation ***oip);
 279          Z_OtherInformationUnit *update_otherInformation (
 280                Z_OtherInformation **otherInformationP, int createFlag,
 281                int *oid, int categoryValue, int deleteFlag);
 282          void set_otherInformationString (
 283                Z_OtherInformation **otherInformationP,
 284                int *oid, int categoryValue,
 285                const char *str);
 286          void set_otherInformationString (
 287                Z_OtherInformation **otherInformation,
 288                int oidval, int categoryValue,
 289                const char *str);
 290          void set_otherInformationString (
 291                Z_APDU *apdu,
 292                int oidval, int categoryValue,
 293                const char *str);
 294
 295          Z_ReferenceId *getRefID(char* str);
 296          Z_ReferenceId **get_referenceIdP(Z_APDU *apdu);
 297          void transfer_referenceId(Z_APDU *from, Z_APDU *to);
 298
 299          const char *get_hostname();
 300      };
 301     </synopsis>
 302    </section>
 303    <section id="IR_Assoc"><title>IR_Assoc</title>
 304     <para>
 305      This object is just a specialization of
 306      <link linkend="Z_Assoc">Z_Assoc</link> and provides
 307      more facilities for the Z39.50 client role.
 308     </para>
 309     <synopsis>
 310      #include &lt;yazpp/ir-assoc.h>
 311
 312      class IR_Assoc : public Z_Assoc {
 313        ...
 314      };
 315     </synopsis>
 316     <para>
 317      The example client, <filename>yaz-my-client.cpp</filename>,
 318      uses this class.
 319     </para>
 320    </section>
 321    <section id="Z_Server"><title>Z_Server</title>
 322     <para>
 323      This object is just a specialization of
 324      <link linkend="Z_Assoc">Z_Assoc</link> and provides
 325      more facilities for the Z39.50 server role.
 326     </para>
 327     <synopsis>
 328      #include &lt;yazpp/z-server.h>
 329
 330      class My_Server : public Z_Server {
 331        ...
 332      };
 333     </synopsis>
 334     <para>
 335      The example server, <filename>yaz-my-server.cpp</filename>,
 336      uses this class.
 337     </para>
 338    </section>
 339   </section>
 340  </chapter>
 341  <!-- Keep this comment at the end of the file
 342  Local variables:
 343  mode: sgml
 344  sgml-omittag:t
 345  sgml-shorttag:t
 346  sgml-minimize-attributes:nil
 347  sgml-always-quote-attributes:t
 348  sgml-indent-step:1
 349  sgml-indent-data:t
 350  sgml-parent-document: "yazpp.xml"
 351  sgml-local-catalogs: nil
 352  sgml-namecase-general:t
 353  End:
 354  -->