Protocols/MSNP/Notification/Presence

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.

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.

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 Transaction ID (the same TrID as your CHG or ADD command), and four parameters:

• 1. The principal's three letter status code.
• 2. The principal's account name.
• 3. The principal's URL-encoded display name.
• 4. The principal's Protocols/MSNP/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