Socket-Class
view release on metacpan or search on metacpan
"GET / HTTP/1.0\r\n" .
"User-Agent: Not Mozilla\r\n" .
"Host: www.perl.org\r\n" .
"Connection: Close\r\n" .
"\r\n"
) or die $sock->error;
# read the response (1MB max)
$sock->read( $buf, 1048576 )
or die $sock->error;
# do something with the response
print $buf;
# close the socket an free its resources
$sock->free();
=head2 Bluetooth RFCOMM Client
use Socket::Class;
# create a new socket and connect to a bluetooth device
$sock = Socket::Class->new(
'domain' => 'bluetooth',
'type' => 'stream',
'proto' => 'rfcomm',
'remote_addr' => '00:16:20:66:F2:6C',
'remote_port' => 1, # channel
) or die Socket::Class->error;
# do something with the socket
$sock->send( "bluetooth works" );
...
# close the connection and free its resources
$sock->free();
=head1 METHODS
=head2 Constructing
=over 4
=item B<new ( [%arg] )>
Creates a Socket::Class object, which is a reference to a newly created socket
handle. I<new()> optionally takes arguments, these arguments must set as
key-value pairs.
=for formatter none
remote_addr Remote host address <hostname> | <hostaddr>
remote_port Remote port or service <service> | <number>
remote_path Remote path for unix sockets "/tmp/mysql.sock"
local_addr Local host bind address <hostname> | <hostaddr>
local_port Local host bind port <service> | <number>
local_path Local path for unix sockets "/tmp/myserver.sock"
domain Socket domain name (or number) "inet" | "inet6" | ...
proto Protocol name (or number) "tcp" | "udp" | ...
type Socket type name (or number) "stream" | "dgram" | ...
listen Put socket into listen state with a specified maximal
number of connections in the queue
broadcast Set SO_BROADCAST before binding
reuseaddr Set SO_REUSEADDR before binding
blocking Enable or disable blocking mode; default is enabled
timeout Timeout value for various operations as floating point
number;
defaults to 15000 (15 seconds); currently used by connect
=for formatter perl
If I<local_addr>, I<local_port> or I<local_path> is defined, then the socket
will bind a local address. If I<listen> is defined, then the socket will put
into listen state. If I<remote_addr>, I<remote_port> or I<remote_path> is
defined then I<connect()> is called.
Standard I<domain> is AF_INET. Standard socket I<type> is SOCK_STREAM.
Standard I<proto> is IPPROTO_TCP. If I<local_path> or I<remote_path> is
defined, then the standard domain becomes AF_UNIX and the standard
protocol becomes 0.
B<Examples>
I<Create a nonblocking listening inet socket on a random local port>
$sock = Socket::Class->new(
'listen' => 5,
'blocking' => 0,
) or die Socket::Class->error;
print "listen on local port ", $sock->local_port, "\n";
I<Create a listening unix socket>
$sock = Socket::Class->new(
'domain' => 'unix',
'local_path' => '/tmp/myserver.sock',
'listen' => 5,
) or die Socket::Class->error;
I<Connect to smtp service (port 25) on localhost>
$sock = Socket::Class->new(
'remote_addr' => 'localhost',
'remote_port' => 'smtp',
) or die Socket::Class->error;
I<Create a broadcast socket>
$sock = Socket::Class->new(
'remote_addr' => '255.255.255.255',
'remote_port' => 9999,
'proto' => 'udp',
'local_addr' => 'localhost',
'broadcast' => 1,
) or die Socket::Class->error;
One of the following values that specifies the operation that will no longer
be allowed. Default is I<SD_SEND>.
=for formatter none
Num Const Description
----------------------------------------------------------------------
0 SD_SEND Disable sending on the socket.
1 SD_RECEIVE Disable receiving on the socket.
2 SD_BOTH Disable both sending and receiving on the socket.
=for formatter perl
B<Return Values>
Returns a true value on sucess or undef on failure.
Use L<errno()|Socket::Class/errno> and L<error()|Socket::Class/error>
to retrieve the error code and message.
B<Examples>
use Socket::Class qw(SD_BOTH);
$sock = Socket::Class->new( ... );
...
$sock->shutdown( SD_BOTH );
$sock->free();
=item B<close ()>
Closes the socket without freeing internal resources.
=item B<free ()>
Closes the socket and frees all internally allocated resources.
=back
=head2 Bind, Listen and Accept
=over 4
=item B<bind ( [$addr [, $port]] )>
=item B<bind ( [$path] )>
Binds the socket to a specified local address.
B<Parameters>
I<$addr> or I<$path>
On 'inet' family sockets the I<$addr> parameter can be an IP address in
dotted-quad notation (e.g. 127.0.0.1) or a valid hostname.
On 'inet6' family sockets the I<$addr> parameter can be an IPv6 address in
hexadecimal notation (e.g. 2001:0db8:85a3:08d3:1319:8a2e:0370:7344) or a
valid hostname.
On 'unix' family sockets the I<$path> is the pathname of a Unix domain socket.
If I<$addr> is not defined the address from last I<bind> is used.
I<$port>
The I<$port> parameter designates the port or channel on the local host.
B<Return Values>
Returns a true value on sucess or undef on failure.
Use L<errno()|Socket::Class/errno> and L<error()|Socket::Class/error>
to retrieve the error code and message.
B<Examples>
$sock->bind( '0.0.0.0', 9999 )
or die "can't bind: " . $sock->error;
=item B<listen ( [$backlog] )>
Listens for a connection on a socket.
B<Parameters>
I<$backlog>
A maximum of backlog incoming connections will be queued for processing.
If a connection request arrives with the queue full the client may
receive an error with an indication of ECONNREFUSED, or, if the
underlying protocol supports retransmission, the request may be ignored
so that retries may succeed.
B<Return Values>
Returns a true value on sucess or undef on failure.
Use L<errno()|Socket::Class/errno> and L<error()|Socket::Class/error>
to retrieve the error code and message.
B<Examples>
use Socket::Class qw(SOMAXCONN);
...
$sock->listen( SOMAXCONN )
or die $sock->error;
=item B<accept ()>
Accepts a connection on a bound socket. Once a successful connection is made,
a new socket resource is returned, which may be used for communication.
If there are multiple connections queued on the socket, the first will be
used. If there are no pending connections, accept() will block until a
connection becomes present. If socket has been made non-blocking using
set_blocking(), 0 will be returned.
B<Return Values>
Returns a new socket class on sucess or 0 on non-blocking mode and no new
connection becomes available or UNDEF on failure.
Use L<errno()|Socket::Class/errno> and L<error()|Socket::Class/error>
to retrieve the error code and message.
B<Examples>
I<Blocking mode (default)>
while( $client = $sock->accept() ) {
# do something with the connection
print "Incoming connection: ", $client->to_string, "\n";
...
$client->free();
}
I<Non blocking mode>
while( 1 ) {
$client = $sock->accept();
if( ! defined $client ) {
# error
die $sock->error;
}
elsif( ! $client ) {
# no client, sleep for a while
$sock->wait( 10 );
next;
}
# do something with the connection
print "Incoming connection: ", $client->to_string, "\n";
...
$client->free();
}
=back
=head2 Connect
=over 4
=item B<connect ( [$addr [, $port [, $timeout]]] )>
=item B<connect ( [$path [,$timeout]] )>
Initiates a connection.
B<Parameters>
I<$addr> or I<$path>
On 'inet' family sockets the I<$addr> parameter can be an IP address in
dotted-quad notation (e.g. 127.0.0.1) or a valid hostname.
On 'inet6' family sockets the I<$addr> parameter can be an IPv6 address in
hexadecimal notation (e.g. 2001:0db8:85a3:08d3:1319:8a2e:0370:7344) or a
valid hostname.
On 'unix' family sockets the I<$path> is the pathname of a Unix domain socket.
If I<$addr> is not defined the address from last I<connect> is used.
I<$port>
The I<$port> parameter designates the port or service on the remote host to
which a connection should be made.
I<$timeout>
Optionally timeout in milliseconds as floating point number.
B<Return Values>
Returns a TRUE value on sucess or UNDEF on failure.
Use L<errno()|Socket::Class/errno> and L<error()|Socket::Class/error>
to retrieve the error code and message.
B<Examples>
$sock->connect( 'www.perl.org', 'http' )
or die "can't connect: " . $sock->error;
=item B<reconnect ( [$timeout] )>
Closes the current connection, waits I<$timeout> milliseconds and
reconnects the socket to the connection previously made.
B<Return Values>
Returns a true value on sucess or undef on failure.
Use L<errno()|Socket::Class/errno> and L<error()|Socket::Class/error>
to retrieve the error code and message.
B<Examples>
if( $sock->is_error ) {
retry:
print "socket error: ", $sock->error, "\n";
# try to reconnect
$r = $sock->reconnect( 1000 );
if( ! $r ) {
# can't connect
goto retry;
}
}
=back
=head2 Low level sending and receiving data
=over 4
=item B<send ( $buf [, $flags] )>
( run in 0.520 second using v1.01-cache-2.11-cpan-e1769b4cff6 )