Protocols/MSNP/Notification/SettingDetails

MSNP Protocol

Introduction • Terms • Clients

Reference

Error List • Commands • Relying Party Suite • Spotlife

Services

XMPP • HTTP Gateway • Tabs • Activities

Documentation

Development Tools • MSNP Grid

Polygamy • URLs used by MSN

Documents

Protocol Versions

Version 21

Version 18

Version 16

Version 15

Version 14

Version 13

Version 12

Version 11

Version 9

Version 8

Version 2

MSNC

Introduction • P2P • Object Descriptor • Display Pictures • File Transfer

Scenarios

Microsoft Messenger for Mac

MSNP on WebTV (MSNTV)

Privacy Settings

GTC

To change your GTC value, send the GTC command with a TrID and the new value as the parameter. If successful, the server will return a GTC with your TrID, the new version as the first parameter, and the new GTC value as the second parameter. If you tried to change it to the value it was already set to, you will receive error 218. If you send an invalid parameter, you will be immediately disconnected.

Here are some examples of setting your GTC value:

>>> GTC 20 A\r\n
<<< GTC 20 200 A\r\n
>>> GTC 21 N\r\n
<<< GTC 21 201 N\r\n
>>> GTC 22 N\r\n
<<< 218 22\r\n
<<< GTC 23 F\r\n


<o> Server Closes Connection

BLP

Changing this value is similar to changing your GTC. Here are some examples.

>>> BLP 24 AL\r\n
<<< BLP 24 202 AL\r\n
>>> BLP 25 BL\r\n
<<< BLP 25 203 BL\r\n
>>> BLP 26 BL\r\n
<<< 218 26\r\n
<<< BLP 27 FL\r\n


<o> Server Closes Connection

Setting Your Phone Numbers

To set a personal phone number, send the PRP command with a TrID, the three letter code for the phone type, and the phone value. To set an empty phone number, leave out the second parameter. To disable or unregister your MSN Mobile device, set the second parameter to "N".

If successful, the server will respond with a single PRP with a TrID, version number, three-letter code, and phone number.

• If you send a phone number longer than 95 bytes, (counting a URL-encoded character as three bytes), the server will immediately close the connection with no error.
• If you try to set a nonexistent phone type of three or less characters such as phh or PH, the server will respond with error 715.
• If the phone type is longer than three characters, the server will immediately close the connection.

If you try to set MOB to anything when MBE is set to N, the server will respond with MOB still being set to N and no changes will be made. You can set MBE to Y even if you do not have a mobile device set up, which doesn't make much sense. You can also set MBE to N and leave MOB still as Y.

If you set either MOB or MBE to something besides Y or N, the server will set it to N, regardless of what it says in its response. There are a lot of weird exceptions to all of this, so just try to keep weird things from happening.

Below are some examples of setting personal phone numbers:

>>> PRP 55 PHH 555-1234\r\n
<<< PRP 55 12183 PHH 555-1234\r\n
>>> PRP 56 PHW\r\n
<<< PRP 56 12184 PHW\r\n
>>> PRP 57 PHV 1234\r\n
<<< 715 57\r\n
>>> PRP 58 MOB Y\r\n
<<< PRP 58 12185 MOB Y\r\n

Adding Principals (ADC)

Adding a Contact Initially

To add a new buddy to your contact list you must sent:

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

• The first parameter ("FL" in this example) indicates the list we wish them to be added to.
• The N= parameter contains the passport address of the contact being added.
• The F= parameter contains the friendlyname that they will be identified as. This parameter should only added when adding to the FL list. Also note that you can safely set this parameter to (for example) the email address of the person, seeing as the server will always send the updated nickname with an ILN or NLN command back to you.

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 a "ILN" and an optional "UBX" command (scroll down) if the contact is online, indicating their status and personal message (if they have one).

• The C= parameter is the GUID of the contact mentioned in the LST section above. This parameter will only be present if the person has been added to the FL, otherwise (AL, Bl, etc) it will be left out.

Copying a Contact to Another Group

This is accomplished by sending a command such as:

 < 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 group ID (GUID) of the group we're copying them to.

Removing Principals (REM)

This command now takes three distinct forms:

Deleting a contact from your Forward List

This form is very similar to the old (MSNP8) 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 deleting 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 previous added to when you re-add them to the FL list! Therefor it is wise to first remove them from any groups (see below).

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

Deleting a contact from a group

To remove a contact from a group, you must use the above syntax and remove the contact from the FL, but must also specify a 4th parameter, the group ID:

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

• Note that contacts can also be group less. Therefor, if you have removed the contact from all groups, they will still appear on the FL as group-less buddies. If you want to completely remove the contact, first remove them from all your groups, and then remove them from the FL itself (see above).

Deleting a contact from any other list

To remove the contact from any other list you can use the old MSNP8 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 hex string to contacts not on your Forward List.

Groups

Every principal on your FL can belong to one or more groups. If no group is specified, the principal automatically belongs to group zero. Each group has a name and a group ID, and groups are always referred to by their IDs. The group name is solely for end-user display purposes.

Adding Groups (ADG)

To add a group to your contact list, send the ADG command. The first parameter will the be URL-encoded choice for the name of the group, and the second parameter is a zero.

• If the length of the group name is longer than 128 bytes (as of March 29, 2003), the server will immediately disconnect you.
• If the length of the group name is greater than 61 bytes (as of March 29, 2003), you will receive error 229. Note that %20 counts as three bytes, not one (and the same idea applies for all similar entities).
• If you try to add a 31st group (30 is the maximum as of March 29, 2003), you will receive error 223. Note that group zero counts as a one of the 30 groups.

If the ADG was successful, the server will respond with an ADG. The first parameter will be your new version number. The second parameter will be the group name (should be the same one you specified). The third parameter will be the group ID. The fourth parameter should be a zero.

Here are some examples of using the ADG command:

>>> ADG 37 this%20group's%20name%20is%20sixty%20two%20bytes%20in%20length 0\r\n
<<< 229 37\r\n

>>> ADG 38 My%20New%20Group 0\r\n
<<< ADG 38 4029 My%20New%20Group 4 0\r\n

>>> ADG 39 thirtyfirst%20group 0\r\n (31st Group)
<<< 223 39\r\n

Because every group is represented by a group ID, you may have multiple groups with the same name. Make sure your client can deal with that. Also, because you cannot have more than 30 groups, all group IDs will be between 0 and 29. Group IDs are recycled (if you have thirty groups, and remove group 3, and add another group, it will become group 3). But don't rely on this, and assume group IDs can be of any reasonable size.

The final parameter in ADG is a little weird. At earlier dates (still with MSNP7), the server would reply with a weird string instead of another zero. If you specify another number instead of a zero, nothing will be done differently, but the server will respond with that same number. I'm not sure what this parameter is for, and if you have any clues, I'd like to hear about it.

Removing Groups (RMG)

To remove a group from your contact list, send the RMG command with the only parameter being the group ID. The server will respond with an RMG with the version number as the first parameter and the group ID as the second parameter. If the group doesn't exist, the server will respond with error 224. If you try to remove group zero, you will receive error 230.

If you remove a group, remember that every principal that is in that group is no longer in that group. If a principal was in multiple groups, he or she will still be in the other groups. But if it was his or her only group, he or she will be erased from the FL.

>>> RMG 40 4\r\n
<<< RMG 40 4030 4\r\n
>>> RMG 41 4\r\n
<<< 224 41\r\n
>>> RMG 42 0\r\n
<<< 230 42\r\n

Renaming Groups (REG)

To rename a group, send the REG command. The first parameter is the ID of the group you want to rename. The second parameter is the URL-encoded name that you want to group to be renamed to. The third parameter is exactly the same as the final parameter in ADG: The client always sends zero, but you can send other numbers and nothing changes.

Just like in the ADG command, if you rename a group to have more than 128 characters (as of March 29, 2003), you will be immediately disconnected. However, there is no error on names of any less length. So if you want to have a group with 127 characters, you must first add the group to be 61 or less characters, and then rename it to have 127. If you try to rename a nonexistent group, you will get error 224. Because of the 30-group limit, if you try to rename a group with a group ID greater than 29, you will be immediately disconnected. This is not true for removing groups. Also, there is nothing wrong with renaming the group with the ID of zero.

If the REG was successful, the server will respond with an REG. The first parameter will be your new version number. The second parameter will be the group ID. The third parameter will be the new group name (should be the same one you specified). And the fourth parameter is the same as in the ADG command (normally a zero).

Below are some examples of using the REG command:

>>> REG 43 3 My%20New%20Name 0\r\n
<<< REG 43 4031 3 My%20New%20Name 0\r\n
>>> REG 44 20 NewName 0\r\n (Group Does Not Exist)
<<< 224 44\r\n
>>> REG 45 30 NewName 0\r\n
<o> Server Closes Connection

When other people change their details

Reverse List Changes

When someone adds you to/removes you from their forward list, they are added to/removed from your reverse list, so you will receive an ADD or REM from the server. It will have a TrID of zero, and three or four parameters:

• The first parameter will always be RL
• The second parameter will be the new version number
• The third parameter will be the principal's account name
• If it is an ADD, the fourth parameter will be the principal's display name

Here are some examples:

<<< ADD 0 RL 3049 example@passport.com My%20Name\r\n
<<< REM 0 RL 3050 example@passport.com\r\n

Phone numbers

When someone on your forward list updates their phone numbers, you should receive a BPR message just like after receiving an ADD. Even if you are sent several BPRs at once, each one will have a different version number.

Unlike BPRs received in a SYN, this command has four parameters:

• The first parameter is the new version number
• The second parameter is the principal's account name
• The third parameter is the phone number type (PHH, MOB, etc.)
• The fourth parameter is the phone value

Here is an example BPR command:

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

When you block someone, they will automatically be sent blank BPRs (if your phone numbers weren't blank already).