Sending and Receiving Application Messages (JavaScript Library)

Ff751471.note(en-us,MSDN.10).gifNote:
Current information about Live Connect is now available in the Windows Live Developer Center. The information in the following sections is provided for legacy purposes only.

You can use messaging extensions to enable users to send and receive different types of data in the messaging client. The default messaging extension supports sending and receiving JavaScript Object Notation (JSON) data, but you can define your own factory class to send and receive other types of data. Some examples include:

  • A wink feature is a custom message type that contains the index of an icon. The receiving client can display the corresponding icon, based on the value in the custom message.
  • A mapping feature that enables messaging clients to exchange latitude and longitude. The data can be used to display the location of each conversation participant on a map.

To create a custom message type, you should first decide if your application can use a default factory and application message class, or whether you can implement your own.

The default application message factory is easier to use, but supports only serializing and deserializing JSON objects.

To send an Application Message by using the default factory
  1. Create a SimpleApplicationMessage object with the specified JSON information that you want to send.

    var jsonObject = { param1: "value1" };    // On the receiving end, we can access the value by doing jsonObject.param1
    var expectedMessage1 = new Microsoft.Live.Messenger.Messaging.SimpleApplicationMessage(jsonObject);
    
  2. Send the message to the specified user.

    Microsoft.Live.App.get_messengerContext().sendMessage("234234234", expectedMessage1);
    

If your application needs more specialized logic for its application messages, then it must implement its own extension of the ApplicationMessage and ApplicationMessageFactory classes. Custom ApplicationMessageFactory cannot use the "json" and "xml" names, which are reserved.

Implementing application messaging through a custom application message factory involves the following steps:

  1. Create an ApplicationMessageFactory object with the serialize method and the deserialize method.
    The serialize method outputs a string representation of the message extension object.
    The deserialize method recreates the message extension from the string representation.
  2. Create an ApplicationMessage object.
    This object must support the get_id() method, and can be extended to contain other methods and data.
  3. Add code to assign the custom ApplicationMessageFactory to the user and to register the custom ApplicationMessage type.
  4. Send a custom message.
  5. Intercept an incoming custom message.
To create an ApplicationMessageFactory object
  1. Create the ApplicationMessageFactory object constructor.

    This object serializes and deserializes your messaging extension.

    _myMessageFactory = function _myMessageFactory(_user) {
        _myMessageFactory.constructBase(this, [ _user ]);
    }
    
  2. 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 that is returned by serialize is that value that is 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
  1. Create the ApplicationMessage object constructor.

    In this example, a custom string value is added.

    _myApplicationMessage = function _myApplicationMessage(str) {
        _myApplicationMessage.constructBase(this);
        this.myString = str;
    }
    
  2. Add methods to the ApplicationMessage object.

    The get_id() method is always required. In this example, an additional method called get_myString() is 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;
        }
    }
    
  3. 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
  • 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))
        {        
         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;
        }
    }
    

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. For more information, see the JSON website.

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

// Use the eval function to convert the string to an object.
// Typically, this is used on the receiving side.
var latLonObj = eval('(' + latLonStr + ')');

// Test it by using an alert.
Alert('latitude: ' + latLonObj.lat + ', longitude: ' + latLongObj.lon);
Show: