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.

PUBLISHED INPUT EVENTS

       '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.