<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>GT::Socket - A simple internet socket handling interface</title>
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
<style type="text/css">
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
/* $MVD$:fontset("Arial","Arial") */
/* $MVD$:fontset("Arial Black","Arial Black") */
/* $MVD$:fontset("Algerian","Algerian") */
body {
background-color: white;
font-family: Verdana, Arial, sans-serif;
font-size: small;
color: black;
}
p {
background-color : white;
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
h1 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : medium;
background-color : white;
color : maroon;
}
h2 {
font-family : Verdana, Arial, sans-serif;
font-size : medium;
font-weight : bold;
color : blue;
background-color : white;
}
h3 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : medium;
color : black;
background-color : white;
}
h4 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : small;
color : maroon;
background-color : white;
}
h5 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : small;
color : blue;
background-color : white;
}
h6 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : small;
color : black;
background-color : white;
}
ul {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
ol {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dl {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
li {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
th {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
td {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dl {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dd {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
dt {
font-family : Verdana, Arial, sans-serif;
font-size : small;
color : black;
}
code {
font-family : Courier;
font-size : small;
color : black;
}
pre {
font-family : Courier;
font-size : small;
color : black;
}
.mvd-H1 {
font-family : Verdana, Arial, sans-serif;
font-weight : bold;
font-size : 14.0pt;
background-color : transparent;
background-image : none;
color : maroon;
}
.mvd-H2 {
font-family : Verdana, Arial, sans-serif;
font-size : 12.0pt;
color : blue;
}
p.indent {
font-family : "Verdana, Arial, sans-serif";
list-style-type : circle;
list-style-position : inside;
color : black;
margin-left : 16.0pt;
}
.mvd-P-indent {
font-family : Verdana, Arial, sans-serif;
list-style-type : circle;
list-style-position : inside;
color : black;
margin-left : 16.0pt;
}
pre.programlisting {
font-size : 9.0pt;
list-style-type : disc;
margin-left : 16.0pt;
margin-top : -14.0pt;
}
.mvd-PRE-programlisting {
font-size : 9.0pt;
list-style-type : disc;
margin-left : 16.0pt;
margin-top : -14.0pt;
}
.mvd-PRE {
font-size : 9.0pt;
}
p.note {
margin-left : 28.0pt;
}
.mvd-P-note {
margin-left : 28.0pt;
}
.mvd-H4 {
font-family : Verdana, Arial, sans-serif;
font-weight : normal;
font-size : 9.0pt;
color : black;
margin-left : 6.0pt;
margin-top : -14.0pt;
}
.mvd-P {
font-family : Verdana, Arial, sans-serif;
font-size : 10.0pt;
color : black;
}
.mvd-BODY {
font-family : Verdana, Arial, sans-serif;
background-color : white;
}
p.indentnobullet {
font-family : Verdana, Arial, sans-serif;
list-style-type : none;
}
.mvd-P-indentnobullet {
font-family : Verdana, Arial, sans-serif;
list-style-type : none;
}
</style>
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#method_list">Method List</a></li>
<li><a href="#creating_a_new_client_socket">Creating a new Client Socket</a></li>
<li><a href="#limiting_maximum_amount_of_data_downloaded">Limiting maximum amount of data downloaded</a></li>
<li><a href="#limiting_maximum_amount_of_data_uploaded">Limiting maximum amount of data uploaded</a></li>
<li><a href="#limiting_time_taken_to_connect_to_a_host">Limiting time taken to connect to a host</a></li>
<li><a href="#methods">Methods</a></li>
<li><a href="#autoflush___flag_boolean__">autoflush ( flag BOOLEAN )</a></li>
<li><a href="#close">close</a></li>
<li><a href="#eof">EOF</a></li>
<li><a href="#fh">fh</a></li>
<li><a href="#gulpread___tics_integer__">gulpread ( tics INTEGER )</a></li>
<li><a href="#pending___tics_integer__">pending ( tics INTEGER )</a></li>
<li><a href="#read___number_bytes_integer__">read ( number_bytes INTEGER )</a></li>
<li><a href="#vec_____bits_scalar____">vec ( [ bits SCALAR ] )</a></li>
<li><a href="#write___buffer_scalar__">write ( buffer SCALAR )</a></li>
<li><a href="#creating_a_new_server_socket">Creating a new Server Socket</a></li>
<li><a href="#methods">Methods</a></li>
<li><a href="#accept">accept</a></li>
<li><a href="#fh">fh</a></li>
<li><a href="#pending___tics_integer__">pending ( tics INTEGER )</a></li>
<li><a href="#vec_____bits_scalar____">vec ( [ bits SCALAR ] )</a></li>
</ul>
<li><a href="#examples">EXAMPLES</a></li>
<ul>
<li><a href="#server">Server</a></li>
<li><a href="#client_for_server">Client for Server</a></li>
</ul>
<li><a href="#copyright">COPYRIGHT</a></li>
<li><a href="#version">VERSION</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>GT::Socket - A simple internet socket handling interface</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
use GT::Socket;</pre>
<pre>
my $sock = GT::Socket->open({
host => 'www.gossamer-threads.com',
port => 80
});</pre>
<pre>
$sock->write("GET / HTTP/1.0\n\n");</pre>
<pre>
print "REQUEST RETURNED:\n\n", $sock->gulpread(-1);</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>GT::Socket provides a simple interface for tcp client/server socket services.</p>
<p>
</p>
<h2><a name="method_list">Method List</a></h2>
<p>Object Creation</p>
<pre>
open() Creates a new client socket
server() Creates a new server socket</pre>
<p>Reading and Writing</p>
<pre>
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</pre>
<p>Socket Administration</p>
<pre>
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</pre>
<p>Server Handling</p>
<pre>
accept() Accepts a incoming client request</pre>
<p>
</p>
<h2><a name="creating_a_new_client_socket">Creating a new Client Socket</a></h2>
<p>To instantiate a new Client Socket connection, the <code>open()</code> method must be
called.</p>
<pre>
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)
});</pre>
<p>The parameters are somewhat flexible, to connect to www.gossamer-threads.com on
port 80, any of the following calling methods can be used.</p>
<pre>
my $sock = GT::Socket->open({
host => 'www.gossamer-threads.com',
port => 80
});</pre>
<pre>
my $sock = GT::Socket->open(
host => 'www.gossamer-threads.com',
port => 80
);</pre>
<pre>
my $sock = GT::Socket->open('www.gossamer-threads.com', 80);</pre>
<pre>
my $sock = GT::Socket->open('www.gossamer-threads.com:80');</pre>
<p>Note that as port 80 is the HTTP port, and port gets tested and handled with
the getservbyname function, the following can be done:</p>
<pre>
# 'http' here but can be 'pop3', 'telnet', etc. depending on service wanted
my $sock = GT::Socket->open('www.gossamer-threads.com', 'http');</pre>
<p>Note that if the value passed to <code>open()</code> is a hash ref, with a host and port, a
handful of other options may be set.</p>
<p>
</p>
<h2><a name="limiting_maximum_amount_of_data_downloaded">Limiting maximum amount of data downloaded</a></h2>
<p>This affects the $sock-><code>read()</code> and the $sock-><code>gulpread()</code> methods.</p>
<p>The option 'max_down' can be used to put a cap on the number of bytes recieved
through the socket.</p>
<p>For example to limit the number of bytes downloaded to 2k, set max_down to 2048</p>
<pre>
my $sock = GT::Socket->open(
host => 'www.gossamer-threads.com',
port => 80,
max_down => 2048
);</pre>
<p>WARNING, once the download maximum has been reached, the socket is closed. Then
no more information can be uploaded to the remote host.</p>
<p>
</p>
<h2><a name="limiting_maximum_amount_of_data_uploaded">Limiting maximum amount of data uploaded</a></h2>
<p>The option 'max_up' is used to limit the number of bytes that can be sent to
the remote host.</p>
<p>After the maximum number of bytes is hit, the object will no longer carry out
$sock-><code>write()</code> requests.</p>
<p>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.</p>
<p>In the following example. The maximum number of bytes for both download and
upload have been set to 2K.</p>
<p>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-><code>write()</code> as well!</p>
<pre>
my $sock = GT::Socket->open(
host => 'www.gossamer-threads.com',
port => 80,
max_down => 2048,
max_up => 2048
);</pre>
<p>
</p>
<h2><a name="limiting_time_taken_to_connect_to_a_host">Limiting time taken to connect to a host</a></h2>
<p>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.</p>
<p>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.</p>
<p>Since this uses alarm, it will not function on Win32 machines.</p>
<p>With the following example, the module will spend a maximum of 3 seconds trying
to connect to www.gossamer-threads.com.</p>
<pre>
my $sock = GT::Socket->open(
host => 'www.gossamer-threads.com',
port => 80,
timeout => 3
);</pre>
<p>
</p>
<h2><a name="methods">Methods</a></h2>
<p>The following methods are available to the Client object</p>
<p>
</p>
<h2><a name="autoflush___flag_boolean__">autoflush ( flag BOOLEAN )</a></h2>
<pre>
$sock->autoflush(1) # turn on flushing
$sock->autoflush(0) # turn off flushing</pre>
<p>Turns off buffering for the socket. By default, the socket is
autoflushed/buffering turned off.</p>
<p>This prevents peculiar errors like stalling when trying to communicate with
http servers.</p>
<p>
</p>
<h2><a name="close">close</a></h2>
<p>Closes the socket if open.</p>
<p>
</p>
<h2><a name="eof">EOF</a></h2>
<p>Returns true of the socket is closed.</p>
<p>
</p>
<h2><a name="fh">fh</a></h2>
<p>Returns the filehandle.</p>
<p>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.</p>
<p>
</p>
<h2><a name="gulpread___tics_integer__">gulpread ( tics INTEGER )</a></h2>
<p>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.</p>
<p>Tics is a non-zero value that will determine how long the function will run for
or wait:</p>
<pre>
$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</pre>
<p>
</p>
<h2><a name="pending___tics_integer__">pending ( tics INTEGER )</a></h2>
<p>Returns true if socket has data pending to be received. Usually this would be
followed with a call to $sock-><code>gulpread()</code> or $sock-><code>read()</code></p>
<pre>
$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</pre>
<p>
</p>
<h2><a name="read___number_bytes_integer__">read ( number_bytes INTEGER )</a></h2>
<p>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.</p>
<p>
</p>
<h2><a name="vec_____bits_scalar____">vec ( [ bits SCALAR ] )</a></h2>
<p>Sets the bits appropriate for the object's socket handle. The returned value
can be used in <code>select(RBITS,WBITS,EBITS,TIMEOUT)</code> function calls.</p>
<p>To test a series of socket handles, vec accepts an already set bit list from
another vec call.</p>
<pre>
$bits = $sock1->vec();
$bits = $sock2->vec($bits);
$bits = $sock3->vec($bits);</pre>
<p>And $bits can now be used to test on all three handles.</p>
<p>
</p>
<h2><a name="write___buffer_scalar__">write ( buffer SCALAR )</a></h2>
<p>Takes the buffer and send it into the socket or up to the max_up limit.</p>
<p>Returns the number of bytes sent.</p>
<p>
</p>
<h2><a name="creating_a_new_server_socket">Creating a new Server Socket</a></h2>
<p>Creating a server socket is almost identical to creating a client socket except
no hostname is specified.
</p>
<pre>
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)
});</pre>
<p>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.</p>
<p>
</p>
<h2><a name="methods">Methods</a></h2>
<p>The following methods are available to the Client object</p>
<p>
</p>
<h2><a name="accept">accept</a></h2>
<p>Accepts an incoming connection and returns a GT::Socket client object for
further interations with the client.</p>
<p>
</p>
<h2><a name="fh">fh</a></h2>
<p>Returns the filehandle.</p>
<p>
</p>
<h2><a name="pending___tics_integer__">pending ( tics INTEGER )</a></h2>
<p>Returns true if server has awaiting connections. Usually this would be followed
with a call to $server->accept();</p>
<pre>
$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</pre>
<p>
</p>
<h2><a name="vec_____bits_scalar____">vec ( [ bits SCALAR ] )</a></h2>
<p>Sets the bits appropriate for the object's socket handle. The returned value
can be used in <code>select(RBITS,WBITS,EBITS,TIMEOUT)</code> function calls.</p>
<p>To test a series of socket handles, vec accepts an already set bit list from
another vec call.</p>
<pre>
$bits = $sock1->vec();
$bits = $sock2->vec($bits);
$bits = $sock3->vec($bits);</pre>
<p>And $bits can now be used to test on all three handles.</p>
<p>
</p>
<hr />
<h1><a name="examples">EXAMPLES</a></h1>
<p>
</p>
<h2><a name="server">Server</a></h2>
<pre>
use GT::Socket;</pre>
<pre>
my $server = GT::Socket->server({
port => 7890
});</pre>
<pre>
while (1) {
if ($server->pending(-1)) {
print "Accepting a connection\n";
my $sock = $server->accept();
$sock->write("The time is: " . localtime() . "\n");
}
}</pre>
<p>
</p>
<h2><a name="client_for_server">Client for Server</a></h2>
<pre>
use GT::Socket;</pre>
<pre>
my $client = GT::Socket->open("localhost:7890");
print "Server Said: ", $client->gulpread(-1);</pre>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright (c) 2000 Gossamer Threads Inc. All Rights Reserved.
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
<p>
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
<p>Revision: $Id: Socket.pm,v 1.43 2004/08/23 20:07:44 jagerman Exp $</p>
</body>
</html>