POE::Component::Client::TCP(3)

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.
      Alias         => $session_alias  # Optional.
      ServerInput   => sub {
        my $input = $_[ARG0];
        print "from server: $input\n";
      }
    );

  # Complete usage.

  my $session_id = POE::Component::Client::TCP->new
    ( RemoteAddress  => "127.0.0.1",
      RemotePort     => "chargen",
      BindAddress    => "127.0.0.1",
      BindPort       => 8192,
      Domain         => AF_INET,        # Optional.
      Alias          => $session_alias  # Optional.
      ConnectTimeout => 5,              # Seconds; optional.

      SessionType   => "POE::Session::Abc",           # Optional.
      SessionParams => [ options => { debug => 1 } ], # Optional.

      Started        => \&handle_starting,   # Optional.
      Args           => [ "arg0", "arg1" ],  # Optional.  Start args.

      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_start {
    my @args = @_[ARG0..$#_];
  }

  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( "connect", $host, $port )  # connect to a new host/port
  $kernel->yield( "reconnect" )  # reconnect to the previous host/port
  $kernel->yield( "shutdown" )   # shut down a connection gracefully

  # 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

new The new() method can accept quite a lot of parameters. It will return the session ID of the accecptor session. One must use callbacks to check for errors rather than the return value of new().

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.

SessionType
    SessionType specifies what type of sessions will be created within the TCP server. It must be a scalar value.

      SessionType => "POE::Session::MultiDispatch"

    SessionType is optional. The component will supply a "POE::Session" type if none is specified.

SessionParams
    Initialize parameters to be passed to the SessionType when it is created. This must be an array reference.

      SessionParams => [ options => { debug => 1, trace => 1 } ],

    It is important to realize that some of the arguments to SessionHandler may get clobbered when defining them for your SessionHandler. It is advised that you stick to defining arguments in the "options" hash such as trace and debug. See POE::Session for an example list of options.

Args ARRAYREF
    Args passes the contents of a ARRAYREF to the Started callback via @_[ARG0..$#_]. It allows a program to pass extra information to the session created to handle the client connection.

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().

ConnectTimeout
    ConnectTimeout is the maximum time in seconds to wait for a connection to be established. If it is omitted, Client::TCP relies on the operating system to abort stalled connect() calls.

    Upon a connection timeout, Client::TCP will send a ConnectError event. Its ARG0 will be 'connect' and ARG1 will be the POSIX/Errno ETIMEDOUT value.

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, a list reference or a POE::Filter reference. If it is a scalar, it will contain a POE::Filter class name.

      Filter => "POE::Filter::Line",

    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. For example, this changes the line separator to a vertical pipe:

      Filter => [ "POE::Filter::Line", Literal => "|" ],

    If it is an object, it will be clone()'d.

      Filter => POE::Filter::Line->new()

    Filter is optional. The component will supply a "POE::Filter::Line" instance none is specified. If you supply a different value for Filter, then you must also "use" that filter class.

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.

Started
    Started is an optional callback. It is called after Client::TCP is initialized but before a connection has been established.

    The Args parameter can be used to pass initialization values to the Started callback, eliminating the need for closures to get values into the component. These values are included in the @_[ARG0..$#_] parameters.

Public Events

connect
    Cause the TCP client to connect, optionally providing a new RemoteHost and RemotePort (which will also be used for subsequent "reconnect"s. If the client is already connected, it will disconnect harshly, as with reconnect, discarding any pending input or output.

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. After a point, it becomes easier to roll a custom client using POE::Wheel::SocketFactory and POE::Wheel::ReadWrite.

This looks nothing like what Ann envisioned.

AUTHORS & COPYRIGHTS
POE::Component::Client::TCP is Copyright 2001-2006 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>.