Protocols/MSNP/MSNP11/Changes

MSN Protocol Version 11

Overview · Challenges · Changes · Example Session

Overview

MSNP11 has introduced a lot of new features, and with these new features come new and/or changed commands. This page is dedicated to describing the differences between MSNP9 and MSNP11 including new, changed and removed commands. MSNP10 can be assumed to be the same, except for missing the UUX command.

Contact list version numbers have been dropped from MSNP10 and above. This affects the SYN, GTC, BLP, ADG, REG, RMG, ADD (now ADC), REM, REA (now PRP/SBP), PRP and BPR commands. See below.

Changed Commands

SYN

The SYN ('synchronise') command now has an extra parameter. The two parameters must be set to 0 to retrieve the full contact list, or contain the timestamp from a previous SYN reply if you only wish to receive contact list when something has changed:

 < SYN 8 0 0\r\n
 > SYN 8 2005-04-23T18:57:44.8130000-07:00 2005-04-23T18:57:54.2070000-07:00 5 0\r\n

• The 1st is the Transaction ID
• The 2nd and 3rd are used when you want to cache your contact list, phone numbers and settings
• The 4th is the Number of Contacts
• The 5th is the Number of Groups

If the 2nd and 3rd parameter are the same timestamp, the number of contacts and groups won't be specified and you can continue to use the old cached version of your contact list. If they are not equal, you will have to resync everything. This, of course, only applies if you sent timestamps with the SYN command in the first place.

LSG

The LSG has changed slightly, now using GUIDs to identify groups:

 > LSG Other%20Contacts xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n

The first parameter is the group name, and the second is the group's GUID. Note that there is no longer an 'Other Contacts' group. Instead contacts when first added will be groupless.

LST

The syntax of the LST command has changed dramatically. This command now takes the format:

 > LST N=email@addr.ess F=Display%20Name C=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 13 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n

• C is the contact's GUID (where x is a (lower case) hexadecimal digit). This field will only be specified when the contact is on the FL.
• The number parameter (13) is the so-called listbit. This number gives you information about all the lists a person is on -- 1=Forward, 2=Allow, 4=Block, 8=Reverse and 16=Pending. You can check if someone is on a specific list by ANDing the number (ie. 13 & 1 gives 1, so the person is on the FL, likewise 13 & 2 gives 0, so the person is not on the AL).
• The F= parameter may be omitted in case the person is not on the FL. This is however not always the case, so be prepared to receive it anyway!
• After the listbit parameter come the group IDs, separated by commas (considering someone can be in multiple groups!). This parameter will only be sent if the person is also on the FL (which is logical, someone cannot be in a group when they aren't on the FL). Each group ID will be sent to you with an LSG command. Contacts on the FL are not always added to a group! (see LSG above).

BPR

New in MSNP11 is the HSB (Has Blog) setting, which is used to indicate that the principle has an (updated) MSN Space blog. Other values are PHM (Phone Mobile), PHW (Phone Work), PHH (Phone Home), MOB (MSN Mobile device enabled) and WWE (MSN Direct device enabled).

This command is received immediately after receiving an LST command while synchronising. It contains no way of identifying the principle that it refers to, so you must assume that it is for the most recently sent LST.

 > BPR HSB 1\r\n

If one of your contacts changes one of the above settings while you are online (i.e. after synchronising), the BPR command will include the principle's E-mail address.

 > BPR example@passport.com PHH 555%20555-4321\r\n

USR/PRP

Your display name is now received in the PRP command along with the other PRPs after SYN and no longer in USR OK.

USR OK is exactly with same as before but with one less parameter:

 > USR 6 OK <E-mail address> 1 0\r\n

Setting your display name is now done with the PRP command:

 < PRP 9 MFN My%20New%20Name\r\n
 > PRP 9 MFN My%20New%20Name\r\n

As usual, the 9 is the TrID, MFN stands for 'My Friendly Name', and your new display name must, as always, be UTF8 and URL encoded. This new method, along with SBP (see below), obsoletes the REA command.

ADD/ADC

The change in group and contact GUIDs also affects the ADD command, including changing the name to ADC (ADd Contact).

Adding a Contact Initially

To add a new contact to your contact list, you must send:

 < ADC 16 FL N=passport@hotmail.com F=Display%20Name\r\n

• The first parameter (FL in this example) indicates the list we wish to add them to.
• The N= parameter contains the passport address of the contact being added.
• The F= parameter contains the friendly name that they will be identified as. This parameter should only be included when adding to the FL. If you do not have a friendly name for this contact (i.e. it's a new contact), you should either set this parameter to their E-mail address or omit it. If you do have a friendly name for them, setting this to the contact's E-mail address will result in loss of their friendly name until they are next seen online.

The Notification server will then reply (assuming all parameters are correct) with:

 > ADC 16 FL N=passport@hotmail.com F=Display%20Name C=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n

Followed by an ILN and an optional UBX (see below) if the contact is online, indicating their status and personal message (if they have one).

The C= parameter is the contact's GUID (mentioned in the LST section above). This parameter will only be present if the person has been added to the FL.

Adding a Contact to a Group

Before you can add a contact to a group, you must first add them to your FL (see above).

Adding a contact to a group is accomplished by sending:

 < ADC 19 FL C=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n

• FL is the list (FL/AL/BL/RL/PL). C= is the contact's GUID (you must always use the GUID, and not the E-mail address (N=) when dealing with the FL!).
• The final parameter is the GUID of the group we're adding them to (received in LSG or ADG).

REM

This command now takes 3 distinct forms:

Removing a contact from your Forward List

This form is very similar to the old (pre-MSNP10) command, the only difference being that the GUID for the contact is used, rather than their passport address:

 < REM 22 FL xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n

• FL is the list we're removing the contact from.
• The hex string is the contact's GUID.
• This does not remove the contact from any groups! While it physically removes the contact from your list, they will re-appear in the groups they were previously added to when you re-add them to the FL! Therefore, it is wise to first remove them from any groups (see below).

If successful, the server will echo the command back to you.

Removing a contact from a group

To remove a contact from a group, you must use the above syntax to remove the contact from the FL, but must also specify a 4th parameter, the group's GUID:

 < REM 22 FL xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n

Note that contacts can also be ungrouped. Therefore, if you have removed the contact from all groups, they will still appear on the FL as ungrouped contacts. If you want to completely remove the contact, first remove them from all groups, then remove them from the FL itself (see above).

Removing a contact from any other list

To remove the contact from any other list, you can use the pre-MSNP10 syntax:

 < REM 22 AL passport@hotmail.com\r\n

Where passport@hotmail.com is the account you wish to remove from the list specified as the first parameter. The reason for the difference between the two is that the server does not assign a GUID to contacts not on your Forward List.

New Commands

SBS

The SBS command is being sent directly after authentication (between USR OK and the initial profile MSG). The meaning of the command is unknown, but it is related to your mobile credits (MSN Mobile) or the number thereof. When you have no credits, 'null' will be sent as a parameter:

 > SBS 0 SC=Some-ID-here;SI=Another-ID;SS=2;PS=2\r\n
 > SBS 0 null\r\n

SBP

Previously done with REA, renaming contacts is now done with the new SBP command. Please note that while the official client does not support contact renaming, it still uses the SBP command. When the official client encounters a new name for the contact (in ILN and NLN), it will update your 'copy' of that contact's nickname using SBP; otherwise, you would still receive their old nickname in LST. This, however, can be put to better use (as I have done in my own client) by allowing you to set your own nickname for contacts.

 < SBP <TrID> <Contact's GUID> <Setting> <URL-Encoded Value>\r\n

As with PRP, 'setting' should be set to 'MFN' to change the contact's nickname. You might also be able to edit the contact's phone numbers yourself (if they haven't entered them) using this command, but I haven't tested this yet.

If successful, the server will echo the command back to you.

UUX

This is the command used to set your Personal Message (PSM) or currently playing song. It is a payload command, with the only parameter after the TrID being the length of the payload:

 < UUX 10 72\r\n

If this command is successful, the server will reply with a message containing the TrID you used and a 0 as the only parameter.

 > UUX 10 0\r\n

The contents of the payload depend on whether you have a currently playing song or not.

Without a Current Media

 <PSM>My Personal Message</PSM><CurrentMedia></CurrentMedia>

The contents of the PSM tag is your personal message (XML encoded!), leaving <CurrentMedia> blank. Both may be specified, but this is not recommended. See below to find out how to set both and show only the one you want (Enabled setting).

The client will always limit your PSM to 129 characters (same as the friendly name). Server-wise however, a payload of up to 1KB (including XML) is being accepted. The client will always show only 129 characters in the main contact list, but will show the full PSM in conversation windows.

With a Current Media

The value of the CurrentMedia tag can be thought of as an array separated by the string "\0" (literal backslash followed by zero, not NULL). The elements of this 'array' are as follows:

• Application - This is the app you are using. Usually empty (ITunes,Winamp and WMP are the only ones known to be accepted)
• Type - This is the type of PSM, either 'Music', 'Games' or 'Office'
• Enabled - This is a boolean value (0/1) to enable/disable the Current Media setting
• Format - A formatter string (you may be familiar with this syntax if you've used .NET); for example, "{0} - {1}"
• First line - The first line (Matches {0} in the Format)
• Second line - The second line (Matches {1} in the Format)
• Third line - The third line (Matches {2} in the Format)

There is no known limit to the number of formatter tags, but it is speculated to be 99.

Examples of the CurrentMedia Tag

Currently Playing Song

 <CurrentMedia>\0Music\01\0{0} - {1}\0 Song Title\0Song Artist\0Song Album\0\0</CurrentMedia>

Playing a Game

 <CurrentMedia>\0Games\01\0Playing {0}\0Game Name\0</CurrentMedia>

Microsoft Office

 <CurrentMedia>\0Office\01\0Office Message\0Office App Name\0</CurrentMedia>

UBX

UBX is the sister command to UUX. UUX is used to set your personal message, UBX is sent by the server to all principles to inform them of the change (where B means Buddy). The format is similar to UUX; they are payload commands where the first parameter is the passport address of the contact who has just changed their personal message or currently playing song, and the second parameter is the length of the payload:

 > UBX passport@hotmail.com xxx\r\n
 <PSM>My Personal Message</PSM><CurrentMedia></CurrentMedia>

 > UBX passport@hotmail.com xxx\r\n
 <PSM></PSM><CurrentMedia>\0Music\01\0{0} - {1}\0Song Title\0
 Song Artist\0Song Album\0{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\0</CurrentMedia>

(Sent on one line - split for ease of viewing here)

GCF

With this new payload command, it is possible to request a configuration file from the server. Currently, only the file Shields.xml is known, which is an XML file that controls blocking of security sensitive items like hyperlinks, Winks and Dynamic Display Pictures.

 < GCF 29 Shields.xml\r\n
 > GCF 29 Shields.xml 159\r\n
   <?xml version="1.0" encoding="utf-8" ?>\n
   <config>\n
     <shield>\n
       <cli maj="7" min="0" minbld="0" maxbld="9999" deny=" " />\n
     </shield>\n
     <block></block>\n
   </config>\n

The first field is the TrID, 2nd the filename, and the 3rd the length of the payload in bytes.

Shields.xml is believed to be able to also contain the element 'imtext', perhaps containing some text that should be shown in the IM window. Inside the 'block' nodes, two subnodes can be found: 'hashes' and 'regexp'. What these two nodes do is not yet known, but it is suspected they block out certain filenames and files with certain hash values.

The 'deny' attribute in the 'cli' node can contain the following strings (separated by spaces to indicate multiple blocked features):

• SharingFolders (WLM only)
• protocolhandler (Unknown)
• dynamicbackgrounds
• phone (WLM only)
• voiceim
• camera
• audio
• filexfer
• hotlinks (Regular clickable links)
• ddp
• winks

Removed Commands

The ADD command has been removed, in favour of ADC. Use of ADD in MSNP10 or higher will result in immediate disconnection.

REA has also been removed and replaced with PRP and SBP (see above). Use of REA will probably also result in disconnection, although I haven't tested this.

Reverse List Additions

This has been changed so much that it warrants its own section.

When someone adds you to their contact list, you will get the standard ADC command from the server informing you of this change:

 > ADC 0 RL N=their@email.address F=Display%20Name\r\n

You can then add them to your Forward List (if you want, you may also safely ignore the command) and your Allow or Block list. Providing the parameters are correct, you will receive responses from the server:

 < ADC 55 FL N=their@email.address F=their@email.address\r\n
 > ADC 55 FL N=their@email.address F=their@email.address C=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n
 < ADC 56 AL N=their@email.address\r\n
 > ADC 56 AL N=their@email.address\r\n

If you added them to your Forward list and they are online (or, rather, not offline), the notification server will tell you their status and any personal message they have (see the UBX command).

 > ILN 55 NLN their@email.address Display%20Name 1073860652 <msnobj>\r\n
 > UBX their@email.address xx\r\n
   <PSM>Help NINA Wiki grow!</PSM><CurrentMedia></CurrentMedia>

That's all fairly straight-forward and as expected. However once you sign out and then sign back in again, this contact will have a list value in the high teens. This is because there is now a fifth list, the Pending List, with an identifier of 16. When combined, for example, with the values for the Forward list (1) and Allow list (2) they get a list value of 19.

Bitwise comparisons to demonstrate which lists a contact with a value of 19 is in:

• 19 & 1: 1 (They are on our FL)
• 19 & 2: 2 (They are on our AL)
• 19 & 4: 0 (They are NOT on our BL)
• 19 & 8: 0 (They are NOT on our RL)
• 19 & 16: 16 (They are on our PL)

Note that they do not appear on your RL, even though the server informed us to the contrary when they added us to their FL. Note also that while a contact is on the PL, they will not be able to see your status.

To 'solve' this problem, we must manually add them to the RL (yes, that's possible now, but presumably only if they're on the PL) and remove them from the PL. The official client (V7 and above) handles it as follows:

 > LST N=their@email.address F=Display%20Name C=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 19\r\n
 < ADC 31 RL N=their@email.address\r\n
 > ADC 31 RL N=their@email.address\r\n
 < REM 37 PL their@email.address\r\n
 > REM 37 PL their@email.address\r\n

Once off our PL and on our RL, the contact can see our status and everything will work as expected. Note that when you have already synchronised your lists, you MUST do the ADC/REM for the RL/PL! The next time you sign in, they will not appear on your PL any more (as expected).