Protocols/MSNP/MSNP13/Changes

MSN Protocol Version 13

Overview · Changes · Challenges · Sharing Folders · Example Session
SOAP Address Book: Retrieving the lists · Updating the membership lists · Updating the AB
Other features using SOAP: Offline Messaging · Passport 3.0 authentication

New commands

ADL

'Add List' command, uses XML to identify each contact, and works as a payload message. Each ADL command may contain up to 150 contacts (a payload of roughly 7500 bytes). The format of the payload looks like this:

<ml l="1">
    <d n="domain">
        <c n="email" l="3" t="1" />
    </d>
</ml>

Elements:

• ml: the meaning of l is unknown (thought to mean initial listing due to the fact that it is only sent in the initial ADL)
• d (domain): contacts are grouped by domain, where n is the domain name (the part after the @ symbol in the email address)
• c (contact): n is the name or the part before the @ symbol in the email address, l is the list bit flag (i.e. 1 for FL, 2 for AL, 4 for BL) and t is the contact type (1 for a Passport, 4 for a mobile phone, other values are still unknown)

Note: you can send all your contacts in just one ADL command by putting multiple 'd' elements (with the sub-elements of course) for each contact e.g.:

<ml l="1">
    <d n="domain1">
        <c n="email1" l="3" t="1" />
    </d>
    <d n="domain2">
        <c n="email2" l="5" t="4" />
    </d>
</ml>

Sending ADL to the server:

>>> ADL (TrId) (PayloadLength)\r\n

Then send your payload:

>>> <ml l="1"><d n="domain"><c n="email" l="3" t="1" /></d></ml>

The payload must not contain any 'whitespace' characters (i.e. returns, tabs or spaces) between tags or at the beginning or end, or the server will reply with error 240 or 241.

The server responds to a successful ADL command with:

ADL (TrId) OK

Initial ADL listing

Once the client has retrieved the contact list with a new set of SOAP requests (see Protocols/MSNP/MSNP13/Contact_List), it will send the information about the contacts on the list to the server with an ADL command. In this ADL, the <ml> node often seems to contain the attribute l, set to 1. However, the client does not always appear to send this attribute in the official listing!

You must include everyone on your Forward List (FL), Allow List (AL) and Block List (BL). If you don't, anyone you fail to include will be removed from their respective lists. Also note that the official client does not include contacts on the RL and PL in the initial listing. In fact, if you send the RL and PL bits in the ADL, the server will reject your ADL command, and possibly disconnect you.

You MUST send your privacy settings (BLP command), then ADL and finally your display name (PRP command) in that order or the server will ignore your ADL. These are retrieved using the ABFindAll SOAP request.

After receiving ADL (TrId) OK, you must set your initial presence (CHG command). If you send CHG before ADL, the servers will not dispatch your presence to other clients.

Server-initated ADL

Just as with ADD and ADC in previous protocol versions, the server may send an ADL command. The server's response to a client-initiated ADL command (see above) does not include a payload. The server-initiated ADL command, however, does include a payload. Therefore, you must ensure that your client can distinguish between the 2.

The server-initiated ADL command has so far only been observed with one contact per command. However, it may contain more in the future, so it is recommended that your implementation supports multiple contacts per ADL. Also, unlike the client-initiated ADL, the server-initiated ADL may contain the RL and PL bits.

The format of the server-initiated ADL is the same as that of a client-initiated ADL.

RML

The RML command replaces REM and is used to remove contacts from your lists. Each RML command may contain only one contact (as opposed to the ADL command).

The format of the RML command is largely similar to ADL:

<ml>
    <d n="domain.com">
        <c n="alias" t="1" l="1" />
    </d>
</ml>

Note that you may only remove people from the FL, AL and BL using the RML command (which makes sense, seeing as you can also only add people to the FL, AL and BL with the ADL command). Also note that by using the RML command, the contact will not be removed from your address book - for this, you will have to use the ABContactDelete SOAP request.

UUN and UBN

Much like the UUX command in MSNP12, except that it is specific to a certain contact. Syntax:

>>> UUN 25 destinationemail@addr.ess 1 65\r\n
<SNM opcode="SNM" csid="{7F5AEEDC-74A7-4C98-5DEF-C8FF30C7781C}"/>
<<< UUN 25 OK

The other destined user will receive a UBN command:

>>> UBN sourceemail@addr.ess 1 65\r\n
<SNM opcode="SNM" csid="{7F5AEEDC-74A7-4C98-5DEF-C8FF30C7781C}"/>

The destined contact should then reply with another UUN accepting or declining the sharing invitation:

Accepting the invitation:

>>> UUN 36 sourceemail@addr.es 1 66\r\n
<SNM opcode="ACK" csid="{E87A6818-1AF2-FDD9-90DB-0AC02A788BDD}" />
<<< UUN 36 OK

Declining the invitation:

>>> UUN 36 sourceemail@addr.es 1 85\r\n
<SNM opcode="NAK" csid="{E87A6818-1AF2-FDD9-90DB-0AC02A788BDD}" reason="0x80070490"/>

The opcode can have the following values:

• SNM means that the clients are still in negotiation period ("Share New Media")
• ACK means that the invitation has been accepted
• NAK means that the invitation has been declined

The csid GUID field is specific to the client.

When declining, you must include the reason field. Its value is a standard Windows error code (in the above case, it's 'Element not found').

Of course, as said before, the source will receive a UBN notifying him/her if the invitation was successful or not. If it wasn't, the destination client will most likely resend a UUN with opcode="SNM".

Generating the 'reason' value

You can generate these errors by first finding the error code (in this case, ERROR_NOT_FOUND, 1168L, 0x490). These constants are defined in winerror.h if you are working with C, or if you want to know the actual values, see MSDN or this file from the WINE project.

After you've found the value, you can generate the 'reason' value using the equation below.

reason = (error_code & 0xFFFF) | (0x07 << 16) | 0x80000000

Special error codes

• 0x8F450001: Shared folders are disabled

RFS

This command will be sent to the client when the server wants the client to refresh the contact list. Because the NS no longer does the address book synchronisation (the client is expected to this instead), it is possible that the NS needs to re-acquire the user's contact list (for example, in case of a backend server shutdown).

The client responds to the RFS command with the contact list using the ADL command. The way the contact list should be submitted back to the NS is exactly the same as the initial ADL command, so it is recommended you create a method in your code that takes care of both cases.

Removed commands

ADC and REM

ADC and REM have been replaced by ADL and RML (see above).

SYN

The SYN command has been completely dropped. Instead, the client will fetch the contact list through a SOAP request, which will then be 'dumped' to the server with the ADL command. Please refer to Protocols/MSNP/MSNP13/Contact_List for more information.

GTC

The GTC command has been completely removed and is no longer accepted by the server. Sending GTC to the server will result in an immediate disconnect. Note that there is no reason for the NS to recognise GTC in the first place, seeing as it is a client-only setting. The value of GTC (A/N) may be fetched using the ABFindAll SOAP request. Please refer to Protocols/MSNP/MSNP13/Contact_List for more information.

Changed commands

XFR

The format of both XFR NS and XFR SB as received from the server has changed in MSNP13.

XFR NS

The 0 and current server parameters have been removed and replaced with the letters U and D instead. The meaning of these two parameters is still unknown.

Old format:

<<< XFR 10 NS 207.4.100.31:1863 0 207.44.103.32:1863\r\n

New format:

<<< XFR 7 NS 207.4.100.31:1863 U D\r\n

XFR SB

XFR SB now has two new parameters, the first always being U and the second being messenger.msn.com. Again, the meaning of these two parameters is still unknown.

Old format:

<<< XFR 15 SB 207.46.108.37:1863 CKI 17262740.1050826919.32308\r\n

New format:

<<< XFR 32 SB 65.54.171.31:1863 CKI 1743299383.52212212.219110167 U messenger.msn.com\r\n

RNG

As with XFR, RNG has also changed, and is now too showing the U parameter, and another parameter which until now has only been observed as being messenger.hotmail.com. It is speculated that these two parameters have something to do with direct connections, but this has not yet been confirmed.

Old format:

<<< RNG 11752013 207.46.108.38:1863 CKI 849102291.520491113 example@passport.com Example%20Name\r\n

New format:

<<< RNG 146980 207.46.2.154:1863 CKI 1138138395.4459 example@passport.com Example%20Name U messenger.hotmail.com\r\n

UBX/UUX

One change is that UUX has to be sent when signing in, and a new field has been added (MachineGuid).

>>> UUX sender@email.com (Length)\r\n
<PSM></PSM><CurrentMedia></CurrentMedia><MachineGuid>{F26D1F07-95E2-403C-BC18-D4BFED493428}</MachineGuid>

GCF

The default GCF file Shield.xml will now be sent to you after you send the USR TWN I command to the server. The layout of the XML has changed slightly, dropping the filename and instead renaming them to 'policies' (i.e. Shields.xml --> POLICY="SHIELDS").

>>> USR 3 TWN I passport@domain.com
<<< GCF 0 165
  <Policies>
    <Policy type="SHIELDS">
      <config>
        <shield>
          <cli maj="7" min="0" minbld="0" maxbld="9999" deny=" " />
        </shield>
        <block>
        </block>
      </config>
    </Policy>
  </Policies>
<<< USR 3 TWN S lc=1033,id=507,tw=40,fs=1,ru=http%3A%2F%2Fmessenger%2Emsn%2Ecom,ct=1135524557,kpp=1,kv=7,ver=2.1.6000.1,rn=zFcWKb4y,tpf=e0c103aa2bcf3968ce1ccb373a0e98d7

JOI/IRO

Both the JOI and IRO commands for the SB now have an additional parameter: the Client ID of the person that has just joined the conversation. The server probably sends this parameter so that other participants know whether they can send/receive ink, voice clips, etc., even though they might not have the new participant on their contact list.

<<< JOI email@addr.ess Inky%20| 1342558268\r\n

New Profile Fields

BetaInvites

For the duration of the beta period only, this is sent with the initial profile message (text/x-msmsgsprofile) to notify the client of the number of invitations a user has. It comes after the ABCHMigrated field. Example:

...
ABCHMigrated: 1\r\n
BetaInvites: 0\r\n
\r\n

New Message Headers (Switchboard)

Starting from WLM 8.0.0683, Microsoft has introduced several new headers for messages sent in SB sessions. Details can be found below.

Data Cast - ID 4

Setting the ID of a Data Cast to 4 allows you to send an 'action message', like the message "xyz has sent you a nudge!", but the font color is dark gray. The Data header must be set to the text you want the client to display.

Note! You must promote MSNC6 in order to receive Action Messages

MIME-Version: 1.0\r\n
Content-Type: text/x-msnmsgr-datacast\r\n
\r\n
ID: 4\r\n
Data: Your text here\r\n

PlugIn-Context Header Field

Whenever a plug-in (or 'add-in') sends a message, this field is included. It tells the receiving client(s) that the message was sent by a plug-in.

Content-Type: text/x-msnmsgr-datacast\r\n
PlugIn-Context: 1\r\n