NAME POEx::IRC::Backend - IRC client or server backend SYNOPSIS use POE; use POEx::IRC::Backend; ## Spawn a Backend and register as the controlling session: my $backend = POEx::IRC::Backend->spawn; $poe_kernel->post( $backend->session_id, 'register' ); sub ircsock_registered { my ($kernel, $self) = @_[KERNEL, OBJECT]; ## Listen for incoming IRC traffic: $backend->create_listener( bindaddr => $addr, port => $port, ); ## Connect to a remote endpoint: $backend->create_connector( remoteaddr => $remote, remoteport => $remoteport, ## Optional: bindaddr => $bindaddr, ipv6 => 1, ssl => 1, ); } ## Handle and dispatch incoming IRC events: sub ircsock_input { my ($kernel, $self) = @_[KERNEL, OBJECT]; ## POEx::IRC::Backend::Connect obj: my $this_conn = $_[ARG0]; ## IRC::Message::Object obj: my $input_obj = $_[ARG1]; my $cmd = $input_obj->command; ## ... dispatch, etc ... } DESCRIPTION A POE IRC backend socket handler using POE::Filter::IRCv3 and IRC::Toolkit. This can be used by client or server libraries to speak IRC protocol via IRC::Message::Object objects. This is a basic low-level interface to IRC connections; see POEx::IRC::Client::Lite for an experimental IRC client library using this backend. This module is part of a set of IRC building blocks that have been split out of a much larger project; it is also early 'alpha-quality' software. Take a gander at POE::Component::IRC for a mature, fully-featured IRC client library. Attributes controller Retrieve the POE::Session ID for the backend's registered controller. Predicate: has_controller connectors A HASH of active Connector objects, keyed on their wheel ID. filter A POE::Filter::Stackable instance consisting of the current "filter_irc" stacked with "filter_line" (at the time the attribute is built). filter_irc A POE::Filter::IRCv3 instance with colonify enabled, by default. A client-side Backend will probably want a non-colonifying filter: my $backend = POEx::IRC::Backend->new( filter_irc => POE::Filter::IRCv3->new(colonify => 0), ... ); filter_line A POE::Filter::Line instance. listeners HASH of active Listener objects, keyed on their wheel ID. session_id Returns the backend's session ID. wheels HASH of actively connected wheels, keyed on their wheel ID. Methods spawn my $backend = POEx::IRC::Backend->spawn( ## Optional, needed for SSL-ified server-side sockets ssl_opts => [ 'server.key', 'server.cert', ], ); Creates the backend's POE::Session. create_connector $backend->create_connector( remoteaddr => $addr, remoteport => $addr, ## Optional: bindaddr => $local_addr, ipv6 => 1, ssl => 1, ); Attempts to create a POEx::IRC::Backend::Connector that holds a POE::Wheel::SocketFactory connector wheel; connectors will attempt to establish an outgoing connection immediately. create_listener $backend->create_listener( bindaddr => $addr, port => $port, ## Optional: ipv6 => 1, ssl => 1, idle => $seconds, ); Attempts to create a POEx::IRC::Backend::Listener that holds a POE::Wheel::SocketFactory listener wheel. remove_listener $backend->remove_listener( listener => $listener_id, ); ## or via addr, port, or combination thereof: $backend->remove_listener( addr => '127.0.0.1', port => 6667, ); Removes a listener and clears its wheel attribute; the socket shuts down when the POE::Wheel::SocketFactory wheel goes out of scope. disconnect $backend->disconnect($wheel_id, $disconnect_string); Given a connection's wheel ID, mark the specified wheel for disconnection. send $backend->send( { prefix => $prefix, params => [ @params ], command => $cmd, }, @connect_ids ); use IRC::Message::Object 'ircmsg'; my $msg = ircmsg( command => 'PRIVMSG', params => [ $chan, $string ], ); $backend->send( $msg, $connect_id ); Feeds POE::Filter::IRCv3 and sends the resultant raw IRC line to the specified connection wheel ID(s). Accepts either an IRC::Message::Object or a HASH compatible with POE::Filter::IRCv3 -- look there for details. set_compressed_link $backend->set_compressed_link( $conn_id ); Mark a specified connection wheel ID as pending compression; POE::Filter::Zlib::Stream will be added to the filter stack when the next flush event arrives. set_compressed_link_now $backend->set_compressed_link_now( $conn_id ); Add a POE::Filter::Zlib::Stream to the connection's filter stack immediately, rather than upon next flush event. unset_compressed_link $backend->unset_compressed_link( $conn_id ); Remove POE::Filter::Zlib::Stream from the connection's filter stack. Received events register $poe_kernel->post( $backend->session_id, 'register' ); Register the sender session as the backend's controller session. The last session to send 'register' is the session that receives notification events from the backend component. create_connector Event interface to *create_connector* -- see "Methods" create_listener Event interface to *create_listener* -- see "Methods" remove_listener Event interface to *remove_listener* -- see "Methods" send Event interface to */send* -- see "Methods" shutdown Disconnect all wheels and clean up. Dispatched events These events are dispatched to the controller session; see "register". ircsock_compressed Dispatched when a connection wheel has had a compression filter added. $_[ARG0] is the connection's POEx::IRC::Backend::Connect ircsock_connection_idle Dispatched when a connection wheel has had no input for longer than specified idle time (see "create_listener" regarding idle times). $_[ARG0] is the connection's POEx::IRC::Backend::Connect ircsock_connector_failure Dispatched when a Connector has failed due to some sort of socket error. $_[ARG0] is the connection's POEx::IRC::Backend::Connector with wheel() cleared. @_[ARG1 .. ARG3] contain the socket error details reported by POE::Wheel::SocketFactory; operation, errno, and errstr, respectively. ircsock_connector_open Dispatched when a Connector has established a connection to a peer. $_[ARG0] is the POEx::IRC::Backend::Connect for the connection. ircsock_disconnect Dispatched when a connection wheel has been cleared. $_[ARG0] is the connection's POEx::IRC::Backend::Connect with wheel() cleared. ircsock_input Dispatched when there is some IRC input from a connection wheel. $_[ARG0] is the connection's POEx::IRC::Backend::Connect. $_[ARG1] is an IRC::Message::Object. ircsock_listener_created Dispatched when a POEx::IRC::Backend::Listener has been created. $_[ARG0] is the POEx::IRC::Backend::Listener instance; the instance's port() is altered based on getsockname() details after socket creation and before dispatching this event. ircsock_listener_failure Dispatched when a Listener has failed due to some sort of socket error. $_[ARG0] is the POEx::IRC::Backend::Listener object. @_[ARG1 .. ARG3] contain the socket error details reported by POE::Wheel::SocketFactory; operation, errno, and errstr, respectively. ircsock_listener_open Dispatched when a listener accepts a connection. $_[ARG0] is the connection's POEx::IRC::Backend::Connect $_[ARG1] is the connection's POEx::IRC::Backend::Listener ircsock_listener_removed Dispatched when a Listener has been removed. $_[ARG0] is the POEx::IRC::Backend::Listener object. ircsock_registered Dispatched when a "register" event has been successfully received, as a means of acknowledging the controlling session. $_[ARG0] is the Backend's $self object. BUGS Probably lots. Please report them via RT, e-mail, or GitHub (). Tests are a bit incomplete, as of this writing. Zlib and SSL are mostly untested. SEE ALSO IRC::Toolkit POE::Filter::IRCv3 AUTHOR Jon Portnoy Inspiration derived from POE::Component::Server::IRC::Backend and POE::Component::IRC by BINGOS, HINRIK et al