readme.html 7.68 KB
Newer Older
Gaston Dombiak's avatar
Gaston Dombiak committed
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
<!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%;
        }
38 39 40 41 42 43 44 45 46 47 48
        #datatable TH {
            color : #fff;
            background-color : #2A448C;
            text-align : left;
        }
        #datatable TD {
            background-color : #FAF6EF;
        }
        #datatable .name {
            background-color : #DCE2F5;
        }
Gaston Dombiak's avatar
Gaston Dombiak committed
49 50 51 52 53 54 55 56 57 58 59
    </style>
</head>
<body>

<h1>
Presence Plugin Readme
</h1>

<h2>Overview</h2>

<p>
60
The presence plugin is a service that provides simple presence information over HTTP. 
61
It can be used to display an online status icon for a user or component on a web page or to
62
poll for presence information from a web service.
Gaston Dombiak's avatar
Gaston Dombiak committed
63 64 65 66
</p>

<h2>Installation</h2>

67
<p>Copy presence.jar into the plugins directory of your Openfire installation. The
Gaston Dombiak's avatar
Gaston Dombiak committed
68 69 70 71 72
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>

73
The presence plugin can be configured via the Openfire Admin Console.
74 75
Use the configuration page to specify whether presence information should be available 
to anyone or restricted to authorized users (users which have presence subscriptions).
76 77
The status message for unavailable users can also be changed from the default of
&quot;Unavailable&quot;.
Gaston Dombiak's avatar
Gaston Dombiak committed
78 79 80

<h2>Using the Plugin</h2>

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
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
106
    are <b>image</b>, <b>text</b> or <b>xml</b>. If this parameter is not specified, the
107 108
    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
109
    user's presence will be returned. If <b>text</b> is specified, the status text of the
110 111 112 113 114 115 116 117 118 119
    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>, 
120 121
    <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.
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
    </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>


138
<p><b>Sample HTML</b></p>
139

140 141
<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>
Gaston Dombiak's avatar
Gaston Dombiak committed
142 143

<ul>
144
<form>
Matt Tucker's avatar
Matt Tucker committed
145
<textarea cols=65 rows=3 wrap=virtual><img src="http://example.com:9090/plugins/presence/status?jid=jsmith@example.com" border="0">
146 147
</textarea>
</form>
Gaston Dombiak's avatar
Gaston Dombiak committed
148 149
</ul>

150 151
<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>
Gaston Dombiak's avatar
Gaston Dombiak committed
152 153

<ul>
154 155
<form>
<textarea cols=65 rows=4 wrap=virtual>
Matt Tucker's avatar
Matt Tucker committed
156
<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>
157 158
</textarea>
</form>
Gaston Dombiak's avatar
Gaston Dombiak committed
159 160
</ul>

161
<p>This example requests the presence of a user in XML format:</p>
Gaston Dombiak's avatar
Gaston Dombiak committed
162

163 164
<ul>
<form>
Matt Tucker's avatar
Matt Tucker committed
165
<textarea cols=65 rows=3 wrap=virtual>http://example.com:9090/plugins/presence/status?jid=jsmith@example.com&type=xml
166 167 168
</textarea>
</form>
</ul>
Gaston Dombiak's avatar
Gaston Dombiak committed
169

170 171 172 173 174 175 176 177 178
<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>

179 180
<p><b>Working With Firewalls</b></p>

181 182
<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
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
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>&lt;img src="http://www.example.com:9090/plugins/presence/status?jid=jsmith@example.com"&gt;</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>&lt;virtualhost *:80&gt;

  servername example.com
  ....
  ProxyVia On
  RewriteEngine On
204
  RewriteCond %{REQUEST_URI} ^/plugins/presence/status
205 206 207 208 209
  RewriteRule ^/(.*) http://example.com:9090/$1 [P]
&lt;/virtualhost&gt;
</pre></td></tr></table>


Gaston Dombiak's avatar
Gaston Dombiak committed
210 211
</body>
</html>