- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS

- open
- readline
- readblock
- readall
- readalluntil
- select_time
- read_wait
- write
- eol
- error
- iaddr
- port

- SEE ALSO
- MAINTAINER
- COPYRIGHT
- VERSION

# NAME

GT::Socket::Client - Socket module designed for TCP clients

# SYNOPSIS

        use GT::Socket::Client qw/:crlf/;

        my $socket = GT::Socket::Client->open(
            host => "gossamer-threads.com",
            port => "shell", # AKA port 514
            timeout => 10
        ) or die GT::Socket::Client->error;

        # $socket is now a socket connected to the host. Use
        # it as you would use any socket.
        $sock->readline(my $line);
        print "Read this line from the socket: $line";
        print $sock "That line" . CRLF;

        $sock->readblock(my $block, 4096);
        print "Read 4KB from the socket: $block";
        print $sock "QUIT" . CRLF;

        $sock->readall(my $all);
        print "Everything else from the socket: $all";
        print $sock "Something else" . CRLF;

# DESCRIPTION

This module is a basic socket module that is designed to only handle basic socket connection and simple read capabilities. Anything else that you want to do with the socket is entirely up to you - this doesn't try to support superfluous options that only a few connections will ever use, or options that should be done in the code using this module instead of the module itself. See the GT::WWW::http and GT::WWW::https modules for a good working example.

By default, GT::Socket::Client exports nothing, however it can export the LF, CR, CRLF, $LF, $CR, and $CRLF constants, individually, or together via the ':crlf' export tag.

# METHODS

## open

Takes a hash (not hash reference) of socket options, as follows:

host

  [REQUIRED] The name or IP of the host to connect to.

port

  [REQUIRED] The numeric value (25) or service name (``smtp'') of the port to connect to.

ssl

  [OPTIONAL] If this option is provided, the connection will use SSL. Note that this requires the Net::SSLeay module.

timeout

  [OPTIONAL] A connection timeout period, in integral seconds. Note that this is only supported on systems that support the `alarm()` function; on other systems (such as Windows), this argument has no effect.

non_blocking

  [OPTIONAL] Before returning it to you, the connected socket will be set up as non-blocking if this option is enabled. Note that this option DOES NOT WORK with the ssl option, due to the Net::SSLeay interface.

autoflush

  [OPTIONAL] Before returning to you, the connected socket will be made non- buffering. If you want your socket to be buffered, pass in autoflush with a false value.

ssl

  [OPTIONAL] GT::Socket::Client has the ability to establish an SSL connection to a server for protocols such as HTTPS, SMTPS, POP3S, IMAPS, etc. Note that it currently has a limitation of not being able to change to or from an SSL connection once the connection is established, for protocols like FTPS.

debug

  [OPTIONAL] If debugging is enabled, internal warnings (such as invalid port, unresolvable host, connection failure, etc.) will be warn()ed. This does not affect the `error()` method, which will always be set to the error message when a problem occurs. Provide a true value if you want the warn()s to appear.

## readline

This method reads a single line from the socket. It takes one argument, which must be a scalar which will be set to the line read. See the `eol()` method, which allows you to specify an EOL character other than ``\012''. Note that on a blocking socket, this will block until it can read a full line (or the server closes the connection). On a non-blocking socket, the amount of time it will wait for input is dependent on the value of the `read_wait()` method.

1 is returned on success, undef on failure.

## readblock

This method attempts to read a certain number of bytes from the server. This takes two arguments: like readline(), the first argument is a scalar that will be set to the data read. The second argument is the amount of data that may be read. Note that on a blocking socket, this will block until the required amount of data is read, or the socket is closed. On a non-blocking socket, this will return once the requested amount of data is read, the socket closes, or there is no input for `read_wait` seconds (See read_wait).

Note that a block size of -1 makes the socket read until the connection is closed, in the case of blocking sockets, or until the `read_wait()` is hit.

The number of bytes read is returned on success, undef on failure.

## readall

A synonym for `$obj->readblock($_[0], -1)` - in other words, it reads all available data (waiting for up to `read_wait` seconds, if non-blocking).

## readalluntil

A useful function for non-blocking sockets (completely useless for blocking sockets, on which it simply becomes a readall call). Basically, this works like readall(), above, but it will terminate immediately if it encounters a pattern that you provide on the end of the data read. Note that this does NOT work as a delimiter, but is useful for protocols such as POP3 when you want to read as much as you can, but know what should be at the end of what you read. The sole advantage of this is that it allows you to avoid the read_wait timeout that would otherwise be required at the end of a data stream.

It takes two arguments - the first is a string or array reference of strings containing the trailing string data. The second is a scalar that will be set to the data read. For example, for POP3 you might use: `"\n.\r\n"`. You can optionally pass in a third argument, which is used during the first read - if the result of the first read is equal to the string passed in, it's returned. Using the POP3 example again, this might be `".\r\n"` - to handle an empty response.

## select_time

[Non-blocking sockets only] This adjusts the number of seconds passed to `select()` to poll the socket for available data. The default value is 0.05, which should work in most situations.

## read_wait

[Non-blocking sockets only] This method is used to set the wait time for reads. On a local or very fast connection, this can be set to a low value (i.e. 0.1 seconds), but on a typical slower internet connection, longer wait times for reading are usually necessary. Hence, the default is a wait time of 5 seconds. In effect, an attempt to read all data will end after nothing has been received for this many seconds.

## write

Sends data to the server. Takes the data to send. This does The Right Thing for either non-blocking or blocking sockets.

## eol

This method takes one or more character, and uses it for the EOL `character(s)` used by readline. If called without any argument, the EOL character for the current object is returned.

## error

If an error (such as connection, socket, etc.) occurs, you can access it via the `error()` method. This can be called as either a class or instance method, since `open()` return `undef` instead of an object if the connection fails.

## iaddr

Once a connection has been established, you can call this method to get the iaddr value for the connection. This value is as returned by Socket.pm's inet_aton function.

## port

Once a connection has been established, this method can be used to determine the port connected to. Note that this is not necessarily the same as the value of the `port` option passed to `open()` - the return value of this function will always be numeric (e.g. `25`), even if a service name (e.g. `"smtp"`) was passed to open().

# SEE ALSO

the GT::Socket manpage - A socket module made for Links SQL.

# MAINTAINER

Jason Rhinelander

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: Client.pm,v 1.16 2005/09/19 23:06:25 brewt Exp $