<!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>