Added id attributes to some sections
[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 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  -->