<!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 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 Jive Messenger 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 Jive Messenger 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).

<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> 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.</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>.
    </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>

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:

<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>

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:

<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>

This example requests the presence of a user in XML format:

<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>

</body>
</html>