NAME
POE::Component::Client::TCP - a simplified TCP client
SYNOPSIS
use POE qw(Component::Client::TCP);
# Basic usage.
POE::Component::Client::TCP->new
( RemoteAddress => "127.0.0.1",
RemotePort => "chargen",
Domain => AF_INET, # Optional.
ServerInput => sub {
my $input = $_[ARG0];
print "from server: $input\n";
}
);
# Complete usage.
POE::Component::Client::TCP->new
( RemoteAddress => "127.0.0.1",
RemotePort => "chargen",
BindAddress => "127.0.0.1",
BindPort => 8192,
Domain => AF_INET, # Optional.
Connected => \&handle_connect,
ConnectError => \&handle_connect_error,
Disconnected => \&handle_disconnect,
ServerInput => \&handle_server_input,
ServerError => \&handle_server_error,
ServerFlushed => \&handle_server_flush,
Filter => "POE::Filter::Something",
InlineStates => { ... },
PackageStates => [ ... ],
ObjectStates => [ ... ],
);
# Sample callbacks.
sub handle_connect {
my ($socket, $peer_address, $peer_port) = @_[ARG0, ARG1, ARG2];
}
sub handle_connect_error {
my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2];
}
sub handle_disconnect {
# no special parameters
}
sub handle_server_input {
my $input_record = $_[ARG0];
}
sub handle_server_error {
my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2];
}
sub handle_server_flush {
# no special parameters
}
# Reserved HEAP variables:
$heap->{server} = ReadWrite wheel representing the server.
$heap->{shutdown} = Shutdown flag (check to see if shutting down).
$heap->{connected} = Connected flag (check to see if session is connected).
$heap->{shutdown_on_error} = Automatically disconnect on error.
# Accepted public events.
$kernel->yield( "shutdown" ) # shut down a connection
$kernel->yield( "reconnect" ) # reconnect to a server
# Responding to a server.
$heap->{server}->put(@things_to_send);
DESCRIPTION
The TCP client component hides the steps needed to create a client using Wheel::SocketFactory and Wheel::ReadWrite. The steps aren't many, but they're still tiresome after a while.
POE::Component::Client::TCP supplies common defaults for most callbacks and handlers. The authors hope that clients can be created with as little work as possible.
Constructor Parameters
- Alias
-
Alias is an optional component alias. It's used to post events to the TCP client component from other sessions. The most common use of Alias is to allow a client component to receive "shutdown" and "reconnect" events from a user interface session.
- BindAddress
- BindPort
-
Specifies the local interface address and/or port to bind to before connecting. This allows the client's connection to come from specific addresses on a multi-host system.
- ConnectError
-
ConnectError is an optional callback to handle SocketFactory errors. These errors happen when a socket can't be created or connected to a remote host.
ConnectError must contain a subroutine reference. The subroutine will be called as a SocketFactory error handler. In addition to the usual POE event parameters, ARG0 will contain the name of the syscall that failed. ARG1 will contain the numeric version of $! after the failure, and ARG2 will contain $!'s string version.
Depending on the nature of the error and the type of client, it may be useful to post a reconnect event from ConnectError's callback.
sub handle_connect_error { $_[KERNEL]->delay( reconnect => 60 ); }
The component will shut down after ConnectError if a reconnect isn't requested.
- Connected
-
Connected is an optional callback to notify a program that SocketFactory succeeded. This is an advisory callback, and it should not create a ReadWrite wheel itself. The component will handle setting up ReadWrite.
ARG0 contains a socket handle. It's not necessary to save this under most circumstances. ARG1 and ARG2 contain the peer address and port as returned from getpeername().
- Disconnected
-
Disconnected is an optional callback to notify a program that an established server connection has shut down. It has no special parameters.
For persistent connections, such as MUD bots or long-running services, a useful thing to do from a Disconnected handler is reconnect. For example, this reconnects after waiting a minute:
sub handle_disconnect { $_[KERNEL]->delay( reconnect => 60 ); }
The component will shut down after disconnecting if a reconnect isn't requested.
- Domain
-
Specifies the domain within which communication will take place. It selects the protocol family which should be used. Currently supported values are AF_INET, AF_INET6, PF_INET or PF_INET6. This parameter is optional and will default to AF_INET if omitted.
Note: AF_INET6 and PF_INET6 are supplied by the Socket6 module, which is available on the CPAN. You must have Socket6 loaded before POE::Component::Server::TCP will create IPv6 sockets.
- Filter
-
Filter specifies the type of filter that will parse input from a server. It may either be a scalar or a list reference. If it is a scalar, it will contain a POE::Filter class name. If it is a list reference, the first item in the list will be a POE::Filter class name, and the remaining items will be constructor parameters for the filter.
Filter is optional. The component will supply a "POE::Filter::Line" instance none is specified.
- InlineStates
-
InlineStates holds a hashref of inline coderefs to handle events. The hashref is keyed on event name. For more information, see POE::Session's create() method.
- ObjectStates
-
ObjectStates holds a list reference of objects and the events they handle. For more information, see POE::Session's create() method.
- PackageStates
-
PackageStates holds a list reference of Perl package names and the events they handle. For more information, see POE::Session's create() method.
- RemoteAddress
-
RemoteAddress contains the address to connect to. It is required and may be a host name ("poe.perl.org") a dotted quad ("127.0.0.1") or a packed socket address.
- RemotePort
-
RemotePort contains the port to connect to. It is required and may be a service name ("echo") or number (7).
- ServerError
-
ServerError is an optional callback to notify a program that an established server connection has encountered some kind of error. Like with ConnectError, it accepts the traditional error parameters:
ARG0 contains the name of the syscall that failed. ARG1 contains the numeric failure code from $!. ARG2 contains the string version of $!.
The component will shut down after a server error if a reconnect isn't requested.
- ServerFlushed
-
ServerFlushed is an optional callback to notify a program that ReadWrite's output buffers have completely flushed. It has no special parameters.
The component will shut down after a server flush if $heap->{shutdown} is set.
- ServerInput
-
ServerInput is a required callback. It is called for each input record received from a server. ARG0 contains the input record, the format of which is determined by POE::Component::Client::TCP's Filter parameter.
The ServerInput function will stop being called when $heap->{shutdown} is true.
Public Events
- reconnect
-
Instruct the TCP client component to reconnect to the server. If it's already connected, it will disconnect harshly, discarding any pending input or output data.
- shutdown
-
When a Client::TCP component receives a shutdown event, it initiates a graceful shutdown. Any subsequent server input will be ignored, and any pending output data will be flushed. Once the connection is dealt with, the component will self-destruct.
SEE ALSO
POE::Component::Server::TCP, POE::Wheel::SocketFactory, POE::Wheel::ReadWrite, POE::Filter
CAVEATS
This may not be suitable for complex client tasks.
This looks nothing like what Ann envisioned.
AUTHORS & COPYRIGHTS
POE::Component::Client::TCP is Copyright 2001 by Rocco Caputo. All rights are reserved. POE::Component::Client::TCP is free software, and it may be redistributed and/or modified under the same terms as Perl itself.
POE::Component::Client::TCP is based on code, used with permission, from Ann Barcomb <kudra@domaintje.com>.
POE::Component::Client::TCP is based on code, used with permission, from Jos Boumans <kane@cpan.org>.