# Presence Plugin Readme

## Overview

The presence plugin includes a servlet that provides presence information of the users in the server.

## Installation

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.

## Configuration

The presence plugin can be configured via Jive Messenger Administration Console. Use the configuration page to set if the presence information is visible to anyone or only to authorized users.

## Using the Plugin

In order to get presence information of a user you should send HTTP requests to the servlet. The servlet address should be [hostname]/plugins/presence/presence. Since the servlet may return different types of content, the HTTP request should include a type parameter. Possible values are img to get images that represent the user availability status or xml to get an XML stanza with the presence of the user. If the type parameter is missing then an image format is assumed.

Other parameters are:

- sender - bare JID of the user sending the request. This parameter is optional if anyone may get presence information.
- username - username of the user whose presence is being probed. This parameter is mandatory.

When using an image content type it is possible to configure the images to get depending on the user presence status. Moreover, there are many ways to specify the images to use:

- Use a single parameter for all the images - Use the img parameter that will include a ${presence} token. The ${presence} token would be filtered and would be replaced with codes like "dnd", "offline", "away", etc.
- Use a parameter for each possible presence type - Possible parameters are: offline, available, away, chat, dnd, xa. If the parameter was not passed then the default image will be used.
- Do not pass any parameter - When no parameter was passed default images will be used.

If the required user was not found or the user making the request is not allowed to see the user presence then the image specified in the notavailable parameter will be used. However, if the request does not include the notavailable parameter then the default image for user offline will be used. Therefore, each request MUST include the notavailable parameter.

Examples of URL
This example is requesting images and is using a single parameter for all the images: http://localhost:9090/plugins/presence/presence?username=admin&sender=user2@localhost¬available=http://localhost:9090/images/unknown.gif&img=http://localhost:9090/images/${presence}.gif

This example is requesting images and is sending a parameter for each possible presence type: http://localhost:9090/plugins/presence/presence?username=admin&sender=user2@localhost¬available=http://localhost:9090/images/unknown.gif&offline=http://localhost:9090/images/user-red-16x16.gif&available=http://www.jivesoftware.com:9090/images/user-yellow-16x16.gif

This example is requesting presence information in XML format: http://localhost:9090/plugins/presence/presence?username=admin&sender=user2@localhost&type=xml