Table of Contents
ZOOM is an acronym for 'Z39.50 Object-Orientation Model' and is an initiative started by Mike Taylor (Mike is from the UK, which explains the peculiar name of the model). The goal of ZOOM is to provide a common Z39.50 client API not bound to a particular programming language or toolkit.
A recent addition to YAZ is SRU support. You can now make
SRU ZOOM connections by specifying scheme http://
for the hostname for a connection. The dialect of SRU used is
specified by the value of the connection's sru
option, which may be SRU over HTTP GET (get
),
SRU over HTTP POST (post
) or SRW (SRU over
SOAP) (soap
). Using the facility for embedding
options in target strings, a connection can be forced to use SRU
rather the SRW (the default) by prefixing the target string with
sru=get,
, like this:
sru=get,http://sru.miketaylor.org.uk:80/sru.pl
The lack of a simple Z39.50 client API for YAZ has become more and more apparent over time. So when the first ZOOM specification became available, an implementation for YAZ was quickly developed. For the first time, it is now as easy (or easier!) to develop clients than servers with YAZ. This chapter describes the ZOOM C binding. Before going further, please reconsider whether C is the right programming language for the job. There are other language bindings available for YAZ, and still more are in active development. See the ZOOM web-site for more information.
In order to fully understand this chapter you should read and
try the example programs zoomtst1.c
,
zoomtst2.c
, .. in the zoom
directory.
The C language misses features found in object oriented languages
such as C++, Java, etc. For example, you'll have to manually,
destroy all objects you create, even though you may think of them as
temporary. Most objects has a _create
- and a
_destroy
variant.
All objects are in fact pointers to internal stuff, but you don't see
that because of typedefs. All destroy methods should gracefully ignore a
NULL
pointer.
In each of the sections below you'll find a sub section called protocol behavior, that describes how the API maps to the Z39.50 protocol.
The Connection object is a session with a target.
#include <yaz/zoom.h> ZOOM_connection ZOOM_connection_new (const char *host, int portnum); ZOOM_connection ZOOM_connection_create (ZOOM_options options); void ZOOM_connection_connect(ZOOM_connection c, const char *host, int portnum); void ZOOM_connection_destroy (ZOOM_connection c);
Connection objects are created with either function
ZOOM_connection_new
or
ZOOM_connection_create
.
The former creates and automatically attempts to establish a network
connection with the target. The latter doesn't establish
a connection immediately, thus allowing you to specify options
before establishing network connection using the function
ZOOM_connection_connect
.
If the port number, portnum
, is zero, the
host
is consulted for a port specification.
If no port is given, 210 is used. A colon denotes the beginning of
a port number in the host string. If the host string includes a
slash, the following part specifies a database for the connection.
You can prefix the host with a scheme followed by colon. The
default scheme is tcp
(Z39.50 protocol).
The scheme http
selects SRU over HTTP.
You can prefix the scheme-qualified host-string with one or more
comma-separated
sequences, each of which represents an option to be set into the
connection structure before the
protocol-level connection is forged and the initialization
handshake takes place. This facility can be used to provide
authentication credentials, as in host-strings such as:
key
=value
user=admin,password=halfAm4n,tcp:localhost:8017/db
Connection objects should be destroyed using the function
ZOOM_connection_destroy
.
void ZOOM_connection_option_set(ZOOM_connection c, const char *key, const char *val); void ZOOM_connection_option_setl(ZOOM_connection c, const char *key, const char *val, int len); const char *ZOOM_connection_option_get(ZOOM_connection c, const char *key); const char *ZOOM_connection_option_getl(ZOOM_connection c, const char *key, int *lenp);
The functions ZOOM_connection_option_set
and
ZOOM_connection_option_setl
allows you to
set an option given by key
to the value
value
for the connection.
For ZOOM_connection_option_set
, the
value is assumed to be a 0-terminated string. Function
ZOOM_connection_option_setl
specifies a
value of a certain size (len).
Functions ZOOM_connection_option_get
and
ZOOM_connection_option_getl
returns
the value for an option given by key
.
Table 3.1. ZOOM Connection Options
Option | Description | Default |
---|---|---|
implementationName | Name of Your client | none |
user | Authentication user name | none |
group | Authentication group name | none |
password | Authentication password. | none |
host | Target host. This setting is "read-only". It's automatically set internally when connecting to a target. | none |
proxy | Proxy host | none |
async | If true (1) the connection operates in
asynchronous operation which means that all calls are non-blocking
except
ZOOM_event .
| 0 |
maximumRecordSize | Maximum size of single record. | 1 MB |
preferredMessageSize | Maximum size of multiple records. | 1 MB |
lang | Language for negotiation. | none |
charset | Character set for negotiation. | none |
serverImplementationId | Implementation ID of server. (The old targetImplementationId option is also supported for the benefit of old applications.) | none |
targetImplementationName | Implementation Name of server. (The old targetImplementationName option is also supported for the benefit of old applications.) | none |
serverImplementationVersion | Implementation Version of server. (the old targetImplementationVersion option is also supported for the benefit of old applications.) | none |
databaseName | One or more database names
separated by character plus (+ ), which to
be used by subsequent search requests on this Connection.
| Default |
piggyback | True (1) if piggyback should be used in searches; false (0) if not. | 1 |
smallSetUpperBound | If hits is less than or equal to this value, then target will return all records using small element set name | 0 |
largeSetLowerBound | If hits is greater than this value, the target will return no records. | 1 |
mediumSetPresentNumber | This value represents the number of records to be returned as part of a search when when hits is less than or equal to large set lower bound and if hits is greater than small set upper bound. | 0 |
smallSetElementSetName | The element set name to be used for small result sets. | none |
mediumSetElementSetName | The element set name to be for medium-sized result sets. | none |
init_opt_search, init_opt_present, init_opt_delSet, etc. | After a successful Init, these options may be interrogated to discover whether the server claims to support the specified operations. | none |
sru_version |
SRU/SRW version. Should be 1.1 , or
1.2 . This is , prior to connect, the version
to offer (highest version). And following connect (in fact
first operation), holds the negotiated version with the server
(same or lower version).
| 1.2 |
If either option lang
or charset
is set, then
Character Set and Language Negotiation is in effect.
int ZOOM_connection_error (ZOOM_connection c, const char **cp, const char **addinfo); int ZOOM_connection_error_x (ZOOM_connection c, const char **cp, const char **addinfo, const char **dset);
Function ZOOM_connection_error
checks for
errors for the last operation(s) performed. The function returns
zero if no errors occurred; non-zero otherwise indicating the error.
Pointers cp
and addinfo
holds messages for the error and additional-info if passed as
non-NULL
. Function
ZOOM_connection_error_x
is an extended version
of ZOOM_connection_error
that is capable of
returning name of diagnostic set in dset
.
The calls ZOOM_connection_new
and
ZOOM_connection_connect
establishes a TCP/IP
connection and sends an Initialize Request to the target if
possible. In addition, the calls waits for an Initialize Response
from the target and the result is inspected (OK or rejected).
If proxy
is set then the client will establish
a TCP/IP connection with the peer as specified by the
proxy
host and the hostname as part of the
connect calls will be set as part of the Initialize Request.
The proxy server will then "forward" the PDU's transparently
to the target behind the proxy.
For the authentication parameters, if option user
is set and both options group
and
pass
are unset, then Open style
authentication is used (Version 2/3) in which case the username
is usually followed by a slash, then by a password.
If either group
or pass
is set then idPass authentication
(Version 3 only) is used. If none of the options are set, no
authentication parameters are set as part of the Initialize Request
(obviously).
When option async
is 1, it really means that
all network operations are postponed (and queued) until the
function ZOOM_event
is invoked. When doing so
it doesn't make sense to check for errors after
ZOOM_connection_new
is called since that
operation "connecting - and init" is still incomplete and the
API cannot tell the outcome (yet).
The SRU protocol doesn't feature an Inititialize Request, so the connection phase merely establishes a TCP/IP connection with the SOAP service.
Most of the ZOOM connection options do not
affect SRU and they are ignored. However, future versions
of YAZ might honor implementationName
and
put that as part of User-Agent header for HTTP requests.
The charset
is used in the Content-Type header
of HTTP requests.