Since March 10, 2003 - Version 2.1
hypothetic.org

MSN Messenger Protocol

Home Page

Forum

About
Contact us

Resources

Research

Documentation
 General
 Notification
 Switchboard
 Client
 Reference

Validate XHTML
Validate CSS
Notification - presence information
Printable Version

What is presence information?

"Presence" information, in its broadest sense, is information about the present state of the principal and/or the client. In MSNP8, this includes your status (busy, idle, hidden, etc.), your display name, and a number representing various information about the client (e.g. webcam support).

Here is an example presence notification command sent by the server:

NLN AWY example@passport.com example%20display%20name 268435492

This notifies you that the principal with passport "example@passport.com" is able to receive instant messages but is away from the computer, and would like you to refer to him as "example display name". It also notifies you that his client can understand MSNC1 and is capable of viewing "ink" messages.

Statuses

Statuses represent a principal's on-line state. There are two basic states a principal can be in: open ("on-line") and closed ("offline"). When your status is open, you can chat with other people, when it's closed, you can't. When you disconnect from the notification server, your status automatically becomes closed, but when you connect to the server, you have to manually open your status. Closing your status while remaining on-line is referred to as "hiding" or "appearing offline".

Everyone in your contact list, or more specifically, your allow list, can see your status. You can see the status of everyone that has you in their allow list, and you will automatically receive the status of everyone in your forward list

Open principals must set a "sub-state". This doesn't affect how the server treats them, but may be of interest to other principals:

  • NLN - Available
  • BSY - Busy
  • IDL - Idle
  • BRB - Be Right Back
  • AWY - Away
  • PHN - On the Phone
  • LUN - Out to Lunch

You can also set your own sub-state to HDN in order to hide.

Client Identification numbers

In order to properly understand how client identification works in MSN Messenger, you would need a basic understanding binary arithmetic. This site assumes no knowledge of binary, so this discussion of client ID numbers is quite shallow. Client identification are very similar to list numbers, only more complicated.

The client ID number is the sum of several values specifying capabilities advertised by the client the client protocol version it supports. Here are the values that we know to be used in client identification:

1
The client is running on a Windows Mobile device, such as a smartphone or Pocket PC. The official client changes the icon of a buddy with this bit set from a little man to a little man with a phone, and puts "(phone)" next to their name.
2
We don't know what this means, but the official client sometimes sets it when resetting its capabilities
4
The client is capable of viewing "ink" messages (see below).
8
The client is capable of viewing and creating "ink" messages (see below)
16
The client can participate in video conversations. The official client only sets this when you have a webcam connected and have chosen to share your webcam with others
32
We don't yet know what this means, but version 6.0 and above of the official client always sets this bit (it's hardcoded into the client), so it must be something that can't be turned off.
64
The client has a MSN Mobile device you can page them on. This is equivalent to the MOB value in the principal's BPR list, and nothing to do with Windows Mobile.
128
The client has an MSN Direct device you can direct-page them on. This is equivalent to the WWE value in the principal's BPR list.
268435456
The client supports client protocols up to and including MSNC1.
536870912
The client supports client protocols up to and including MSNC2.

To create a client ID number, sum the values in the above list which apply to your client. For example, if your client is a mobile phone supporting MSNC0, your client number is 1. Whereas if your client supports MSNC2, is able to receive ink messages and would like to advertise voice chat support, your client ID number would be 536870932 (536870912 + 16 + 4). Note: you can only specify one supported client protocol - if you use both "268435456" and "536870912" in your client identification, clients will behave unpredictably towards you.

Just like with list numbers, you can extract values from another principal's client ID number by bitwise ANDing the client ID with the value. This is the advised method for getting client capabilities, but it's better to get the client version number by dividing the client ID by 268435456 and rounding down to the nearest integer. This is called "modulo division", and most programming languages have a function or mathematical operator for it. For MSNC0 clients, modulo division will always return 0, for MSNC1 clients, it'll always return 1, and for MSNC2 clients, it'll always return 2.

Using modulo division to get the client version is safer than bitwise AND because it's suspected that the value for MSNC3 will be "805306368" (the sum of MSNC1 and MSNC2). This causes problems for bitwise AND, but is fine for modulo division (which will return 3).

What is "Ink"?

"Ink" is a technology from Microsoft that allows you to handwrite on a screen. It's available in tablet PCs, recent versions of Microsoft's Platform SDK, and in Microsoft's next version of Windows code-named "Longhorn".

A developer who worked on putting ink functionality into MSN Messenger has a page talking about his work.

Setting Your Presence

To manually set or change your status, send the CHG command with a TrID, the three letter status code for your status, and your client ID number. If successful, the server will echo your command back to you. Otherwise, it will most likely disconnect you immediately. Because status codes are case sensitive, sending nln will result in the server closing the connection. Here are some examples of using the CHG command:

>>> CHG 12 NLN 0\r\n
<<< CHG 12 NLN 0\r\n

>>> CHG 13 HDN 24\r\n
<<< CHG 13 HDN 24\r\n

>>> CHG 15 AWY 268435492\r\n
<<< CHG 14 AWY 268435492\r\n

If you attempt to change your status too rapidly, you may receive error 800 in response to some CHGs.

Initial Presence

After synchronising your details with the server, you should set your initial status. The official client always immediately sets the status to NLN, but any status is acceptable.

Until you set your initial presence, your status will remain closed and you won't receive presence notifications. If you want to keep your presence closed after logging on, you should set your initial status to HDN.

You used to be able to set your status to FLN, but this is no longer allowed - you will receive error 201 for invalid parameter if you try. If you request a switchboard session with the XFR command while you're hiding, you will receive error 913.

Changing your display name

Changing your display name is done using the REA command, as described in the setting details page.

Receiving Presences

Initial Presence notification

Initial presence notifications indicate that a principal was already online before you logged in (or before you added them to your forward list). After you send your initial status, you will receive an ILN command for every principal who is online, has you on their allow list, and you have on your forward list. You will also receive one after adding a principal to your forward list if they are online and had already allowed you to see their presence.

Clients shouldn't take special measures to notify the principal when receiving an initial presence notification. For example, the official client doesn't pop up a message when it receives an initial online notification.

The ILN command has a TrID (the same TrID as your CHG or ADD command), and four parameters:

  • The first parameter is the principal's three letter status code.
  • The second parameter is the principal's account name.
  • The third parameter is the principal's URL-encoded display name.
  • The fourth parameter is the principal's client ID number.

ILN commands are one of the least well implemented parts of the MSN Messenger protocol in that there's no way of knowing when the list of ILNs in response to a CHG is complete, or whether you'll receive an ILN in response to an ADD. If this is a problem for your client, you could ping the server when you receive the CHG reply, and assume the list is complete when you receive the ping reply. Alternatively, if you don't receive any ILNs for several seconds, you could assume no more will come. Even so, you should be prepared to handle ILNs as if they were asynchronous commands.

Here is an example of receiving a list of online principals:

>>> CHG 12 NLN 6\r\n

<<< CHG 12 NLN 6\r\n

>>> PNG\r\n

<<< ILN 12 AWY example@passport.com Mike 0\r\n

<<< ILN 12 NLN name_123@hotmail.com Name_123 536870948\r\n

<<< ILN 12 BSY myname@msn.com My%20Name 268435492\r\n

<<< QNG\r\n

Change of Presence Notification

Once you've sent your initial presence, changes of presence from principals on your forward list will cause the server to send you a notification.

When a principal closes their presence (either by disconnecting or hiding), the server sends an FLN command with no TrID and their passport as the only parameter:

<<< FLN example@passport.com\r\n

The server will send an NLN command after any other change to a principal's presence (note: the string NLN is used both as a command and an online state). Events that trigger an NLN command include a principal's presence being opened (e.g. after connecting to its NS), a change of online state, a change in client ID number, and a change in display name. Receiving an NLN command might mean that several of these have changed, or only one, or even none, so you should check before notifying the user.

The syntax for the NLN command is identical to that of the ILN command, except without a TrID:

<<< NLN NLN example@passport.com Mike 12\r\n

<<< NLN AWY example@passport.com Mike 0\r\n

<<< NLN AWY example@passport.com Mike%20Changed%20His%20Name 36\r\n

Search website:


Copyright©2002-2004 to Mike Mintz.