Debian Codegraph @

README

raw
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