Protocols/MSNP/Notification/GettingDetails
What does this page cover?
This page explains how to retrieve your personal details from MSN Messenger. This includes information about people on your contact list, a list of groups they can belong to, your personal phone numbers, and some privacy settings.
When the official client logs on, the first thing it does is send the SYN command to retrieve everything on the contact list. This page gives background information about your contact details and a thorough description of the SYN command. For information about setting your personal details, see Setting Details.
Background Information
These are the basic concepts in MSN's personal information.
Version number
Your complete set of personal details has a version number. Every time a change is made to the contact list, either initiated by you or by someone else, that number is incremented. If your details are changed then changed back (even while you're offline), the number will be incremented twice.
The purpose of this number is to ensure that the client and server have the same version of the contact details. Clients should cache all contact details. When the client logs on, if no changes have been made since it last logged off, it can avoid downloading all of your personal details. The number is always between 0 and 4294967295 (2^32 - 1).
Forward List (FL)
The forward list, abbreviated as FL, is the list of principals whose presence you are subscribed to. You can expect to be notified about their on-line state, phone numbers, etc. This is what a layman would call their "contact list".
This list currently (as of March 23, 2003), has a limit of 150 people, doubled from a previous 75. If you try to add a 151st person, you will receive error 210 and they will not be added.
Everyone in your forward list belongs to one or more groups, identified by their group number. By default, they belong to group 0.
Reverse List (RL)
The reverse list, abbreviated as RL, is the list of principals that have you on their forward list. You cannot make modifications to it. If you attempt to add or remove people from this list, you will be immediately disconnected from the NS with no error message.
Allow List (AL)
The allow list, abbreviated as AL, is the list of principals that you allow to see your online presence - as opposed to your reverse list, which is the list of people who request to see your online presence. If someone removes you from his or her contact list, he or she is automatically removed from your RL but not your AL. He or she no longer receives online presence from you, but if he or she adds you again, your client can act in the knowledge that you previously allowed him or her to see your presence.
Block List (BL)
The block list, abbreviated as BL, is the list of people that are blocked from seeing your online presence. They will never receive your status, and when they try to invite you to a switchboard session, they will be notified that you are offline. No-one can be on the AL and the BL at the same time, and if you try to add someone to both lists, you will receive error 219.
Group List
This is a list of groups that people on your forward list can belong to. Every group has a name and a ID number. You are guaranteed to have at least one group defined (which everyone on your contact list belongs to by default). The default name for this list is "~".
The client and server always refer to groups by number rather than name.
Phone Numbers
MSN Messenger allows you to advertise your personal, home, and work phone phone numbers as well as your MSN Mobile and MSN Direct devices if you have them. You should be automatically sent phone number information about people in your FL, but as of November 2003, a bug in Microsoft's servers mean this doesn't happen. You can choose whether or not to make phone numbers available, and blocked people are sent blank phone number information, so there is no big privacy issue with it.
Synchronisation
The SYN ("synchronisation") command is used to synchronise all four contact lists, the group list, your phone numbers, and some privacy settings with the server. The official client synchronises right after it logs on and before it sets its initial status. Sending SYN more than once in a session has no effect, and may get you disconnected. You should send SYN immediately after logging in to the Messenger server, as the server won't send you certain commands (e.g. additions to your reverse list) until you do. Clients should store a cached version of your details after logging off. This helps to reduce the time it takes to log in.
Sending SYN
The SYN command has a TrID and two parameters - both are timestamps from a previous SYN (or 0 if the client doesn't store personal details). If the cached timestamp is the same as the timestamp on the server (i.e. no changes have been made), the server will not send the list to the client. If the timestamps do not match, the server will send the entire list.
It can take quite a while to download all the personal details - over ten seconds for a large list on a slow connection. It might be best to send SYN before setting your initial status so that other people will not have to wait for you to download your list before you can receive their messages. Also the server will disconnect you if you do not send a SYN within 8 minutes of setting your initial status to online.
Here are two examples of the SYN command:
>>> SYN 8 0 0\r\n >>> SYN 8 2005-04-23T18:57:44.8130000-07:00 2005-04-23T18:57:54.2070000-07:00\r\n
SYN Responses
The SYN response is one of the few MSN Messenger responses that have a different number of parameters in different situations. If the client's cache is up-to-date, the response will contain a TrID and one parameter (the version number). Otherwise, the response will contain a TrID and three parameters: updated version number, number of people on your contact list, and number of groups you've defined.
If the cache is up-to-date, the synchronisation has ended and there will be no further responses to the command. Otherwise the server will send these extra responses (in this order):
- GTC - what to do when someone adds you to their contact list
- BLP - default list for people who aren't explicitly allowed or blocked
- PRP - your phone numbers (sent once for every enabled/non-empty number)
- LSG - list of groups (sent once for every group you've defined)
- LST - list of people (sent once for every person in your contact list)
None of these responses will have TrIDs.
Example SYN Responses
In this example, the cached version is "125", which the server verifies as up-to-date.
>>> SYN 1 2005-04-23T18:57:44.8130000-07:00 2005-04-23T18:57:54.2070000-07:00\r\n <<< SYN 1 2005-04-23T18:57:44.8130000-07:00 2005-04-23T18:57:54.2070000-07:00\r\n
In this example, the client hasn't stored a cache, so the server sends a full list. The gaps in the response have been inserted to make reading easier. There are no blank lines in the protocol.
>>> SYN 1 0 0\r\n <<< SYN 1 2005-04-23T18:57:44.8130000-07:00 2005-04-23T18:57:54.2070000-07:00 1 1\r\n
<<< GTC A\r\n <<< BLP AL\r\n
<<< PRP PHH 01%20234\r\n <<< PRP PHM 56%20789\r\n
<<< LSG Other%20Contacts xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n
<<< LST N=principal5@passport.com F=principal5 C=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 13 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n <<< BPR HSB 1\r\n <<< PRP PHM 55%2088765432\r\n
Privacy Settings
There are two privacy settings in MSNP8: GTC and BLP.
GTC
The GTC value can be set to A or N. The client should change its behaviour based on this value. The value isn't processed by the server or advertised to other clients.
The client is expected to use this value in deciding how to behave when someone is added the RL who hasn't previously been put on the AL or BL. It's possible, for example, for someone to have been on your RL once before, then removed, then come back on, in which case they might already be on your block or allow list. The default setting is A. Because the server only stores this value, it's still the client's job to add them to one of the lists - the server will not do this automatically.
If the GTC value is set to A or the BLP value (below) is set to BL, the official client will alert the user when someone new is added to the reverse list and ask whether to allow or block them. Otherwise, it will automatically add them to the allow list.
BLP
Like GTC, the BLP value is stored on the server and is retrieved by the client every time it logs on. This setting also has only two values: AL and BL. Unlike GTC, the server actually reads this setting and does certain things differently depending on its value.
People who are on neither your AL nor BL will be treated as if they are on the list specified in BLP. If the value is AL, they will be allowed to invite you to a switchboard session and chat with you. If the value is BL, they will be informed that you are offline, and they will not be allowed to invite you to chat. The default value is AL.
Phone Numbers
The only time you can receive the phone numbers that you have set for yourself is during a SYN. Personal phone numbers are sent immediately after BLP. These phone numbers arrive in PRP responses. Each PRP has two parameters: a three letter phone type and the value of the phone number.
Here is a list of the five different phone number types in the order that they are sent:
- PHH - home phone number
- PHW - work phone number
- PHM - mobile phone number
- MOB - are other people authorised to contact me on my MSN Mobile device?
- MBE - do I have a mobile device enabled on MSN Mobile?
- HSB - has an (updated) MSN Space
Phone numbers are not sent if they are empty, MOB and MBE aren't sent unless they are enabled. Because of this, the only way to tell whether you've finished receiving PRPs is when you receive the first LSG response (there will always be at least one LSG response).
The value for the first three items can be anything up to 95 characters. This value can contain any characters allowed in a nickname and is URL Encoded.
The value of MOB and MBE can only be Y ("yes"). If MOB is set, the client has allowed other people to contact him on his mobile device through the PAG command. If MBE is set, that shows that the client has enabled a mobile device on MSN Mobile. Note that these values are completely independent from the PHM mobile device number.
There are 'reports' of a sixth phone number type to handle MSN Direct devices. This WWE value works exactly like MOB, but will be set to "2" if it's enabled. This value has never been observed in MSNP8.
Below is an example of the phone numbers of someone who has set her home phone number and has a mobile device but has chosen not to allow people to page her on MSN. Note that the home phone number is URL-encoded, and would show up like this when decoded: "555 555-0690".
<<< PRP PHH 555%20555-0690\r\n <<< PRP MBE Y\r\n
Group List (LSG)
After the PRPs have been sent, the NS will send the list of groups you've defined with the LSG command. The NS will send one LSG for each group. Each LSG will contain the URL-encoded name of the group, and the groups GUID.
Contact List (LST)
After sending the LSG responses, the NS will send information about the people on your contact list. The entire synchronisation process is complete when the last LST response has been received.
LST is another response with a variable number of parameters:
<<< LST N=email@addr.ess F=Display%20Name C=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 13 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n
- C is a GUID field (where x is a (lowercase) hexadecimal number), containing the ID of the contact. This field will only be specified when the contact is on the FL list (list bit 1).
- 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!
- 5th Parameter is the group IDs, seperated by comma (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).
If the person is in your FL, you will also receive some BPR responses immediately following the LST (if they have set their phone numbers). The format of a BPR response is similar to the PRP responses above, except that there's no such thing as a BPR MBE response. If a principal has MOB set to Y, that means that you can page them with the PAG command. If they have WWE set to 2, you can direct-page them with the PGD command.
It is also possible to receive BPRs outside of a SYN. This is discussed more on the setting details page.
List numbers
The fourth parameter is the principal's "list number", which represents the lists they're in (allow, block, forward, reverse). Each list has a numerical value - the forward list is 1, the allow list is 2, the block list is 4, the reverse list is 8 and the pending list 16. A principal's list number represents the sum of the lists the principal is in. For example, someone on your forward and allow lists but not your block or reverse lists would have a list number of 3.
Because list values are all powers of 2, you can tell which lists a principal is in with the bitwise AND function. ANDing the principal's list number with the value of a list will tell you whether they are in that list. For example, if a principal's list number is 3, "3 AND 1" returns "1" (meaning that they're on your forward list), "3 AND 2" returns "2" (meaning they're on your allow list), while "3 AND 4" and "3 AND 8" return "0" (meaning they aren't on your block or reverse lists).
Everyone on your reverse list should be on either your allow or block list, but this isn't always the case (for example, if they were added since you last logged off). You can check this by ANDing their list number with 14 (the sum of the add, block and allow lists). If the result is "8", they're on your reverse list but neither of the others. For example, if a buddy's list number is "11", "11 AND 14" returns "10" (meaning they have already been added to your allow list); whereas if their list number is "9", "9 AND 14" returns "8" (meaning they haven't been added to your add or block lists). See GTC above for how to handle these people.
There are some programs that erase everyone from your allow list so that you can appear offline to people while you talk, but when you log back on again with a normal client, they are often flooded with messages about new buddies.