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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Presence Plugin Readme</title>
<style type="text/css">
BODY {
font-size : 100%;
}
BODY, TD, TH {
font-family : tahoma, verdana, arial, helvetica, sans-serif;
font-size : 0.8em;
}
H2 {
font-size : 10pt;
font-weight : bold;
}
A:hover {
text-decoration : none;
}
H1 {
font-family : tahoma, arial, helvetica, sans-serif;
font-size : 1.4em;
font-weight: bold;
border-bottom : 1px #ccc solid;
padding-bottom : 2px;
}
TT {
font-family : courier new;
font-weight : bold;
color : #060;
}
PRE {
font-family : courier new;
font-size : 100%;
}
#datatable TH {
color : #fff;
background-color : #2A448C;
text-align : left;
}
#datatable TD {
background-color : #FAF6EF;
}
#datatable .name {
background-color : #DCE2F5;
}
</style>
</head>
<body>
<h1>
Presence Plugin Readme
</h1>
<h2>Overview</h2>
<p>
The presence plugin is a service that provides simple presence information over HTTP.
It can be used to display an online status icon for a user or component on a web page or to
poll for presence information from a web service.
</p>
<h2>Installation</h2>
<p>Copy presence.jar into the plugins directory of your Openfire installation. The
plugin will then be automatically deployed. To upgrade to a new version, copy the new
presence.jar file over the existing file.</p>
<h2>Configuration</h2>
The presence plugin can be configured via the Openfire Admin Console.
Use the configuration page to specify whether presence information should be available
to anyone or restricted to authorized users (users which have presence subscriptions).
The status message for unavailable users can also be changed from the default of
"Unavailable".
<h2>Using the Plugin</h2>
To get presence information for a user, submit HTTP requests to the presence
service. The service address is [hostname]/plugins/presence/status. For example,
if your server name is "example.com", the URL is http://example.com/plugins/presence/status.<p>
The following parameters can be passed into the request:<p>
<div id="datatable">
<table cellpadding="3" cellspacing="1" border="0" width="700">
<tr>
<th colspan=2>Name</th><th>Description</th>
</tr>
<tr>
<td class="name">jid</td><td>Required</td><td>The bare JID (address) of the user to get presence
information for (e.g. "jsmith@example.com"). The address must be on the same
server that the presence service is deployed on.</td>
</tr>
<tr>
<td class="name">req_jid</td><td>Optional</td><td>The bare JID (address) of the user
requesting presence information. This parameter may be required in order
to have permission to get presence information. For example, the presence
service can be configured to only allow presence requests from users that
have a presence subscription to the requested jid.</td>
</tr>
<tr>
<td class="name">type</td><td>Optional</td><td>The type of response to return. Valid values
are <b>image</b>, <b>text</b> or <b>xml</b>. If this parameter is not specified, the
default value is <b>image</b>, which will display an image representing the
user's presence. If <b>xml</b> is specified, an XML representation of the
user's presence will be returned. If <b>text</b> is specified, the status text of the
user's presence will be returned.</td>
</tr>
<tr>
<td class="name">images</td><td>Optional</td><td>The presence service includes a default
set of images that will be returned for a user's presence. You can specify
a custom set of images using this parameter. The value should be the URL
to the images and should include an <b>--IMAGE--</b> token. For example:
"http://www.example.com/images/--IMAGE--.gif". The token will be dynamically
replaced with one of the following values depending on the presence status:
<b>available</b>, <b>chat</b>, <b>away</b>, <b>xa</b>, <b>dnd</b>,
<b>offline</b>, or <b>forbidden</b>. If this option is used, the presence service
will respond with an http redirect pointing to the supplied image url.
</td>
</tr>
<tr>
<td class="name">[image_type]</td><td>Optional</td><td>Instead of specifying a single
location for all custom presence images, you can override each image location
directly. The parameter name should be one of the following values:
<b>available</b>, <b>chat</b>, <b>away</b>, <b>xa</b>, <b>dnd</b>,
<b>offline</b>, or <b>forbidden</b>. The parameter value should be
the full URL of the image, such as "http://www.example.com/images/dnd.png".
These parameters can be used in combination with the "images" parameter to
specify a base location for custom images but then to override specific
images with different locations.</td>
</tr>
</table><p>
<p><b>Sample HTML</b></p>
<p>The following example is the simplest form of calling the service to display
default presence images. The server name and user must be customized for your deployment:</p>
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual><img src="http://example.com:9090/plugins/presence/status?jid=jsmith@example.com" border="0">
</textarea>
</form>
</ul>
<p>This example requests a user's presence by the user "jsmith" and specifies
custom images that should be used to display the user's presence:</p>
<ul>
<form>
<textarea cols=65 rows=4 wrap=virtual>
<img src="http://example.com:9090/plugins/presence/status?jid=mary@example.com&req_jid=jsmith@example.com&images=http://www.example.com/images/--IMAGE--.gif" border=0>
</textarea>
</form>
</ul>
<p>This example requests the presence of a user in XML format:</p>
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>http://example.com:9090/plugins/presence/status?jid=jsmith@example.com&type=xml
</textarea>
</form>
</ul>
<p>This example requests the status text of the presence of a user in text format:</p>
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>http://example.com:9090/plugins/presence/status?jid=jsmith@example.com&type=text
</textarea>
</form>
</ul>
<p><b>Working With Firewalls</b></p>
<p>Because the presence plugin runs within the Openfire admin console web container, users
behind firewalls may have problems seeing the presence icons. For example, if the Openfire
admin console runs on the default port of 9090 and a user is only allowed to receive HTTP traffic
on port 80, then a web request like the following won't work:</p>
<ul>
<tt><img src="http://www.example.com:9090/plugins/presence/status?jid=jsmith@example.com"></tt>
</ul>
<p>One solution for Apache users is to use mod_rewrite, mod_proxy and mod_proxy_http to serve
traffic for the plugin on port 80. Sample Apache configuration entries for performing this mapping
are below. Essentially, we make Apache intercept all requests for the presence plugin on port 80 and
then proxy a real connection to the HTTP server on port 9090.
</p>
<table border="0" cellspacing="1" cellpadding="3" bgcolor="#999999">
<tr>
<td width="1" align="left" bgcolor="#dddddd" valign="top"><font color="#555555"><pre>1<br>2<br>3<br>4<br>5<br>6<br>7<br>8<br>9<br></pre></font></td>
<td align="left" bgcolor="#ffffff" valign="top"><pre><virtualhost *:80>
servername example.com
....
ProxyVia On
RewriteEngine On
RewriteCond %{REQUEST_URI} ^/plugins/presence/status
RewriteRule ^/(.*) http://example.com:9090/$1 [P]
</virtualhost>
</pre></td></tr></table>
</body>
</html>