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.
|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 sockets 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 isnt 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.
Please see POE::Component::Jabber::Events for a list of published events to which subscriptions can be made.
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.
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.
For example implementations using all four current aspects, please see the examples/ directory in the distribution.
Copyright (c) 2003-2009 Nicholas Perez. Distributed under the GPL.
|perl v5.20.3||POE::COMPONENT::JABBER (3)||2016-04-03|