class ZOOM::Connection

The Connection object is a session with a target.

Public Class Methods

new(options=nil) click to toggle source

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.

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| ... } click to toggle source

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.

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;
}

Public Instance Methods

connect(host, port=nil) click to toggle source

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.

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) click to toggle source

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.

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() click to toggle source

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.

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;
}
set_option(key, value) click to toggle source

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.

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;
}