| 1 |
NAME |
| 2 |
POE::Component::Jabber - A POE Component for communicating over Jabber |
| 3 |
|
| 4 |
VERSION |
| 5 |
3.00 |
| 6 |
|
| 7 |
DESCRIPTION |
| 8 |
PCJ is a communications component that fits within the POE framework and |
| 9 |
provides the raw low level footwork of initiating a connection, |
| 10 |
negotiatating various protocol layers, and authentication necessary for |
| 11 |
the end developer to focus more on the business end of implementing a |
| 12 |
client or service. |
| 13 |
|
| 14 |
METHODS |
| 15 |
new() |
| 16 |
Accepts many named, required arguments which are listed below. new() |
| 17 |
will return a reference to the newly created reference to a PCJ |
| 18 |
object and should be stored. There are many useful methods that can |
| 19 |
be called on the object to gather various bits of information such |
| 20 |
as your negotiated JID. |
| 21 |
|
| 22 |
IP |
| 23 |
The IP address in dotted quad, or the FQDN for the server. |
| 24 |
|
| 25 |
PORT |
| 26 |
The remote port of the server to connect. |
| 27 |
|
| 28 |
HOSTNAME |
| 29 |
The hostname of the server. Used in addressing. |
| 30 |
|
| 31 |
USERNAME |
| 32 |
The username to be used in authentication (OPTIONAL for jabberd14 |
| 33 |
service connections). |
| 34 |
|
| 35 |
PASSWORD |
| 36 |
The password to be used in authentication. |
| 37 |
|
| 38 |
RESOURCE |
| 39 |
The resource that will be used for binding and session |
| 40 |
establishment (OPTIONAL: resources aren't necessary for |
| 41 |
initialization of service oriented connections, and if not |
| 42 |
provided for client connections will be automagically generated). |
| 43 |
|
| 44 |
ALIAS |
| 45 |
The alias the component should register for use within POE. |
| 46 |
Defaults to the class name. |
| 47 |
|
| 48 |
CONNECTIONTYPE |
| 49 |
This is the type of connection you wish to esablish. There four |
| 50 |
possible types available for use. One must be selected. Each item |
| 51 |
is exported by default. |
| 52 |
|
| 53 |
XMPP (XMPP.pm) |
| 54 |
This connection type is for use with XMPP 1.0 compliant servers. |
| 55 |
It implements all of the necessary functionality for TLS, |
| 56 |
binding, and session negotiation. |
| 57 |
|
| 58 |
LEGACY (Legacy.pm) |
| 59 |
LEGACY is for use with pre-XMPP Jabber servers. It uses the old |
| 60 |
style authentication and non-secured socket communication. |
| 61 |
|
| 62 |
JABBERD14_COMPONENT (J14.pm) |
| 63 |
Use this connection type if designing a backbone level component |
| 64 |
for a server that implements XEP-114 for router level |
| 65 |
communication. |
| 66 |
|
| 67 |
JABBERD20_COMPONENT (J2.pm) |
| 68 |
If making a router level connection to the jabberd2 server, use |
| 69 |
this connection type. It implements the modified XMPP protocol, |
| 70 |
which does most of it except the session negotiation. |
| 71 |
|
| 72 |
Each connection type has a corresponding module. See their |
| 73 |
respective documentation for more information each protocol |
| 74 |
dialect. |
| 75 |
|
| 76 |
VERSION |
| 77 |
If for whatever reason you want to override the protocol version |
| 78 |
gathered from your ConnectionType, this is the place to do it. |
| 79 |
Please understand that this value SHOULD NOT be altered, but it is |
| 80 |
documented here just in case. |
| 81 |
|
| 82 |
XMLNS |
| 83 |
If for whatever reason you want to override the protocol's default |
| 84 |
XML namespace that is gathered from your ConnectionType, use this |
| 85 |
variable. Please understand that this value SHOULD NOT be altered, |
| 86 |
but is documented here just in case. |
| 87 |
|
| 88 |
STREAM |
| 89 |
If for whatever reason you want to override the xmlns:stream |
| 90 |
attribute in the <stream:stream/> this is the argument to use. |
| 91 |
This SHOULD NOT ever need to be altered, but it is available and |
| 92 |
documented just in case. |
| 93 |
|
| 94 |
DEBUG |
| 95 |
If bool true, will enable debugging and tracing within the |
| 96 |
component. All XML sent or received through the component will be |
| 97 |
printed to STDERR |
| 98 |
|
| 99 |
wheel() [Protected] |
| 100 |
wheel() returns the currently stored POE::Wheel reference. If |
| 101 |
provided an argument, that argument will replace the current |
| 102 |
POE::Wheel stored. |
| 103 |
|
| 104 |
sock() [Protected] |
| 105 |
sock() returns the current socket being used for communication. If |
| 106 |
provided an argument, that argument will replace the current socket |
| 107 |
stored. |
| 108 |
|
| 109 |
sid() [Protected] |
| 110 |
sid() returns the session ID that was given by the server upon the |
| 111 |
initial connection. If provided an argument, that argument will |
| 112 |
replace the current session id stored. |
| 113 |
|
| 114 |
config() [Protected] |
| 115 |
config() returns the configuration structure (HASH reference) of PCJ |
| 116 |
that is used internally. It contains values that are either defaults |
| 117 |
or were calculated based on arguments provided in the constructor. |
| 118 |
If provided an argument, that argument will replace the current |
| 119 |
configuration. |
| 120 |
|
| 121 |
pending() [Protected] |
| 122 |
pending() returns a hash reference to the currently pending |
| 123 |
return_to_sender transactions keyed by the 'id' attribute of the XML |
| 124 |
node. If provided an argument, that argument will replace the |
| 125 |
pending queue. |
| 126 |
|
| 127 |
queue() [Protected] |
| 128 |
queue() returns an array reference containing the Nodes sent when |
| 129 |
there was no suitable initialized connection available. Index zero |
| 130 |
is the first Node placed into the queue with index one being the |
| 131 |
second, and so on. See under the EVENTS section, 'purge_queue' for |
| 132 |
more information. |
| 133 |
|
| 134 |
_reset() [Private] |
| 135 |
_reset() returns PCJ back to its initial state and returns nothing. |
| 136 |
|
| 137 |
_gather_options() [Private] |
| 138 |
_gather_options() takes an array reference of the arguments provided |
| 139 |
to new() (ie. \@_) and populates its internal configuration with the |
| 140 |
values (the same configuration returned by config()). |
| 141 |
|
| 142 |
relinquish_states() [Protected] |
| 143 |
relinquish_states() is used by Protocol subclasses to return control |
| 144 |
of the events back to the core of PCJ. It is typically called when |
| 145 |
the event PCJ_READY is fired to the events handler. |
| 146 |
|
| 147 |
PUBLISHED INPUT EVENTS |
| 148 |
'output' |
| 149 |
This is the event that you use to push data over the wire. It |
| 150 |
accepts only one argument, a reference to a POE::Filter::XML::Node. |
| 151 |
|
| 152 |
'return_to_sender' |
| 153 |
This event takes (1) a POE::Filter::XML::Node and gives it a unique |
| 154 |
id, and (2) a return event and places it in the state machine. Upon |
| 155 |
receipt of response to the request, the return event is fired with |
| 156 |
the response packet. |
| 157 |
|
| 158 |
POE::Component::Jabber will publish the return event upon receipt, |
| 159 |
and rescind the event once the the return event is fired. |
| 160 |
|
| 161 |
In the context POE::Component::PubSub, this means that a |
| 162 |
subscription must exist to the return event. Subscriptions can be |
| 163 |
made prior to publishing. |
| 164 |
|
| 165 |
Please note that return_to_sender short circuits before XPATH filter |
| 166 |
and normal node received events. |
| 167 |
|
| 168 |
'xpath_filter' |
| 169 |
This event takes (1) a command of either 'add' or 'remove', (2) and |
| 170 |
event name to be called upon a successful match, and (3) an XPATH |
| 171 |
expression. |
| 172 |
|
| 173 |
With 'add', all three arguments are required. With 'remove', only |
| 174 |
the event name is required. |
| 175 |
|
| 176 |
Like return_to_sender, POE::Component::Jabber will publish the |
| 177 |
return event upon receipt, but will NOT rescind once the filter |
| 178 |
matches something. This allows for persistent filters and event |
| 179 |
dispatching. |
| 180 |
|
| 181 |
Every filter is evaluated for every packet (if not applicable to |
| 182 |
return_to_sender processing), allowing multiple overlapping filters. |
| 183 |
And event names are not checked to be unique, so be careful when |
| 184 |
adding filters that go to the same event, because 'remove' will |
| 185 |
remove all instances of that particular event. |
| 186 |
|
| 187 |
'shutdown' |
| 188 |
The shutdown event terminates the XML stream which in turn will |
| 189 |
trigger the end of the socket's life. |
| 190 |
|
| 191 |
'connect' and 'reconnect' |
| 192 |
This event can take (1) the ip address of a new server and (2) the |
| 193 |
port. This event may also be called without any arguments and it |
| 194 |
will force the component to [re]connect. |
| 195 |
|
| 196 |
This event must be posted before the component will initiate a |
| 197 |
connection. |
| 198 |
|
| 199 |
'purge_queue' |
| 200 |
If Nodes are sent to the output event when there isn't a fully |
| 201 |
initialized connection, the Nodes are placed into a queue. PCJ will |
| 202 |
not automatically purge this queue when a suitable connection DOES |
| 203 |
become available because there is no way to tell if the packets are |
| 204 |
still valid or not. It is up to the end developer to decide this and |
| 205 |
fire this event. Packets will be sent in the order in which they |
| 206 |
were received. |
| 207 |
|
| 208 |
PUBLISHED OUTPUT EVENTS |
| 209 |
Please see POE::Component::Jabber::Events for a list of published events |
| 210 |
to which subscriptions can be made. |
| 211 |
|
| 212 |
CHANGES |
| 213 |
From the 2.X branch, several changes have been made improve event |
| 214 |
management. |
| 215 |
|
| 216 |
The guts are now based around POE::Component::PubSub. This enables very |
| 217 |
specific subscriptions to status events rather than all of the status |
| 218 |
events being delivered to a single event. |
| 219 |
|
| 220 |
Also, using the new POE::Filter::XML means that the underlying XML |
| 221 |
parser and Node implementation has changed for the better but also |
| 222 |
introduced API incompatibilities. For the most part, a simple |
| 223 |
search-and-replace will suffice. Well worth it for the power to apply |
| 224 |
XPATH expressions to nodes. |
| 225 |
|
| 226 |
NOTES |
| 227 |
This is a connection broker. This should not be considered a first class |
| 228 |
client or service. This broker basically implements whatever core |
| 229 |
functionality is required to get the end developer to the point of |
| 230 |
writing upper level functionality quickly. |
| 231 |
|
| 232 |
EXAMPLES |
| 233 |
For example implementations using all four current aspects, please see |
| 234 |
the examples/ directory in the distribution. |
| 235 |
|
| 236 |
AUTHOR |
| 237 |
Copyright (c) 2003-2009 Nicholas Perez. Distributed under the GPL. |
| 238 |
|