How to: Implement Presence Extensions

Presence extensions provide a means to set custom presence properties for users of your Web-based applications. You can use presence extensions to enable users to publish presence information for other users to see. For example, a music Web site with an integrated Windows Live™ Messenger experience could publish "Now Playing" information as part of users' Messenger presence. Custom presence properties can perform a range of tasks, such as detecting when a particular pair of users is signed in.

Implementing custom presence involves the following steps.

Create a presence extension object. This object must support the get_name() method, and can be extended to contain other methods and data.
Create a >PresenceExtensionFactory object with two methods:
- >serialize(property)—This method outputs a string representation of the presence extension object.
- >deserialize(name, content)—This method recreates the presence extension from the string representation.
Set your PresenceExtensionFactory as the active presence factory.
Add the presence extension to users' presence.

Using JSON

You can use JSON to send multiple data values in one string. In the following code example, JSON is used to create a set of name-value pairs to represent latitude and longitude coordinates.

// Create the JSON string.
var latLonStr = "{'lat':'47.7575', 'lon':'-122.24278'}";

// Use the eval function to convert the string back into an object.
// This would typically be used on the receiving side.
var latLonObj = eval('(' + latLonStr + ')');

// Test it out using an alert.
alert('latitude: ' + latLonObj.lat + ', longitude: ' + latLonObj.lon);

For more information, see the JSON Web site.

Procedures

The following procedures walk you through the individual steps of implementing custom presence.

To create a presence extension object

In your JavaScript file, declare a variable containing the extension name.
This value must be unique within the application and must not exceed 64 characters.
```
var extensionName = 'com.example.ExtNm';
```
Create the necessary code for the functionality of the extension.

In this particular example, the extension stores a name-value pair. The function is used as a constructor, and the other functions in the class are defined by using the prototype property.

function MyPresenceExtension(name, content)
{
    this.name = name; 
    this.content = content;
}
MyPresenceExtension.prototype.get_name = function() {
    return this.name;
}
MyPresenceExtension.prototype.get_content = function() {
    return this.content;
}

To create a PresenceExtensionFactory object

Declare the PresenceExtensionFactory object.

This object serializes and deserializes your custom presence extension.
```
MyPresenceFactory = function () {}
```

Create the serialize and deserialize functions.

MyPresenceFactory.prototype.serialize = function(prop) {
    return prop.get_content();
}
MyPresenceFactory.prototype.deserialize = function(name, content) {
    return new MyPresenceExtension(name, content);
}

To set the PresenceExtensionFactory as the active presence factory

Add the presence factory to the user object by calling set_presenceFactory, and then creating a new instance of MyPresenceFactory.
```
User.set_presenceFactory(new MyPresenceFactory());
```

To add the presence extension to users' presence

Add the custom presence extension for the signed-in user.

function addCustomPresence() 
{
    endpointCollection = _user.get_endpoints();
    endpointPresence = endpointCollection.get_item(0).get_presence();
    extensionCollection = endpointPresence.get_extensions();
    extensionCollection.add(new MyPresenceExtension(extensionName, '*'));
}

Add code to check for the presence extension in each endpoint of this contact's presence.

function getCustomPresenceContent(address) 
{
    endpointEnum = address.get_endpoints().getEnumerator();
    while (endpointEnum.moveNext()) 
    {
        endpoint = endpointEnum.get_current();
        extensionEnum = endpoint.get_presence().get_extensions().getEnumerator();
        while (extensionEnum.moveNext()) 
        {
            extension = extensionEnum.get_current();
            if (extension.get_name() == extensionName) 
            {
                return extension.get_content();
            }
        }
    }
    return '';
}

Example

The following example demonstrates the complete process for implementing the example name-value custom presence extension.

// **** CUSTOM PRESENCE ****
MyPresenceFactory = function () {}
MyPresenceFactory.prototype.serialize = function(prop) {
    return prop.get_content();
}

MyPresenceFactory.prototype.deserialize = function(name, content) {
    return new MyPresenceExtension(name, content);
}

var extensionName = 'MLSDK';
   
function MyPresenceExtension(name, content)
{
    this.name = name; 
    this.content = content;
}

MyPresenceExtension.prototype.get_name = function() {
    return this.name;
}

MyPresenceExtension.prototype.get_content = function() {
    return this.content;
}

/* Add a custom presence extension to the signed-in user */
function addCustomPresence()
{
    endpointCollection = _user.get_endpoints();
    endpointPresence = endpointCollection.get_item(0).get_presence();
    extensionCollection = endpointPresence.get_extensions();
    extensionCollection.add(new MyPresenceExtension(extensionName, '*'));
}      

// For each endpoint of this contact's presence, check for presence extension
function getCustomPresenceContent(address)
{
    endpointEnum = address.get_endpoints().getEnumerator();
    while (endpointEnum.moveNext())
    {
        endpoint = endpointEnum.get_current();
        extensionEnum = endpoint.get_presence().get_extensions().getEnumerator();
        while (extensionEnum.moveNext())
        {
            extension = extensionEnum.get_current();
            if (extension.get_name() == extensionName)
            {
                return extension.get_content();
            }
        }
    }
    return '';
}
// **** END CUSTOM PRESENCE ****

Concepts

Windows Live Messenger Library Tasks