529 lines
15 KiB
HTML
529 lines
15 KiB
HTML
<!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::Client - Socket module designed for TCP clients</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>
|
|
<li><a href="#methods">METHODS</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#open">open</a></li>
|
|
<li><a href="#readline">readline</a></li>
|
|
<li><a href="#readblock">readblock</a></li>
|
|
<li><a href="#readall">readall</a></li>
|
|
<li><a href="#readalluntil">readalluntil</a></li>
|
|
<li><a href="#select_time">select_time</a></li>
|
|
<li><a href="#read_wait">read_wait</a></li>
|
|
<li><a href="#write">write</a></li>
|
|
<li><a href="#eol">eol</a></li>
|
|
<li><a href="#error">error</a></li>
|
|
<li><a href="#iaddr">iaddr</a></li>
|
|
<li><a href="#port">port</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#maintainer">MAINTAINER</a></li>
|
|
<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::Client - Socket module designed for TCP clients</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
use GT::Socket::Client qw/:crlf/;</pre>
|
|
<pre>
|
|
my $socket = GT::Socket::Client->open(
|
|
host => "gossamer-threads.com",
|
|
port => "shell", # AKA port 514
|
|
timeout => 10
|
|
) or die GT::Socket::Client->error;</pre>
|
|
<pre>
|
|
# $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;</pre>
|
|
<pre>
|
|
$sock->readblock(my $block, 4096);
|
|
print "Read 4KB from the socket: $block";
|
|
print $sock "QUIT" . CRLF;</pre>
|
|
<pre>
|
|
$sock->readall(my $all);
|
|
print "Everything else from the socket: $all";
|
|
print $sock "Something else" . CRLF;</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="methods">METHODS</a></h1>
|
|
<p>
|
|
</p>
|
|
<h2><a name="open">open</a></h2>
|
|
<p>Takes a hash (not hash reference) of socket options, as follows:</p>
|
|
<dl>
|
|
<dt><strong><a name="item_host">host</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
[REQUIRED] The name or IP of the host to connect to.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_port">port</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
[REQUIRED] The numeric value (25) or service name (``smtp'') of the port to
|
|
connect to.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_ssl">ssl</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
[OPTIONAL] If this option is provided, the connection will use SSL. Note that
|
|
this requires the Net::SSLeay module.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_timeout">timeout</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
[OPTIONAL] A connection timeout period, in integral seconds. Note that this is
|
|
only supported on systems that support the <code>alarm()</code> function; on other systems
|
|
(such as Windows), this argument has no effect.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_non_blocking">non_blocking</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
[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 <strong>DOES NOT WORK</strong>
|
|
with the ssl option, due to the Net::SSLeay interface.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_autoflush">autoflush</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
[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.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong>ssl</strong><br />
|
|
</dt>
|
|
<dd>
|
|
[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.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_debug">debug</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
[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 <code>error()</code> 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.
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="readline">readline</a></h2>
|
|
<p>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 <code>eol()</code> 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 <code>read_wait()</code> method.</p>
|
|
<p>1 is returned on success, undef on failure.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="readblock">readblock</a></h2>
|
|
<p>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 <code>read_wait</code> seconds (See <a href="#read_wait">read_wait</a>).</p>
|
|
<p>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 <code>read_wait()</code> is hit.</p>
|
|
<p>The number of bytes read is returned on success, undef on failure.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="readall">readall</a></h2>
|
|
<p>A synonym for <code>$obj->readblock($_[0], -1)</code> - in other words, it reads all
|
|
available data (waiting for up to <code>read_wait</code> seconds, if non-blocking).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="readalluntil">readalluntil</a></h2>
|
|
<p>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.</p>
|
|
<p>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: <code>"\n.\r\n"</code>. 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 <code>".\r\n"</code> - to handle an empty
|
|
response.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="select_time">select_time</a></h2>
|
|
<p>[Non-blocking sockets only] This adjusts the number of seconds passed to
|
|
<code>select()</code> to poll the socket for available data. The default value is 0.05,
|
|
which should work in most situations.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="read_wait">read_wait</a></h2>
|
|
<p>[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.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="write">write</a></h2>
|
|
<p>Sends data to the server. Takes the data to send. This does The Right Thing
|
|
for either non-blocking or blocking sockets.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="eol">eol</a></h2>
|
|
<p>This method takes one or more character, and uses it for the EOL <code>character(s)</code>
|
|
used by readline. If called without any argument, the EOL character for the
|
|
current object is returned.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="error">error</a></h2>
|
|
<p>If an error (such as connection, socket, etc.) occurs, you can access it via
|
|
the <code>error()</code> method. This can be called as either a class or instance method,
|
|
since <code>open()</code> return <code>undef</code> instead of an object if the connection fails.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="iaddr">iaddr</a></h2>
|
|
<p>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
|
|
<em>Socket.pm</em>'s inet_aton function.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="port">port</a></h2>
|
|
<p>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 <a href="#item_port"><code>port</code></a> option passed to <code>open()</code> - the return value of this function will
|
|
always be numeric (e.g. <code>25</code>), even if a service name (e.g. <code>"smtp"</code>) was
|
|
passed to open().</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/Socket.html">the GT::Socket manpage</a> - A socket module made for Links SQL.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="maintainer">MAINTAINER</a></h1>
|
|
<p>Jason Rhinelander</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 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: Client.pm,v 1.15 2004/02/17 01:33:07 jagerman Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|