2 <title>YAZ C++ API</title>
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 -
10 All definitions from YAZ++ are part of namespace
11 <literal>yazpp_1</literal>.
14 The following sections include a short description of the
15 interfaces and implementations (concrete classes).
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
27 The documentation here is very limited. We plan to enhance it -
28 provided there is interest for it.
31 <section id="interfaces"><title>Interfaces</title>
32 <section id="ISocketObservable"><title>ISocketObservable</title>
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>
40 #include <yazpp/socket-observer.h>
42 class my_socketobservable : public ISocketObservable {
43 // Add an observer interested in socket fd
44 virtual void addObserver(int fd, ISocketObserver *observer) = 0;
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,
53 virtual void timeoutObserver(ISocketObserver *observer,
58 <section id="ISocketObserver"><title>ISocketObserver</title>
60 This interface is interested in socket events supporting
61 the <link linkend="ISocketObservable">ISocketObservable</link>
65 #include <yazpp/socket-observer.h>
67 class my_socketobserver : public ISocketObserver {
69 // Notify the observer that something happened to socket
70 virtual void socketNotify(int event) = 0;
74 <section id="IPDU_Observable"><title>IPDU_Observable</title>
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>
82 #include <yazpp/pdu-observer.h>
84 class my_pduobservable : public IPDU_Observable {
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;
94 virtual void close() = 0;
95 // Make clone of this object using this interface
96 virtual IPDU_Observable *clone() = 0;
98 virtual void destroy() = 0;
100 virtual void idleTime (int timeout) = 0;
102 virtual const char *getpeername() = 0;
104 virtual ~IPDU_Observable();
108 <section id="IPDU_Observer"><title>IPDU_Observer</title>
110 This interface is interested in PDUs and using an object implementing
111 <link linkend="IPDU_Observable">IPDU_Observable</link>.
114 #include <yazpp/pdu-observer.h>
116 class my_pduobserver : public IPDU_Observer {
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;
132 <section id="query"><title>Yaz_Query</title>
137 #include <yazpp/query.h>
138 class my_query : public Yaz_Query {
140 // Print query in buffer described by str and len
141 virtual void print (char *str, int len) = 0;
147 <section id="implementations"><title>Implementations</title>
148 <section id="Yaz_SocketManager"><title>Yaz_SocketManager</title>
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.
157 #include <yazpp/socket-manager.h>
159 class SocketManager : public ISocketObservable {
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);
170 virtual void timeoutObserver(ISocketObserver *observer,
172 // Process one event. return > 0 if event could be processed;
175 virtual ~SocketManager();
179 <section id="PDU_Assoc">
180 <title>PDU_Assoc</title>
182 This class implements the interfaces
183 <link linkend="IPDU_Observable">IPDU_Observable</link>
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).
190 #include <yazpp/pdu-assoc.h>
192 class PDU_Assoc : public IPDU_Observable,
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,
202 // Close socket and destroy object.
203 virtual ~PDU_Assoc();
205 IPDU_Observable *clone();
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);
219 void idleTime (int timeout);
221 virtual void childNotify(COMSTACK cs);
226 <section id="Z_Assoc"><title>Z_Assoc</title>
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
234 #include <yazpp/z-assoc.h>
236 class Z_Assoc : public IPDU_Observer {
238 // Create object using the PDU Observer specified
239 Z_Assoc(IPDU_Observable *the_PDU_Observable);
240 // Destroy association and close PDU Observer
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;
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);
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);
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);
273 void set_APDU_log(const char *fname);
274 const char *get_APDU_log();
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,
285 void set_otherInformationString (
286 Z_OtherInformation **otherInformation,
287 int oidval, int categoryValue,
289 void set_otherInformationString (
291 int oidval, int categoryValue,
294 Z_ReferenceId *getRefID(char* str);
295 Z_ReferenceId **get_referenceIdP(Z_APDU *apdu);
296 void transfer_referenceId(Z_APDU *from, Z_APDU *to);
298 const char *get_hostname();
302 <section id="IR_Assoc"><title>IR_Assoc</title>
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.
309 #include <yazpp/ir-assoc.h>
311 class IR_Assoc : public Z_Assoc {
316 The example client, <filename>yaz-my-client.cpp</filename>,
320 <section id="Z_Server"><title>Z_Server</title>
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.
327 #include <yazpp/z-server.h>
329 class My_Server : public Z_Server {
334 The example server, <filename>yaz-my-server.cpp</filename>,
340 <!-- Keep this comment at the end of the file
345 sgml-minimize-attributes:nil
346 sgml-always-quote-attributes:t
349 sgml-parent-document: "yazpp.xml"
350 sgml-local-catalogs: nil
351 sgml-namecase-general:t