NAME¶
POE::Component::Jabber - A POE Component for communicating over Jabber
VERSION¶
3.00
DESCRIPTION¶
PCJ is a communications component that fits within the POE framework and
provides the raw low level footwork of initiating a connection, negotiatating
various protocol layers, and authentication necessary for the end developer to
focus more on the business end of implementing a client or service.
METHODS¶
- new()
- Accepts many named, required arguments which are listed
below. new() will return a reference to the newly created reference
to a PCJ object and should be stored. There are many useful methods that
can be called on the object to gather various bits of information such as
your negotiated JID.
- IP
- The IP address in dotted quad, or the FQDN for the
server.
- PORT
- The remote port of the server to connect.
- HOSTNAME
- The hostname of the server. Used in addressing.
- USERNAME
- The username to be used in authentication (OPTIONAL for
jabberd14 service connections).
- PASSWORD
- The password to be used in authentication.
- RESOURCE
- The resource that will be used for binding and session
establishment (OPTIONAL: resources aren't necessary for initialization of
service oriented connections, and if not provided for client connections
will be automagically generated).
- ALIAS
- The alias the component should register for use within POE.
Defaults to the class name.
- CONNECTIONTYPE
- This is the type of connection you wish to esablish. There
four possible types available for use. One must be selected. Each item is
exported by default.
- XMPP (XMPP.pm)
- This connection type is for use with XMPP 1.0 compliant
servers. It implements all of the necessary functionality for TLS,
binding, and session negotiation.
- LEGACY (Legacy.pm)
- LEGACY is for use with pre-XMPP Jabber servers. It uses the
old style authentication and non-secured socket communication.
- JABBERD14_COMPONENT (J14.pm)
- Use this connection type if designing a backbone level
component for a server that implements XEP-114 for router level
communication.
- JABBERD20_COMPONENT (J2.pm)
- If making a router level connection to the jabberd2 server,
use this connection type. It implements the modified XMPP protocol, which
does most of it except the session negotiation.
Each connection type has a corresponding module. See their respective
documentation for more information each protocol dialect.
- VERSION
- If for whatever reason you want to override the protocol
version gathered from your ConnectionType, this is the place to do it.
Please understand that this value SHOULD NOT be altered, but it is
documented here just in case.
- XMLNS
- If for whatever reason you want to override the protocol's
default XML namespace that is gathered from your ConnectionType, use this
variable. Please understand that this value SHOULD NOT be altered, but is
documented here just in case.
- STREAM
- If for whatever reason you want to override the
xmlns:stream attribute in the <stream:stream/> this is the argument
to use. This SHOULD NOT ever need to be altered, but it is available and
documented just in case.
- DEBUG
- If bool true, will enable debugging and tracing within the
component. All XML sent or received through the component will be printed
to STDERR
- wheel() [Protected]
- wheel() returns the currently stored POE::Wheel
reference. If provided an argument, that argument will replace the current
POE::Wheel stored.
- sock() [Protected]
- sock() returns the current socket being used for
communication. If provided an argument, that argument will replace the
current socket stored.
- sid() [Protected]
- sid() returns the session ID that was given by the
server upon the initial connection. If provided an argument, that argument
will replace the current session id stored.
- config() [Protected]
- config() returns the configuration structure (HASH
reference) of PCJ that is used internally. It contains values that are
either defaults or were calculated based on arguments provided in the
constructor. If provided an argument, that argument will replace the
current configuration.
- pending() [Protected]
- pending() returns a hash reference to the currently
pending return_to_sender transactions keyed by the 'id' attribute of the
XML node. If provided an argument, that argument will replace the pending
queue.
- queue() [Protected]
- queue() returns an array reference containing the
Nodes sent when there was no suitable initialized connection available.
Index zero is the first Node placed into the queue with index one being
the second, and so on. See under the EVENTS section, 'purge_queue' for
more information.
- _reset() [Private]
- _reset() returns PCJ back to its initial state and
returns nothing.
- _gather_options() [Private]
- _gather_options() takes an array reference of the
arguments provided to new() (ie. \@_) and populates its internal
configuration with the values (the same configuration returned by
config()).
- relinquish_states() [Protected]
- relinquish_states() is used by Protocol subclasses
to return control of the events back to the core of PCJ. It is typically
called when the event PCJ_READY is fired to the events handler.
- 'output'
- This is the event that you use to push data over the wire.
It accepts only one argument, a reference to a
POE::Filter::XML::Node.
- 'return_to_sender'
- This event takes (1) a POE::Filter::XML::Node and gives it
a unique id, and (2) a return event and places it in the state machine.
Upon receipt of response to the request, the return event is fired with
the response packet.
POE::Component::Jabber will publish the return event upon receipt, and
rescind the event once the the return event is fired.
In the context POE::Component::PubSub, this means that a subscription must
exist to the return event. Subscriptions can be made prior to publishing.
Please note that return_to_sender short circuits before XPATH filter and
normal node received events.
- 'xpath_filter'
- This event takes (1) a command of either 'add' or 'remove',
(2) and event name to be called upon a successful match, and (3) an XPATH
expression.
With 'add', all three arguments are required. With 'remove', only the event
name is required.
Like return_to_sender, POE::Component::Jabber will publish the return event
upon receipt, but will NOT rescind once the filter matches something. This
allows for persistent filters and event dispatching.
Every filter is evaluated for every packet (if not applicable to
return_to_sender processing), allowing multiple overlapping filters. And
event names are not checked to be unique, so be careful when adding
filters that go to the same event, because 'remove' will remove all
instances of that particular event.
- 'shutdown'
- The shutdown event terminates the XML stream which in turn
will trigger the end of the socket's life.
- 'connect' and 'reconnect'
- This event can take (1) the ip address of a new server and
(2) the port. This event may also be called without any arguments and it
will force the component to [re]connect.
This event must be posted before the component will initiate a
connection.
- 'purge_queue'
- If Nodes are sent to the output event when there isn't a
fully initialized connection, the Nodes are placed into a queue. PCJ will
not automatically purge this queue when a suitable connection DOES become
available because there is no way to tell if the packets are still valid
or not. It is up to the end developer to decide this and fire this event.
Packets will be sent in the order in which they were received.
PUBLISHED OUTPUT EVENTS¶
Please see POE::Component::Jabber::Events for a list of published events to
which subscriptions can be made.
CHANGES¶
From the 2.X branch, several changes have been made improve event management.
The guts are now based around POE::Component::PubSub. This enables very specific
subscriptions to status events rather than all of the status events being
delivered to a single event.
Also, using the new POE::Filter::XML means that the underlying XML parser and
Node implementation has changed for the better but also introduced API
incompatibilities. For the most part, a simple search-and-replace will
suffice. Well worth it for the power to apply XPATH expressions to nodes.
NOTES¶
This is a connection broker. This should not be considered a first class client
or service. This broker basically implements whatever core functionality is
required to get the end developer to the point of writing upper level
functionality quickly.
EXAMPLES¶
For example implementations using all four current aspects, please see the
examples/ directory in the distribution.
AUTHOR¶
Copyright (c) 2003-2009 Nicholas Perez. Distributed under the GPL.