NAME

POE::Component::Server::IRC::Backend - A POE component class that provides network connection abstraction for POE::Component::Server::IRC.

SYNOPSIS

  use POE qw(Component::Server::IRC::Backend);

  my $object = POE::Component::Server::IRC::Backend->create();

  POE::Session->create(
        package_states => [
                'main' => [ qw(_start) ],
        ],
        heap => { ircd => $object },
  );

  $poe_kernel->run();
  exit 0;

  sub _start {
  }

DESCRIPTION

POE::Component::Server::IRC::Backend - A POE component class that provides network connection abstraction for POE::Component::Server::IRC.

CONSTRUCTOR

create

Returns an object. Accepts the following parameters, all are optional:

  'alias', a POE::Kernel alias to set;
  'auth', set to 0 to globally disable IRC authentication, default is auth is enabled;
  'antiflood', set to 0 to globally disable flood protection;
  'prefix', this is the prefix that is used to generate event names that the component produces, 
            the default is 'ircd_backend_'.

  my $object = POE::Component::Server::IRC::Backend->create( 
        alias => 'ircd', # Set an alias, default, no alias set.
        auth  => 0, # Disable auth globally, default enabled.
        antiflood => 0, # Disable flood protection globally, default enabled.
  );

If the component is created from within another session, that session will be automagcially registered with the component to receive events and get an 'ircd_backend_registered' event.

METHODS

These are the methods that may be invoked on our object.

shutdown

Takes no arguments. Terminates the component. Removes all listeners and connectors. Disconnects all current client and server connections.

session_id

Takes no arguments. Returns the ID of the component's session. Ideal for posting events to the component.

send_event

Seen an event through the component's event handling system. First argument is the event name, subsequent arguments are the event's parameters.

antiflood

Takes two arguments, a connection id and true/false value. If value is specified antiflood protection is enabled or disabled accordingly for the specified connection. If a value is not specified the current status of antiflood protection is returned. Returns undef on error.

compressed_link

Takes two arguments, a connection id and true/false value. If value is specified compression is enabled or disabled accordingly for the specified connection. If a value is not specified the current status of compression is returned. Returns undef on error.

disconnect

Requires on argument, the connection id you wish to disconnect. The component will terminate the connection the next time that the wheel input is flushed, so you may send some sort of error message to the client on that connection. Returns true on success, undef on error.

connection_info

Takes one argument, a connection_id. Returns a list consisting of: the IP address of the peer; the port on the peer; our socket address; our socket port. Returns undef on error.

   my($peeraddr,$peerport,$sockaddr,$sockport) = $object->connection_info( $conn_id );

add_denial

Takes one mandatory argument and one optional. The first mandatory argument is a Net::Netmask object that will be used to check connecting IP addresses against. The second optional argument is a reason string for the denial.

del_denial

Takes one mandatory argument, a Net::Netmask object to remove from the current denial list.

denied

Takes one argument, an IP address. Returns true or false depending on whether that IP is denied or not.

add_exemption

Takes one mandatory argument, a Net::Netmask object that will be checked against connecting IP addresses for exemption from denials.

del_exemption

Takes one mandatory argument, a Net::Netmask object to remove from the current exemption list.

exempted

Takes one argument, an IP address. Returns true or false depending on whether that IP is exempt from denial or not.

yield

This method provides an alternative object based means of posting events to the component. First argument is the event to post, following arguments are sent as arguments to the resultant post.

call

This method provides an alternative object based means of calling events to the component. First argument is the event to call, following arguments are sent as arguments to the resultant call.

INPUT EVENTS

These are POE events that the component will accept:

register

Takes no arguments. Registers a session to receive events from the component.

unregister

Takes no arguments. Unregisters a previously registered session.

add_listener

Takes a number of arguments. Adds a new listener.

        'port', the TCP port to listen on. Default is a random port;
        'auth', enable or disable auth sub-system for this listener. Default enabled;
        'bindaddr', specify a local address to bind the listener to;
        'listenqueue', change the SocketFactory's ListenQueue;

del_listener

Takes either 'port' or 'listener':

        'listener' is a previously returned listener ID;
        'port', listening TCP port; 

The listener will be deleted. Note: any connected clients on that port will not be disconnected.

add_connector

Takes two mandatory arguments, 'remoteaddress' and 'remoteport'. Opens a TCP connection to specified address and port.

        'remoteaddress', hostname or IP address to connect to;
        'remoteport', the TCP port on the remote host;
        'bindaddress', a local address to bind from ( optional );

send_output

Takes a hashref and one or more connection IDs.

  $poe_kernel->post( $object->session_id() => send_output => 
        { prefix => 'blah!~blah@blah.blah.blah',
          command => 'PRIVMSG',
          params  => [ '#moo', 'cows go moo, not fish :D' ] },
        @list_of_connection_ids );

OUTPUT EVENTS

Once registered your session will receive these states, which will have the applicable prefix as specified to create() or the default which is 'ircd_backend_':

registered

  Emitted: when a session registers with the component;
  Target:       the registering session;
  Args: 
        ARG0, the component's object;

unregistered

  Emitted: when a session unregisters with the component;
  Target: the unregistering session;
  Args: none

connection

  Emitted: when a client connects to one of the component's listeners;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the conn id;
        ARG1, their ip address;
        ARG2, their tcp port;
        ARG3, our ip address;
        ARG4, our socket port;

auth_done

  Emitted: after a client has connected and the component has validated hostname and ident;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the conn id;
        ARG1, a HASHREF with the following keys: 'ident' and 'hostname';

listener_add

  Emitted: on a successful add_listener() call;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the listening port;
        ARG1, the listener id;

listener_del

  Emitted: on a successful del_listener() call;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the listening port;
        ARG1, the listener id;

listener_failure

  Emitted: when a listener wheel fails;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the listener id;
        ARG1, the name of the operation that failed;
        ARG2, numeric value for $!;
        ARG3, string value for $!;

socketerr

  Emitted: on the failure of an add_connector()
  Target: all plugins and registered sessions;
  Args:
        ARG0, a HASHREF containing the params that add_connector() was called with;

connected

  Emitted: when the component establishes a connection with a peer;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the conn id;
        ARG1, their ip address;
        ARG2, their tcp port;
        ARG3, our ip address;
        ARG4, our socket port;

connection_flood

  Emitted: when a client connection is flooded;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the conn id;

connection_idle

  Emitted: when a client connection has not sent any data for a set period;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the conn id;
        ARG1, the number of seconds period we consider as idle;

disconnected

  Emitted: when a client disconnects;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the conn id;
        ARG1, the error or reason for disconnection;

cmd_*

  Emitted: when a client or peer sends a valid IRC line to us;
  Target: all plugins and registered sessions;
  Args:
        ARG0, the conn id;
        ARG1, a HASHREF containing the output record from POE::Filter::IRCD:
        { prefix => 'blah!~blah@blah.blah.blah',
          command => 'PRIVMSG',
          params  => [ '#moo', 'cows go moo, not fish :D' ],
          raw_line => ':blah!~blah@blah.blah.blah.blah PRIVMSG #moo :cows go moo, not fish :D' };

PLUGIN SYSTEM

POE::Component::Server::IRC sports a plugin system remarkably similar to POE::Component::IRC's.

These are plugin related methods:

pipeline

Returns the POE::Component::Server::IRC::Pipeline object used internally by the component.

plugin_add

Accepts two arguments:

  The alias for the plugin
  The actual plugin object

The alias is there for the user to refer to it, as it is possible to have multiple plugins of the same kind active in one PoCo-Server-IRC-Backend object.

Returns 1 if plugin was initialized, undef if not.

plugin_del

Accepts one argument:

  The alias for the plugin or the plugin object itself

Returns the plugin object if the plugin was removed, undef if not.

plugin_get

Accepts one argument:

  The alias for the plugin

Returns the plugin object if it was found, undef if not.

plugin_list =item plugin_order

Has no arguments.

Returns a hashref of plugin objects, keyed on alias, or an empty list if there are no plugins loaded.

plugin_register =item plugin_unregister

See POE::Component::Server::IRC::Plugin for details on these methods.

And plugin related states, prefixed with the appropriate prefix or the default, 'ircd_backend_':

plugin_add

  Emitted: when the component successfully adds a new plugin;
  Target: all plugins and registered sessions;
  Args:
        ARG0, plugin alias;
        ARG1, plugin object;

plugin_del

  Emitted: when the component successfully removes a plugin;
  Target: all plugins and registered sessions;
  Args:
        ARG0, plugin alias;
        ARG1, plugin object;

AUTHOR

Chris 'BinGOs' Williams

LICENSE

Copyright © Chris Williams

This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.

SEE ALSO

POE::Filter::IRCD

POE::Component::IRC

POE