Class: ZOOM::Connection

Inherits:
Object
  • Object
show all
Defined in:
ext/rbzoomconnection.c,
ext/rbzoomconnection.c

Overview

The Connection object is a session with a target.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(options = nil) ⇒ Object

options: options for the connection, as a Hash object.

Creates a new connection object, but does not establish a network connection immediately, allowing you to specify options before (if given). You can thus establish the connection using ZOOM::Connection#connect.

Returns: a newly created ZOOM::Connection object.



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'ext/rbzoomconnection.c', line 130

static VALUE
rbz_connection_new (int argc, VALUE *argv, VALUE self)
{
    ZOOM_options options;
    ZOOM_connection connection;
    VALUE rb_options;
    
    rb_scan_args (argc, argv, "01", &rb_options);

    if (NIL_P (rb_options))
        options = ZOOM_options_create ();
    else
        options = ruby_hash_to_zoom_options (rb_options);

    connection = ZOOM_connection_create (options);
    ZOOM_options_destroy (options);
    RAISE_IF_FAILED (connection);

    return rbz_connection_make (connection);
}

.open(host, port = nil) {|conn| ... } ⇒ Object

host: hostname of the target to connect to.

port: network port of the target to connect to.

A convenience method that creates a new connection and attempts to establish a network connection to the given target, basically calling ZOOM::Connection.new and ZOOM::Connection#connect.

If a block is given, then it will be called once the connection is established, passing a reference to the connection object as a parameter, and destroying the connection automatically at the end of the block. With no block, this method just returns the connection object.

Returns: a newly created ZOOM::Connection object.

Yields:

  • (conn) 


97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'ext/rbzoomconnection.c', line 97

static VALUE
rbz_connection_open (int argc, VALUE *argv, VALUE self)
{
    VALUE host;
    VALUE port;
    ZOOM_connection connection;
    VALUE rb_connection;
    
    rb_scan_args (argc, argv, "11", &host, &port);

    connection = ZOOM_connection_new (RVAL2CSTR (host),
                                      NIL_P (port) ? 0 : FIX2INT (port));
    RAISE_IF_FAILED (connection);
    
    rb_connection = rbz_connection_make (connection);
    if (rb_block_given_p ()) {
        rb_yield(rb_connection);
        return Qnil;
    }
    return rb_connection;
}

Instance Method Details

#connect(host, port = nil) ⇒ Object

host: hostname of the target to connect to.

port: network port of the target to connect to.

Establishes a network connection to the target specified by the given arguments. If no port is given, 210 will be used. A colon in the host string denotes the beginning of a port number. If the host string includes a slash, the following part specifies a database for the connection.

You can also prefix the host string with a scheme followed by a colon. The default scheme is tcp (Z39.50 protocol). The scheme http selects SRW over HTTP.

This method raises an exception on error.

Returns: self.



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'ext/rbzoomconnection.c', line 172

static VALUE
rbz_connection_connect (int argc, VALUE *argv, VALUE self)
{
    ZOOM_connection connection;
    VALUE host;
    VALUE port;
    
    rb_scan_args (argc, argv, "11", &host, &port);
  
    connection = rbz_connection_get (self);
    ZOOM_connection_connect (connection, 
                             RVAL2CSTR (host), 
                             NIL_P (port) ? 0 : FIX2INT (port));
    RAISE_IF_FAILED (connection); 

    return self;
}

#get_option(key) ⇒ Object

key: the name of the option, as a string.

Gets the value of a connection’s option.

Returns: the value of the given option, as a string, integer or boolean.



226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'ext/rbzoomconnection.c', line 226

static VALUE
rbz_connection_get_option (VALUE self, VALUE key)
{
    ZOOM_connection connection;
    const char *value;
 
    connection = rbz_connection_get (self);
    value = ZOOM_connection_option_get (connection,
                                        RVAL2CSTR (key));

    return zoom_option_value_to_ruby_value (value);
}

#package ⇒ Object

Constructs a new extended services ZOOM::Package using this connections host information.

Note: The Perl script passes this connections options if already set, otherwise constructs a new ZOOM::Option object. Currently this method always constructs a new ZOOM::Option object for each package.

Returns: a new ZOOM::Package object.



283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'ext/rbzoomconnection.c', line 283

static VALUE
rbz_connection_package(VALUE self)
{
  ZOOM_connection connection;
  ZOOM_options options;
  VALUE package;

  connection = rbz_connection_get (self);
  options = ZOOM_options_create ();
  package = rbz_package_make(connection, options);
  return package;
}

#search(criterion) ⇒ Object

criterion: the search criterion, either as a ZOOM::Query object or as a string, representing a PQF query.

Searches the connection from the given criterion. You can either create and pass a reference to a ZOOM::Query object, or you can simply pass a string that represents a PQF query.

This method raises an exception on error.

Returns: a result set from the search, as a ZOOM::ResultSet object, empty if no results were found.



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'ext/rbzoomconnection.c', line 255

static VALUE
rbz_connection_search (VALUE self, VALUE criterion)
{
    ZOOM_connection connection;
    ZOOM_resultset resultset;

    connection = rbz_connection_get (self);
    if (TYPE (criterion) == T_STRING)
        resultset = ZOOM_connection_search_pqf (connection,
                                                RVAL2CSTR (criterion));
    else
        resultset = ZOOM_connection_search (connection,
                                            rbz_query_get (criterion));
    RAISE_IF_FAILED (connection); 
    assert (resultset != NULL);
  
    return rbz_resultset_make (resultset);
}

#set_option(key, value) ⇒ Object

key: the name of the option, as a string.

value: the value of this option (as a string, integer or boolean).

Sets an option on the connection.

Returns: self.



202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'ext/rbzoomconnection.c', line 202

static VALUE
rbz_connection_set_option (VALUE self, VALUE key, VALUE val)
{
    ZOOM_connection connection;
    
    connection = rbz_connection_get (self);
    ZOOM_connection_option_set (connection,
                                RVAL2CSTR (key),
                                RVAL2CSTR (rb_obj_as_string (val)));
    RAISE_IF_FAILED (connection); 
    
    return self;
}