-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
238 lines (188 loc) · 9.77 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
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.