3 <title>YAZ C++ API</title>
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 -
11 All definitions from YAZ++ are part of namespace
12 <literal>yazpp_1</literal>.
15 The following sections include a short description of the
16 interfaces and implementations (concrete classes).
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
28 The documentation here is very limited. We plan to enhance it -
29 provided there is interest for it.
32 <section id="interfaces"><title>Interfaces</title>
33 <section id="ISocketObservable"><title>ISocketObservable</title>
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>
41 #include <yazpp/socket-observer.h>
43 class my_socketobservable : public ISocketObservable {
44 // Add an observer interested in socket fd
45 virtual void addObserver(int fd, ISocketObserver *observer) = 0;
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,
54 virtual void timeoutObserver(ISocketObserver *observer,
59 <section id="ISocketObserver"><title>ISocketObserver</title>
61 This interface is interested in socket events supporting
62 the <link linkend="ISocketObservable">ISocketObservable</link>
66 #include <yazpp/socket-observer.h>
68 class my_socketobserver : public ISocketObserver {
70 // Notify the observer that something happened to socket
71 virtual void socketNotify(int event) = 0;
75 <section id="IPDU_Observable"><title>IPDU_Observable</title>
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>
83 #include <yazpp/pdu-observer.h>
85 class my_pduobservable : public IPDU_Observable {
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;
95 virtual void close() = 0;
96 // Make clone of this object using this interface
97 virtual IPDU_Observable *clone() = 0;
99 virtual void destroy() = 0;
101 virtual void idleTime (int timeout) = 0;
103 virtual const char *getpeername() = 0;
105 virtual ~IPDU_Observable();
109 <section id="IPDU_Observer"><title>IPDU_Observer</title>
111 This interface is interested in PDUs and using an object implementing
112 <link linkend="IPDU_Observable">IPDU_Observable</link>.
115 #include <yazpp/pdu-observer.h>
117 class my_pduobserver : public IPDU_Observer {
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;
133 <section id="query"><title>Yaz_Query</title>
138 #include <yazpp/query.h>
139 class my_query : public Yaz_Query {
141 // Print query in buffer described by str and len
142 virtual void print (char *str, int len) = 0;
148 <section id="implementations"><title>Implementations</title>
149 <section><title>Yaz_SocketManager</title>
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.
158 #include <yazpp/socket-manager.h>
160 class SocketManager : public ISocketObservable {
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);
171 virtual void timeoutObserver(ISocketObserver *observer,
173 // Process one event. return > 0 if event could be processed;
176 virtual ~SocketManager();
180 <section><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