YAZ++ API description
[yazpp-moved-to-github.git] / 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  -->