Protocols/MSNP/MSNP8/Setting Details

MSN Protocol Version 8

General · Connecting · Messaging

Authentication . Presence . Challenges . Getting Details . Setting Details . Messages . Miscellaneous . Example Session

What does this page cover?

This page explains how to alter your contact details, access rules, and privacy settings. This page is the counterpart to the page about retrieving personal details.

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 and Removing Principals

Adding Principals (ADD)

To add a principal, the client must send the ADD command.

• The first parameter is the list you want to add the principal to.
• The second parameter is the principal's account name.
• The third parameter is a nickname you assign to the principal. The official client always uses the principal's account name as the nickname, and that is why when you add a principal, his or her name always shows as his or her account name until he or she logs on and you receive an updated display name.
• If you are adding a principal to your FL, there may be a fourth parameter specifying the group ID that you are adding the principal to. If you do not specify a group ID, zero is implied. You may add the same principal to your FL later specifying another group to have the principal in multiple groups.

When you first add someone to your FL, you should receive a full set of BPRs. If they have already added you to their AL, these will be their actual phone numbers. Otherwise they will be blank, and correct values will be sent if and when they add you to their AL. Adding someone to a new group won't cause BPRs to be sent.

There are a few things you cannot do.

• You cannot add principals to your RL, and if you attempt to, you will be immediately disconnected.
• If you try to add a principal to both your AL and your BL, you will receive error 219.
• If you try to add more than 300 principals (the maximum as of March 31, 2005) to your FL, you will receive error 210.
• If you try to add an invalid email address, you will receive error 201.
• If you try to add a valid email address that does not exist, you will receive error 205.
• If you try to add a principal to your FL in a nonexistent group, you will receive error 224.
• If you try to add a principal to a list (or group within the FL) that they are already in, you will receive error 215.
• Errors 201 and 205 take priority over 224.

In addition, as of March 29, 2003, if the nickname is longer than 387 bytes (a URL-encoded character counts as three bytes, not one), you will be immediately disconnected. This is the same maximum length for setting nicknames with the REA command described below. However, the official client will not properly display names with more than 129 characters (a three-byte URL-encoded characters counts as one character). Note that 129 multiplied by 3 is 387.

If your ADD was successful, the server will reply with another ADD with the same exact parameters, except it will add the new version number in between the list type and the account name.

If you are adding a principal to your FL, you will receive four BPRs after the ADD response. These BPRs will all be blank (except MOB which is N) even if the principal has phone numbers set. Note that you do not receive BPRs if you have not sent the SYN command in the current session.

Also, if the principal is online when you add them to your FL, and you are already on their AL, you will receive an ILN with the same TrID as your ADD showing their initial status. Otherwise, you will receive an NLN if and when they add you to their AL. Note that if they're offline, this might take some time.

Below are some example of using ADD.

>>> ADD 18 AL a@b a@b\r\n
<<< 201 18\r\n

>>> ADD 19 FL non_existent_account@passport.com non_existent_account@passport.com\r\n
<<< 205 19\r\n

>>> ADD 20 AL example@passport.com example@passport.com\r\n
<<< ADD 20 AL 1200 example@passport.com example@passport.com\r\n

>>> ADD 21 BL example@passport.com example@passport.com\r\n
<<< 219 21\r\n

>>> ADD 22 AL example@passport.com example@passport.com\r\n
<<< 215 22\r\n

>>> ADD 23 FL myname_123@hotmail.com myname_123@hotmail.com 1\r\n
<<< ADD 23 FL 1201 myname_123@hotmail.com myname_123@hotmail.com 1\r\n
<<< BPR 1201 myname_123@hotmail.com PHH\r\n
<<< BPR 1201 myname_123@hotmail.com PHW\r\n
<<< BPR 1201 myname_123@hotmail.com PHM\r\n
<<< BPR 1201 myname_123@hotmail.com MOB N\r\n

>>> ADD 24 FL principal@msn.com principal@msn.com 15\r\n (nonexistent Group)
<<< 224 24\r\n

>>> ADD 25 RL principal@msn.com principal@msn.com\r\n
<o> Server Closes Connection

Removing Principals (REM)

To remove a principal, the client must send the REM command. This works almost exactly the same way as the ADD command, except that there is no nickname parameter.

If you are removing a principal from your FL and you want to remove the principal from a specific group, you may specify the group ID in the same way you did with the ADD command.

If your REM was successful, the server will reply with another REM with the same exact parameters, except it will add the new version number in between the list type and the account name. Listed below are some situations which will cause problems:

• If you remove a principal that is not on your list, whether or not it is a valid account name, you will receive error 216.
• If you attempt to remove a principal from your RL, you will be immediately disconnected.
• If you try to remove a principal from a nonexistent group, you will receive error 224.
• If you try to remove a principal from an existent group that they do not belong to, you will receive error 225.
• Error 216 takes priority over 225, and 224 takes priority over 216.

Below are some example of using REM.

>>> REM 26 AL a@b\r\n
<<< 216 26\r\n

>>> REM 27 FL non_existent_account@passport.com\r\n
<<< 216 27\r\n

>>> REM 28 FL valid_account@hotmail.com\r\n (Principal Not In List)
<<< 216 28\r\n

>>> REM 29 FL principal123@msn.com 15\r\n (nonexistent Group)
<<< 224 29\r\n

>>> REM 30 FL principal321@msn.com 3\r\n (Principal Not In Group)
<<< 225 30\r\n

>>> REM 31 FL myname_123@hotmail.com\r\n
<<< REM 31 FL 1202 myname_123@hotmail.com\r\n

>>> REM 32 FL principal@msn.com 1\r\n
<<< REM 32 FL 1203 principal@msn.com 1\r\n

>>> REM 33 AL principal@msn.com\r\n
<<< REM 33 AL 1204 principal@msn.com\r\n

>>> REM 34 RL principal@msn.com\r\n
<o> Server Closes Connection

Moving Principals Between Groups

To move a principal from one group to another, just use the REM command to remove him or her from the original group, and use the ADD command to add him or her to the target group. Because principals can be in more than one group at a time, it does not matter which order you do this in. Below is an example:

>>> REM 35 FL principal@msn.com 1\r\n
>>> ADD 36 FL principal@msn.com principal@msn.com 2\r\n
<<< REM 35 FL 1205 principal@msn.com 1\r\n
<<< ADD 36 FL 1206 principal@msn.com principal@msn.com 2\r\n

MSN also supports having a principal in multiple groups. To do this, just send the ADD command multiple times, and include a group ID each time for the additional group you would like the principal to be in.

Blocking Principals

To block a principal, first remove him or her from your AL if he or she is are already there. Then add him or her to your BL.

>>> REM 27 AL principal@msn.com\r\n
<<< REM 27 AL 3053 principal@msn.com\r\n
>>> ADD 28 BL principal@msn.com principal@msn.com\r\n
<<< ADD 28 BL 3054 principal@msn.com principal@msn.com\r\n

Renaming Principals (REA)

Read this for how to set your display name as well.

To set the nickname of any principal already in any of your lists, you must use the REA command. The REA command has two parameters: the account name of the principal you want to modify, and the new URL-encoded nickname that you want to assign to that principal. If successful, the server will respond with another REA with a new version number, the principal's account name, and the principal's new nickname.

If you use your own account name for the account name parameter, this command will officially change your display name and inform all other on-line principals with a new NLN (unless you are appearing offline or blocking those principals). If you attempt to change your display name too rapidly, you may receive error 800 in response to some REAs. Note that this does not apply to renaming other principals.

As in the ADD command, if the nickname you assign is longer than 387 bytes (as of March 29, 2003), you will be immediately disconnected. However, the official client will not allow principals to set names to more than 129 characters (a three-byte URL-encoded character counts as one character) and will not properly display names with more than 129 characters. If you try to rename a principal that is not in any of your lists, you will receive error 216. This even applies if the account name is an invalid email address.

If MSN for some reason does not like the new nickname has words that MSN does not allow to be in nicknames, the server will send error 209. The server will also send this error if you attempt to change your own display name with this command and your Passport has not yet been verified. (When you sign up for a Passport, you receive an email where you must click on a link to verify your Passport.) Note that error 209 has priority over error 216 when giving invalid principals invalid nicknames.

Some well-known restricted words in nicknames are "msn" and "microsoft". It is very easy to get around this restriction on nicknames. When you set a nickname, just URL-encode all or some of the letters in a restricted word, and MSN will not detect that the nickname is invalid. For example, instead of setting a nickname to "MSN%20SUCKS", set it to "%4DSN%20SUCKS", or your client could even encode every single character. Note that %4D is "M" and %20 is the space character.

Below are some examples of setting nicknames:

>>> REA 101 random_principal@randomdomain.com nickname\r\n (Principal Not In List)
<<< 216 101\r\n

>>> REA 102 mypassport@passport.com msn%20help\r\n
<<< 209 102\r\n

>>> REA 103 mypassport@passport.com new%20name\r\n
<<< REA 103 3055 mypassport@passport.com new%20name\r\n

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).