POE::Wheel::ListenAccept - phpMan

NAME
    POE::Wheel::ListenAccept - accept connections from regular listening
    sockets

SYNOPSIS
    See "SYNOPSIS" in POE::Wheel::SocketFactory for a simpler version of
    this program.

      #!perl

      use warnings;
      use strict;

      use IO::Socket;
      use POE qw(Wheel::ListenAccept Wheel::ReadWrite);

      POE::Session->create(
        inline_states => {
          _start => sub {
            # Start the server.
            $_[HEAP]{server} = POE::Wheel::ListenAccept->new(
              Handle => IO::Socket::INET->new(
                LocalPort => 12345,
                Listen => 5,
              ),
              AcceptEvent => "on_client_accept",
              ErrorEvent => "on_server_error",
            );
          },
          on_client_accept => sub {
            # Begin interacting with the client.
            my $client_socket = $_[ARG0];
            my $io_wheel = POE::Wheel::ReadWrite->new(
              Handle => $client_socket,
              InputEvent => "on_client_input",
              ErrorEvent => "on_client_error",
            );
            $_[HEAP]{client}{ $io_wheel->ID() } = $io_wheel;
          },
          on_server_error => sub {
            # Shut down server.
            my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2];
            warn "Server $operation error $errnum: $errstr\n";
            delete $_[HEAP]{server};
          },
          on_client_input => sub {
            # Handle client input.
            my ($input, $wheel_id) = @_[ARG0, ARG1];
            $input =~ tr[a-zA-Z][n-za-mN-ZA-M]; # ASCII rot13
            $_[HEAP]{client}{$wheel_id}->put($input);
          },
          on_client_error => sub {
            # Handle client error, including disconnect.
            my $wheel_id = $_[ARG3];
            delete $_[HEAP]{client}{$wheel_id};
          },
        }
      );

      POE::Kernel->run();
      exit;

DESCRIPTION
    POE::Wheel::ListenAccept implements non-blocking accept() calls for
    plain old listening server sockets. The application provides the socket,
    using some normal means such as socket(), IO::Socket::INET, or
    IO::Socket::UNIX. POE::Wheel::ListenAccept monitors the listening socket
    and emits events whenever a new client has been accepted.

    Please see POE::Wheel::SocketFactory if you need non-blocking connect()
    or a more featureful listen/accept solution.

    POE::Wheel::ListenAccept only accepts client connections. It does not
    read or write data, so it neither needs nor includes a put() method.
    POE::Wheel::ReadWrite generally handles the accepted client socket.

PUBLIC METHODS
  new
    new() creates a new POE::Wheel::ListenAccept object for a given
    listening socket. The object will generate events relating to the socket
    for as long as it exists.

    new() accepts two required named parameters:

   Handle
    The "Handle" constructor parameter must contain a listening socket
    handle. POE::Wheel::FollowTail will monitor this socket and accept() new
    connections as they arrive.

   AcceptEvent
    "AcceptEvent" is a required event name that POE::Wheel::ListenAccept
    will emit for each accepted client socket. "PUBLIC EVENTS" describes it
    in detail

   ErrorEvent
    "ErrorEvent" is an optional event name that will be emitted whenever a
    serious problem occurs. Please see "PUBLIC EVENTS" for more details.

  event
    event() allows a session to change the events emitted by a wheel without
    destroying and re-creating the object. It accepts one or more of the
    events listed in "PUBLIC EVENTS". Undefined event names disable those
    events.

    Ignore connections:

      sub ignore_new_connections {
        $_[HEAP]{tailor}->event( AcceptEvent => "on_ignored_accept" );
      }

      sub handle_ignored_accept {
        # does nothing
      }

  ID
    The ID() method returns the wheel's unique ID. It's useful for storing
    the wheel in a hash. All POE::Wheel events should be accompanied by a
    wheel ID, which allows the wheel to be referenced in their event
    handlers.

      sub setup_listener {
        my $wheel = POE::Wheel::ListenAccept->new(... etc  ...);
        $_[HEAP]{listeners}{$wheel->ID} = $wheel;
      }

PUBLIC EVENTS
    POE::Wheel::ListenAccept emits a couple events.

  AcceptEvent
    "AcceptEvent" names the event that will be emitted for each newly
    accepted client socket. It is accompanied by three parameters:

    $_[ARG0] contains the newly accepted client socket handle. It's up to
    the application to do something with this socket. Most use cases involve
    passing the socket to a POE::Wheel::ReadWrite constructor.

    $_[ARG1] contains the accept() call's return value, which is often the
    encoded remote end of the remote end of the socket.

    $_[ARG2] contains the POE::Wheel::ListenAccept object's unique ID. This
    is the same value as returned by the wheel's ID() method.

    A sample "AcceptEvent" handler:

      sub accept_state {
        my ($client_socket, $remote_addr, $wheel_id) = @_[ARG0..ARG2];

        # Make the remote address human readable.
        my ($port, $packed_ip) = sockaddr_in($remote_addr);
        my $dotted_quad = inet_ntoa($packed_ip);

        print(
          "Wheel $wheel_id accepted a connection from ",
          "$dotted_quad port $port.\n"
        );

        # Spawn off a session to interact with the socket.
        create_server_session($handle);
      }

  ErrorEvent
    "ErrorEvent" names the event that will be generated whenever a new
    connection could not be successfully accepted. This event is accompanied
    by four parameters:

    $_[ARG0] contains the name of the operation that failed. This usually is
    'accept', but be aware that it's not necessarily a function name.

    $_[ARG1] and $_[ARG2] hold the numeric and stringified values of $!,
    respectively. POE::Wheel::ListenAccept knows how to handle EAGAIN (and
    system-dependent equivalents), so this error will never be returned.

    $_[ARG3] contains the wheel's unique ID, which may be useful for
    shutting down one particular wheel out of a group of them.

    A sample "ErrorEvent" event handler. This assumes the wheels are saved
    as in the "ID" example.

      sub error_state {
        my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
        warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
        delete $_[HEAP]{listeners}{$wheel_id};
      }

SEE ALSO
    POE::Wheel describes the basic operations of all wheels in more depth.
    You need to know this.

    POE::Wheel::ReadWrite for one possible way to handle clients once you
    have their sockets.

    The SEE ALSO section in POE contains a table of contents covering the
    entire POE distribution.

BUGS
    None known.

AUTHORS & COPYRIGHTS
    Please see POE for more information about authors and contributors.