How to: Implement Messaging Extensions

Messaging extensions provide a way to create custom application message types that can extend the functionality of a messaging client by facilitating the exchange of different types of data. Some examples include:

A wink feature, in which a custom message type containing the index of an icon is sent. The receiving client could then display the corresponding icon based on the value in the custom message.
A mapping feature, in which latitude and longitude is exchanged between messaging clients, and is subsequently used to display the location of each conversation participant on a map.

You can create a custom message type by implementing the ApplicationMessage and ApplicationMessageFactory classes, and then extending the >ApplicationMessage class.

Implementing custom messaging involves the following steps:

Create an >ApplicationMessageFactory object with two methods:
- serialize(message)—This method outputs a string representation of the message extension object.
- deserialize(sender, id, content)—This method recreates the message extension from the string representation.
Create an ApplicationMessage object. This object must support the get_id() method, and can be extended to contain other methods and data.
Add code to assign the custom ApplicationMessageFactory to the user, and to register the custom ApplicationMessage type.
Send a custom message.
Intercept an incoming custom message.

Send Multiple Data Values with 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 to send.
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 messaging extensions.

To create an ApplicationMessageFactory object

Create the ApplicationMessageFactory object constructor.

This object serializes and deserializes your messaging extension.
```
_myMessageFactory = function _myMessageFactory(_user) {
    _myMessageFactory.constructBase(this, [ _user ]);
}
```

Create the serialize and deserialize functions.

In this example, the serialize method returns a string value, but the return value varies depending on the implementation. The value returned by serialize is what ultimately gets sent.

_myMessageFactory.prototype = {
   
    deserialize: function deserialize(sender, id, content) {
        if (id == _myApplicationMessage.Id)
        {
            return new _myApplicationMessage(content);
        }
        else
        {
            return null;
        }
    },
   
    serialize: function serialize(message) {
        return (message).get_myString();
    }
}

To create an ApplicationMessage object

Create the ApplicationMessage object constructor.

In this example, a custom string value is added.

_myApplicationMessage = function _myApplicationMessage(str) {
    _myApplicationMessage.constructBase(this);
    this.myString = str;
}

Add methods to the ApplicationMessage object.

The get_id() method is always required. In this example, an additional method called get_myString() has been added to handle the custom string value for this class.

_myApplicationMessage.prototype = {
    myString: null,
   
    get_id: function get_id() {
        return _myApplicationMessage.Id;
    },
   
    get_myString: function get_myString() {
        return this.myString;
    }
}

Assign a value to the Id property for the object.
```
_myApplicationMessage.Id = 'msgid';
```

To assign the ApplicationMessageFactory to the user and register ApplicationMessage

Add the following code to the end of your OnSignInCompleted function.

if (!_user.get_messageFactory()) 
{
    _user.set_messageFactory(new _myMessageFactory(_user));
    if (!_user.get_messageFactory().isRegistered(_myApplicationMessage.Id)) 
    {
        _user.get_messageFactory().register(_myApplicationMessage.Id);
    }
}

To send a custom message type

In this example, the message function checks to see if the current conversation supports the ID of the message. If it does, the message is sent.

function sendCustomMsg()
{
    if (_conv.supportsApplicationMessageType(_myApplicationMessage.Id))
    {
        if (_user) 
        {
        var message = new _myApplicationMessage(customMessageMenu.selectedIndex.toString());
        _conv.sendMessage(message, null);
        }
    }
}

To intercept an incoming custom message type

The following function uses a switch statement to determine the MessageType of an incoming message, and then takes the appropriate action.

function recvMsg(sender, e)
{
    switch (e.get_message().get_type()) 
    {
        case Microsoft.Live.Messenger.MessageType.applicationMessage:
            var customMessage = e.get_message();
            if (message.get_id() == _myApplicationMessage.Id) 
            {
                // Add code to handle the message content here.
            }
            break;
        case Microsoft.Live.Messenger.MessageType.textMessage:
            var message = e.get_message();
            // Add code to handle the message content here.
            break;        
        default:
            break;
    }
}

Concepts

How to: Implement Presence Extensions
Developing with the Windows Live Messenger Library