- NAME
- SYNOPSIS
- DESCRIPTION

- Method List
- Creating a new Client Socket
- Limiting maximum amount of data downloaded
- Limiting maximum amount of data uploaded
- Limiting time taken to connect to a host
- Methods
- autoflush ( flag BOOLEAN )
- close
- EOF
- fh
- gulpread ( tics INTEGER )
- pending ( tics INTEGER )
- read ( number_bytes INTEGER )
- vec ( [ bits SCALAR ] )
- write ( buffer SCALAR )
- Creating a new Server Socket
- Methods
- accept
- fh
- pending ( tics INTEGER )
- vec ( [ bits SCALAR ] )

- EXAMPLES

- Server
- Client for Server

- COPYRIGHT
- VERSION

# NAME

GT::Socket - A simple internet socket handling interface

# SYNOPSIS

        use GT::Socket;

        my $sock = GT::Socket->open({
            host => 'www.gossamer-threads.com',
            port => 80
        });

        $sock->write("GET / HTTP/1.0\n\n");

        print "REQUEST RETURNED:\n\n", $sock->gulpread(-1);

# DESCRIPTION

GT::Socket provides a simple interface for tcp client/server socket services.

## Method List

Object Creation

        open()        Creates a new client socket
        server()      Creates a new server socket

Reading and Writing

        write()       Sends all or up to max_up bytes of data to remote
        read()        Receives an amount or max_down bytes of data from remote
        gulpread()    Gets all or up to max_down bytes of data from remote

Socket Administration

        close()       Closes the socket
        EOF()         Returns open/closed status of socket
        autoflush()   Sets the socket so that no data is buffered
        vec()         Sets bits in a bitmask for select calls
        pending()     Returns true if data/clients awaiting
        fh()          Returns the raw socket handle

Server Handling

        accept()      Accepts a incoming client request

## Creating a new Client Socket

To instantiate a new Client Socket connection, the `open()` method must be called.

        my $sock = GT::Socket->open({
            host => 'hostname', # hostname/ip to connect to
            port => 1234,       # port to connect to
            max_down => 0,      # maximum number of bytes to download (optional)
            max_up => 0,        # maximum number of bytes to upload (optional)
            timeout => 10       # maximum time to wait for host connect (optional)
        });

The parameters are somewhat flexible, to connect to www.gossamer-threads.com on port 80, any of the following calling methods can be used.

        my $sock = GT::Socket->open({
            host => 'www.gossamer-threads.com',
            port => 80
        });

        my $sock = GT::Socket->open(
            host => 'www.gossamer-threads.com',
            port => 80
        );

        my $sock = GT::Socket->open('www.gossamer-threads.com', 80);

        my $sock = GT::Socket->open('www.gossamer-threads.com:80');

Note that as port 80 is the HTTP port, and port gets tested and handled with the getservbyname function, the following can be done:

        # 'http' here but can be 'pop3', 'telnet', etc. depending on service wanted
        my $sock = GT::Socket->open('www.gossamer-threads.com', 'http');

Note that if the value passed to `open()` is a hash ref, with a host and port, a handful of other options may be set.

## Limiting maximum amount of data downloaded

This affects the $sock->`read()` and the $sock->`gulpread()` methods.

The option 'max_down' can be used to put a cap on the number of bytes recieved through the socket.

For example to limit the number of bytes downloaded to 2k, set max_down to 2048

        my $sock = GT::Socket->open(
            host => 'www.gossamer-threads.com',
            port => 80,
            max_down => 2048
        );

WARNING, once the download maximum has been reached, the socket is closed. Then no more information can be uploaded to the remote host.

## Limiting maximum amount of data uploaded

The option 'max_up' is used to limit the number of bytes that can be sent to the remote host.

After the maximum number of bytes is hit, the object will no longer carry out $sock->`write()` requests.

This does not affect the number of bytes that can be downloaded. Until max_down is hit or the remote host finishes the transmission, the socket will keep listening.

In the following example. The maximum number of bytes for both download and upload have been set to 2K.

Keep in mind, with this example, if the maximum download limit is reached before the maximum upload, the socket will be closed so the remote server will stop responding to $sock->`write()` as well!

        my $sock = GT::Socket->open(
            host => 'www.gossamer-threads.com',
            port => 80,
            max_down => 2048,
            max_up => 2048
        );

## Limiting time taken to connect to a host

When the module tries to connect to a host, if the host is not running or simply not present, it may take over 30 seconds for the connect call to give up.

The 'timout' option allows the forcing the waiting period to be a certain number of seconds. By default, the value is set to 10 seconds.

Since this uses alarm, it will not function on Win32 machines.

With the following example, the module will spend a maximum of 3 seconds trying to connect to www.gossamer-threads.com.

        my $sock = GT::Socket->open(
            host => 'www.gossamer-threads.com',
            port => 80,
            timeout => 3
        );

## Methods

The following methods are available to the Client object

## autoflush ( flag BOOLEAN )

        $sock->autoflush(1) # turn on flushing
        $sock->autoflush(0) # turn off flushing

Turns off buffering for the socket. By default, the socket is autoflushed/buffering turned off.

This prevents peculiar errors like stalling when trying to communicate with http servers.

## close

Closes the socket if open.

## EOF

Returns true of the socket is closed.

## fh

Returns the filehandle.

The return value is file glob, because of this, the upload/download limits cannot be enforced and the accounting can fall to bits of both the object and the file glob are being used simultaneously.

## gulpread ( tics INTEGER )

Attempts to read all the data it can into a buffer and return. If max_down is non zero, it will read till the remote closes or the limit has been reached and returns.

Tics is a non-zero value that will determine how long the function will run for or wait:

        $tics     Action
        ----------------------------------------
        >0        Wait $tics seconds till returning with results
        0         Don't wait, simply get what's there and return
        <0        Block, wait until all the data (up to max_down) has been received

## pending ( tics INTEGER )

Returns true if socket has data pending to be received. Usually this would be followed with a call to $sock->`gulpread()` or $sock->`read()`

        $tics     Action
        ----------------------------------------
        >0        Wait $tics seconds till returning with results
        0         Don't wait, simply get what's there and return
        <0        Block, wait until all the data (up to max_down) has been received

## read ( number_bytes INTEGER )

Reads a max of number_bytes from the socket or up to max_down and returns the result. This is nonblocking so it is possible to get no data or less than the requested amount.

## vec ( [ bits SCALAR ] )

Sets the bits appropriate for the object's socket handle. The returned value can be used in `select(RBITS,WBITS,EBITS,TIMEOUT)` function calls.

To test a series of socket handles, vec accepts an already set bit list from another vec call.

        $bits = $sock1->vec();
        $bits = $sock2->vec($bits);
        $bits = $sock3->vec($bits);

And $bits can now be used to test on all three handles.

## write ( buffer SCALAR )

Takes the buffer and send it into the socket or up to the max_up limit.

Returns the number of bytes sent.

## Creating a new Server Socket

Creating a server socket is almost identical to creating a client socket except no hostname is specified.

        my $server = GT::Socket->server({
            port => 1234,  # port to host services
            max_down => 0, # maximum number of bytes to download (optional)
            max_up => 0,   # maximum number of bytes to upload (optional)
            timeout => 10  # maximum time to wait for host connect (optional)
        });

The only option that affects the server directly is the port. The optional values, max_down, max_up, and timeout are passed on to the child socket when the server accepts a new connection.

## Methods

The following methods are available to the Client object

## accept

Accepts an incoming connection and returns a GT::Socket client object for further interations with the client.

## fh

Returns the filehandle.

## pending ( tics INTEGER )

Returns true if server has awaiting connections. Usually this would be followed with a call to $server->accept();

        $tics     Action
        ----------------------------------------
        >0        Wait $tics seconds till returning with results
        0         Don't wait, simply get what's there and return
        <0        Block, wait until all the data (up to max_down) has been received

## vec ( [ bits SCALAR ] )

Sets the bits appropriate for the object's socket handle. The returned value can be used in `select(RBITS,WBITS,EBITS,TIMEOUT)` function calls.

To test a series of socket handles, vec accepts an already set bit list from another vec call.

        $bits = $sock1->vec();
        $bits = $sock2->vec($bits);
        $bits = $sock3->vec($bits);

And $bits can now be used to test on all three handles.

# EXAMPLES

## Server

        use GT::Socket;

        my $server = GT::Socket->server({
            port => 7890
        });

        while (1) {
            if ($server->pending(-1)) {
                print "Accepting a connection\n";
                my $sock = $server->accept();
                $sock->write("The time is: " . localtime() . "\n");
            }
        }

## Client for Server

        use GT::Socket;

        my $client = GT::Socket->open("localhost:7890");
        print "Server Said: ", $client->gulpread(-1);

# COPYRIGHT

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

# VERSION

Revision: $Id: Socket.pm,v 1.43 2004/08/23 20:07:44 jagerman Exp $