GT::Socket - A simple internet socket handling interface
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);
GT::Socket provides a simple interface for tcp client/server socket services.
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
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.
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.
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
);
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
);
The following methods are available to the Client object
$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.
Closes the socket if open.
Returns true of the socket is closed.
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.
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
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
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.
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.
Takes the buffer and send it into the socket or up to the max_up limit.
Returns the number of bytes sent.
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.
The following methods are available to the Client object
Accepts an incoming connection and returns a GT::Socket client object for further interations with the client.
Returns the filehandle.
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
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.
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");
}
}
use GT::Socket;
my $client = GT::Socket->open("localhost:7890");
print "Server Said: ", $client->gulpread(-1);
Copyright (c) 2000 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/
Revision: $Id: Socket.pm,v 1.43 2004/08/23 20:07:44 jagerman Exp $