YAZ C++ API
The YAZ C++ API is an client - and server API that exposes
all YAZ features. The API doesn't hide YAZ C data structures, but
provides a set of useful high-level objects for creating clients -
and servers.
All definitions from YAZ++ are part of namespace
yazpp_1.
The following sections include a short description of the
interfaces and implementations (concrete classes).
In order to understand the structure, you should look at the
example client yaz-my-client.cpp and
the example server yaz-my-server.cpp.
If that is too easy, you can always turn to the implementation
of the proxy itself and send us a patch if you implement a new
useful feature.
The documentation here is very limited. We plan to enhance it -
provided there is interest for it.
InterfacesISocketObservable
This interface is capable of observing sockets.
When a socket even occurs it invokes an object implementing the
ISocketObserver
interface.
#include <yazpp/socket-observer.h>
class my_socketobservable : public ISocketObservable {
// Add an observer interested in socket fd
virtual void addObserver(int fd, ISocketObserver *observer) = 0;
// Delete an observer
virtual void deleteObserver(ISocketObserver *observer) = 0;
// Delete all observers
virtual void deleteObservers() = 0;
// Specify the events that the observer is interested in.
virtual void maskObserver(ISocketObserver *observer,
int mask) = 0;
// Specify timeout
virtual void timeoutObserver(ISocketObserver *observer,
int timeout)=0;
};
ISocketObserver
This interface is interested in socket events supporting
the ISocketObservable
interface.
#include <yazpp/socket-observer.h>
class my_socketobserver : public ISocketObserver {
public:
// Notify the observer that something happened to socket
virtual void socketNotify(int event) = 0;
}
IPDU_Observable
This interface is is responsible for sending - and receiving PDUs over
the network (YAZ COMSTACK). When events occur, an instance
implementing IPDU_Observer
is notified.
#include <yazpp/pdu-observer.h>
class my_pduobservable : public IPDU_Observable {
public:
// Send encoded PDU buffer of specified length
virtual int send_PDU(const char *buf, int len) = 0;
// Connect with server specified by addr.
virtual void connect(IPDU_Observer *observer,
const char *addr) = 0;
// Listen on address addr.
virtual void listen(IPDU_Observer *observer, const char *addr)=0;
// Close connection
virtual void close() = 0;
// Make clone of this object using this interface
virtual IPDU_Observable *clone() = 0;
// Destroy completely
virtual void destroy() = 0;
// Set Idle Time
virtual void idleTime (int timeout) = 0;
// Get peername
virtual const char *getpeername() = 0;
virtual ~IPDU_Observable();
};
IPDU_Observer
This interface is interested in PDUs and using an object implementing
IPDU_Observable.
#include <yazpp/pdu-observer.h>
class my_pduobserver : public IPDU_Observer {
public:
// A PDU has been received
virtual void recv_PDU(const char *buf, int len) = 0;
// Called when Iyaz_PDU_Observable::connect was successful.
virtual void connectNotify() = 0;
// Called whenever the connection was closed
virtual void failNotify() = 0;
// Called whenever there is a timeout
virtual void timeoutNotify() = 0;
// Make clone of observer using IPDU_Observable interface
virtual IPDU_Observer *sessionNotify(
IPDU_Observable *the_PDU_Observable, int fd) = 0;
};
Yaz_Query
Abstract query.
#include <yazpp/query.h>
class my_query : public Yaz_Query {
public:
// Print query in buffer described by str and len
virtual void print (char *str, int len) = 0;
};
ImplementationsYaz_SocketManager
This class implements the
ISocketObservable interface and is a portable
socket wrapper around the select call.
This implementation is useful for daemons,
command line clients, etc.
#include <yazpp/socket-manager.h>
class SocketManager : public ISocketObservable {
public:
// Add an observer
virtual void addObserver(int fd, ISocketObserver *observer);
// Delete an observer
virtual void deleteObserver(ISocketObserver *observer);
// Delete all observers
virtual void deleteObservers();
// Set event mask for observer
virtual void maskObserver(ISocketObserver *observer, int mask);
// Set timeout
virtual void timeoutObserver(ISocketObserver *observer,
unsigned timeout);
// Process one event. return > 0 if event could be processed;
int processEvent();
SocketManager();
virtual ~SocketManager();
};
PDU_Assoc
This class implements the interfaces
IPDU_Observable
and
ISocketObserver.
This object implements a non-blocking client/server channel
that transmits BER encoded PDUs (or those offered by YAZ COMSTACK).
#include <yazpp/pdu-assoc.h>
class PDU_Assoc : public IPDU_Observable,
ISocketObserver {
public:
COMSTACK comstack(const char *type_and_host, void **vp);
// Create object using specified socketObservable
PDU_Assoc(ISocketObservable *socketObservable);
// Create Object using existing comstack
PDU_Assoc(ISocketObservable *socketObservable,
COMSTACK cs);
// Close socket and destroy object.
virtual ~PDU_Assoc();
// Clone the object
IPDU_Observable *clone();
// Send PDU
int send_PDU(const char *buf, int len);
// connect to server (client role)
void connect(IPDU_Observer *observer, const char *addr);
// listen for clients (server role)
void listen(IPDU_Observer *observer, const char *addr);
// Socket notification
void socketNotify(int event);
// Close socket
void close();
// Close and destroy
void destroy();
// Set Idle Time
void idleTime (int timeout);
// Child start...
virtual void childNotify(COMSTACK cs);
};
Z_Assoc
This class implements the interface
IPDU_Obserer.
This object implements a Z39.50 client/server channel AKA
Z-Association.
#include <yazpp/z-assoc.h>
class Z_Assoc : public IPDU_Observer {
public:
// Create object using the PDU Observer specified
Z_Assoc(IPDU_Observable *the_PDU_Observable);
// Destroy association and close PDU Observer
virtual ~Z_Assoc();
// Receive PDU
void recv_PDU(const char *buf, int len);
// Connect notification
virtual void connectNotify() = 0;
// Failure notification
virtual void failNotify() = 0;
// Timeout notification
virtual void timeoutNotify() = 0;
// Timeout specify
void timeout(int timeout);
// Begin Z39.50 client role
void client(const char *addr);
// Begin Z39.50 server role
void server(const char *addr);
// Close connection
void close();
// Decode Z39.50 PDU.
Z_APDU *decode_Z_PDU(const char *buf, int len);
// Encode Z39.50 PDU.
int encode_Z_PDU(Z_APDU *apdu, char **buf, int *len);
// Send Z39.50 PDU
int send_Z_PDU(Z_APDU *apdu);
// Receive Z39.50 PDU
virtual void recv_Z_PDU(Z_APDU *apdu) = 0;
// Create Z39.50 PDU with reasonable defaults
Z_APDU *create_Z_PDU(int type);
// Request Alloc
ODR odr_encode ();
ODR odr_decode ();
ODR odr_print ();
void set_APDU_log(const char *fname);
const char *get_APDU_log();
// OtherInformation
void get_otherInfoAPDU(Z_APDU *apdu, Z_OtherInformation ***oip);
Z_OtherInformationUnit *update_otherInformation (
Z_OtherInformation **otherInformationP, int createFlag,
int *oid, int categoryValue, int deleteFlag);
void set_otherInformationString (
Z_OtherInformation **otherInformationP,
int *oid, int categoryValue,
const char *str);
void set_otherInformationString (
Z_OtherInformation **otherInformation,
int oidval, int categoryValue,
const char *str);
void set_otherInformationString (
Z_APDU *apdu,
int oidval, int categoryValue,
const char *str);
Z_ReferenceId *getRefID(char* str);
Z_ReferenceId **get_referenceIdP(Z_APDU *apdu);
void transfer_referenceId(Z_APDU *from, Z_APDU *to);
const char *get_hostname();
};
IR_Assoc
This object is just a specialization of
Z_Assoc and provides
more facilities for the Z39.50 client role.
#include <yazpp/ir-assoc.h>
class IR_Assoc : public Z_Assoc {
...
};
The example client, yaz-my-client.cpp,
uses this class.
Z_Server
This object is just a specialization of
Z_Assoc and provides
more facilities for the Z39.50 server role.
#include <yazpp/z-server.h>
class My_Server : public Z_Server {
...
};
The example server, yaz-my-server.cpp,
uses this class.