Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POE::Component::ServerUserCContributed)POE::Component::Server::IRC::Backend(3)

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

SYNOPSIS
	package	MyIRCD;

	use strict;
	use warnings;
	use base 'POE::Component::Server::IRC::Backend';

	sub spawn {
	    my ($package, %args) = @_;

	    my $self = $package->create(prefix => 'ircd_', @_);

	    # process %args ...

	    return $self;
	}

DESCRIPTION
       POE::Component::Server::IRC::Backend - A	POE component class that
       provides	network	connection abstraction for
       POE::Component::Server::IRC. It uses a plugin system. See
       POE::Component::Server::IRC::Plugin for details.

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

       o   'alias', a POE::Kernel alias	to set;

       o   'auth', set to a false value	to globally disable IRC
	   authentication, default is auth is enabled;

       o   'antiflood',	set to a false value to	globally disable flood
	   protection, default is true;

       o   'prefix', this is the prefix	that is	used to	generate event names
	   that	the component produces.	The default is 'ircd_'.

       o   'states', an	array reference	of extra objects states	for the	IRC
	   daemon's POE	sessions. The elements can be array references of
	   states as well as hash references of	state => handler pairs.

       o   'plugin_debug', set to a true value to print	plugin debug info.
	   Default is false.

       o   'options', a	hashref	of options to POE::Session

       o   'raw_events', whether to send raw events.  False by default.	Can be
	   enabled later with "raw_events";

       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
   General
       "shutdown"

       Takes no	arguments. Terminates the component. Removes all listeners and
       connectors. Disconnects all current client and server connections. This
       is a shorthand for "$ircd->yield('shutdown')".

       "session_id"

       Inherited from POE::Component::Syndicator

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

       "session_alias"

       Inherited from POE::Component::Syndicator

       Takes no	arguments. Returns the session alias that has been set through
       "create"'s 'alias' argument.

       "yield"

       Inherited from POE::Component::Syndicator

       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"

       Inherited from POE::Component::Syndicator

       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.

       "delay"

       Inherited from POE::Component::Syndicator

       This method provides a way of posting delayed events to the component.
       The first argument is an	arrayref consisting of the delayed command to
       post and	any command arguments. The second argument is the time in
       seconds that one	wishes to delay	the command being posted.

       Returns an alarm	ID that	can be used with "delay_remove"	to cancel the
       delayed event. This will	be undefined if	something went wrong.

       "delay_remove"

       Inherited from POE::Component::Syndicator

       This method removes a previously	scheduled delayed event	from the
       component. Takes	one argument, the "alarm_id" that was returned by a
       "delay" method call.

       Returns an arrayref that	was originally requested to be delayed.

       "send_event"

       Inherited from POE::Component::Syndicator

       Sends an	event through the component's event handling system. These
       will get	processed by plugins then by registered	sessions. First
       argument	is the event name, followed by any parameters for that event.

       "send_event_next"

       Inherited from POE::Component::Syndicator

       This sends an event right after the one that's currently	being
       processed.  Useful if you want to generate some event which is directly
       related to another event	so you want them to appear together. This
       method can only be called when POE::Component::IRC is processing	an
       event, e.g. from	one of your event handlers. Takes the same arguments
       as "send_event".

       "send_event_now"

       Inherited from POE::Component::Syndicator

       This will send an event to be processed immediately. This means that if
       an event	is currently being processed and there are plugins or sessions
       which will receive it after you do, then	an event sent with
       "send_event_now"	will be	received by those plugins/sessions before the
       current event.  Takes the same arguments	as "send_event".

       "raw_events"

       If called with a	true value, raw	events ("ircd_raw_input" and
       "ircd_raw_output") will be enabled.

   Connections
       "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 a value
       is specified, compression will be 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_exists"

       Requires	one argument, a	connection id. Returns true value if the
       connection exists, false	otherwise.

       "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)	= $ircd->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.

   Plugins
       "pipeline"

       Inherited from Object::Pluggable

       Returns the Object::Pluggable::Pipeline object.

       "plugin_add"

       Inherited from Object::Pluggable

       Accepts two arguments:

	The alias for the plugin
	The actual plugin object
	Any number of extra arguments

       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 Object::Pluggable
       object.

       This method goes	through	the pipeline's "push()"	method,	which will
       call "$plugin->plugin_register($pluggable, @args)".

       Returns the number of plugins now in the	pipeline if plugin was
       initialized, "undef"/an empty list if not.

       "plugin_del"

       Inherited from Object::Pluggable

       Accepts the following arguments:

	The alias for the plugin or the	plugin object itself
	Any number of extra arguments

       This method goes	through	the pipeline's "remove()" method, which	will
       call "$plugin->plugin_unregister($pluggable, @args)".

       Returns the plugin object if the	plugin was removed, "undef"/an empty
       list if not.

       "plugin_get"

       Inherited from Object::Pluggable

       Accepts the following arguments:

	The alias for the plugin

       This method goes	through	the pipeline's "get()" method.

       Returns the plugin object if it was found, "undef"/an empty list	if
       not.

       "plugin_list"

       Inherited from Object::Pluggable

       Takes no	arguments.

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

       "plugin_order"

       Inherited from Object::Pluggable

       Takes no	arguments.

       Returns an arrayref of plugin objects, in the order which they are
       encountered in the pipeline.

       "plugin_register"

       Inherited from Object::Pluggable

       Accepts the following arguments:

	The plugin object
	The type of the	hook (the hook types are specified with	_pluggable_init()'s 'types')
	The event name[s] to watch

       The event names can be as many as possible, or an arrayref. They
       correspond to the prefixed events and naturally,	arbitrary events too.

       You do not need to supply events	with the prefix	in front of them, just
       the names.

       It is possible to register for all events by specifying 'all' as	an
       event.

       Returns 1 if everything checked out fine, "undef"/an empty list if
       something is seriously wrong.

       "plugin_unregister"

       Inherited from Object::Pluggable

       Accepts the following arguments:

	The plugin object
	The type of the	hook (the hook types are specified with	_pluggable_init()'s 'types')
	The event name[s] to unwatch

       The event names can be as many as possible, or an arrayref. They
       correspond to the prefixed events and naturally,	arbitrary events too.

       You do not need to supply events	with the prefix	in front of them, just
       the names.

       It is possible to register for all events by specifying 'all' as	an
       event.

       Returns 1 if all	the event name[s] was unregistered, undef if some was
       not found.

INPUT EVENTS
       These are POE events that the component will accept:

   "register"
       Inherited from POE::Component::Syndicator

       Takes N arguments: a list of event names	that your session wants	to
       listen for, minus the "irc_" prefix.

	$ircd->yield('register', qw(connected disconnected));

       The special argument 'all' will register	your session for all events.
       Registering will	generate an "ircd_registered" event that your session
       can trap.

   "unregister"
       Inherited from POE::Component::Syndicator

       Takes N arguments: a list of event names	which you don't	want to
       receive.	If you've previously done a "register" for a particular	event
       which you no longer care	about, this event will tell the	component to
       stop sending them to you. (If you haven't, it just ignores you. No big
       deal.)

       If you have registered with 'all', attempting to	unregister individual
       events such as 'connected', etc.	will not work. This is a 'feature'.

   "add_listener"
       Takes a number of arguments. Adds a new listener.

       o   'port', the TCP port	to listen on. Default is a random port;

       o   'auth', enable or disable auth sub-system for this listener.
	   Enabled by default;

       o   'bindaddr', specify a local address to bind the listener to;

       o   'listenqueue', change the SocketFactory's ListenQueue;

       o   'usessl', whether the listener should use SSL. Default is false;

       o   'antiflood',	whether	the listener should use	flood protection.
	   Defaults is true;

       o   'idle', the time, in	seconds, after which a connection will be
	   considered idle. Defaults is	180.

   "del_listener"
       Takes one of the	following arguments:

       o   'listener', a previously returned listener ID;

       o   'port', a listening 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.

       o   'remoteaddress', hostname or	IP address to connect to;

       o   'remoteport', the TCP port on the remote host;

       o   'bindaddress', a local address to bind from (optional);

   "send_output"
       Takes a hashref and one or more connection IDs.

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

   "shutdown"
       Inherited from POE::Component::Syndicator

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

OUTPUT EVENTS
       These following events are sent to interested sessions.

   "ircd_registered"
       Inherited from POE::Component::Syndicator

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

   "ircd_connection"
       Emitted:	when a client connects to one of the component's listeners;
       Target: all plugins and registered sessions
       Args:
	   o   "ARG0": the conn	id;

	   o   "ARG1": their ip	address;

	   o   "ARG2": their tcp port;

	   o   "ARG3": our ip address;

	   o   "ARG4": our socket port;

	   o   "ARG5": a boolean indicating whether the	client needs to	be
	       authed

   "ircd_auth_done"
       Emitted:	after a	client has connected and the component has validated
       hostname	and ident;
       Target: Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the connection id;

	   o   "ARG1", a HASHREF with the following keys: 'ident' and
	       'hostname';

   "ircd_listener_add"
       Emitted:	on a successful	"add_listener" call;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the listening port;

	   o   "ARG1", the listener id;

	   o   "ARG2", the listening address;

   "ircd_listener_del"
       Emitted:	on a successful	"del_listener" call;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the listening port;

	   o   "ARG1", the listener id;

	   o   "ARG2", the listener address;

   "ircd_listener_failure"
       Emitted:	when a listener	wheel fails;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the listener id;

	   o   "ARG1", the name	of the operation that failed;

	   o   "ARG2", numeric value for $!;

	   o   "ARG3", string value for	$!;

	   o   "ARG4", the port	it tried to listen on;

	   o   "ARG5", the address it tried to listen on;

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

	   o   "ARG1", the name	of the operation that failed;

	   o   "ARG2", numeric value for $!;

	   o   "ARG3", string value for	$!;

   "ircd_connected"
       Emitted:	when the component establishes a connection with a peer;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the connection id;

	   o   "ARG1", their ip	address;

	   o   "ARG2", their tcp port;

	   o   "ARG3", our ip address;

	   o   "ARG4", our socket port;

	   o   "ARG5", the peer's name;

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

   "ircd_connection_idle"
       Emitted:	when a client connection has not sent any data for a set
       period;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the connection id;

	   o   "ARG1", the number of seconds period we consider	as idle;

   "ircd_compressed_conn"
       Emitted:	when compression has been enabled for a	connection
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the connection id;

   "ircd_cmd_*"
       Emitted:	when a client or peer sends a valid IRC	line to	us;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the connection id;

	   o   "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'
		}

   "ircd_raw_input"
       Emitted:	when a line of input is	received from a	connection
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the connection id;

	   o   "ARG1", the raw line of input

   "ircd_raw_output"
       Emitted:	when a line of output is sent over a connection
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the connection id;

	   o   "ARG1", the raw line of output

   "ircd_disconnected"
       Emitted:	when a client disconnects;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the connection id;

	   o   "ARG1", the error or reason for disconnection;

   "ircd_shutdown"
       Inherited from POE::Component::Syndicator

       Emitted:	when the component has been asked to "shutdown"
       Target: all registered sessions;
       Args:
	   o   "ARG0": the session ID of the requesting	component

   "ircd_delay_set"
       Inherited from POE::Component::Syndicator

       Emitted:	on a successful	addition of a delayed event using the "delay"
       method
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0": the alarm id which can be used later with
	       "delay_remove"

	   o   "ARG1..$#_": subsequent arguments are those which were passed
	       to "delay"

   "ircd_delay_removed"
       Inherited from POE::Component::Syndicator

       Emitted:	when a delayed command is successfully removed
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0": the alarm id which was removed

	   o   "ARG1..$#_": subsequent arguments are those which were passed
	       to "delay"

   "ircd_plugin_add"
       Inherited from Object::Pluggable

       Emitted:	when a new plugin is added to the pipeline
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0": the plugin alias

	   o   "ARG1": the plugin object

   "ircd_plugin_del"
       Inherited from Object::Pluggable

       Emitted:	when a plugin is removed from the pipeline
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0": the plugin alias

	   o   "ARG1": the plugin object

   "ircd_plugin_error"
       Inherited from Object::Pluggable

       Emitted:	when an	error occurs while executing a plugin handler
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0": the error message

	   o   "ARG1": the plugin alias

	   o   "ARG2": the plugin object

AUTHOR
       Chris 'BinGOs' Williams

LICENSE
       Copyright A(C) 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

       POE::Filter::IRCD

       POE::Component::Server::IRC

perl v5.32.0			  2011-POE::Component::Server::IRC::Backend(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | METHODS | INPUT EVENTS | OUTPUT EVENTS | AUTHOR | LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=POE::Component::Server::IRC::Backend&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help