Protocols/MSNP/MSNP8/SBMiscellaneous

MSNP Protocol

Version 8

General

Overview • Glossary

Payload Commands • Names

Bitwise AND

Connecting

Authentication • Presence

Challenges • Getting Details

Setting Details • Messages

Miscellaneous

Example Session

Messaging

Authentication • Miscellaneous

Messages • Example Session

Overview

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)

Inviting Principals

A principal cannot enter a switchboard session without being invited by a current participant. Any participant, not just the creator of the session, can invite other principals. There is no known limit on the number of principals in a switchboard session, but it is most likely greater than 30. There used to be a limit of five.

You can invite the same principal into several switchboards - for example, to chat in one switchboard and transfer a file in another. However, the official client will attempt to handle all of the sessions in a single window, which can lead to confusing results. If you have more than one session to choose between, you should always send messages to the session you last received a message in.

CAL

To invite a principal into a switchboard session, send the CAL command to the switchboard. It should have a TrID and the account name of the principal you wish to invite as the first parameter.

If successful, the server will respond with another CAL with the same TrID, the string RINGING as the first parameter, and the session ID of this switchboard session as the second parameter. Note that this is only an acknowledgement that you invited the principal - the principal has not joined the session yet. That comes later with the JOI command. Also, the session ID is not important to the client, and it will be the same for every principal invited.

There are several things that can go wrong with the CAL command:

• If you try to invite a principal that is already in the session (including yourself), you will receive error 215. This error will also be sent if you try to invite a principal that has already been invited by your or another participant but has not yet joined.
• If the format was incorrect (e.g. too few or too many parameters), you will be immediately disconnected from the switchboard. However, as with every other case with the switchboard, the NS is not informed of anything and therefore the connection to the NS remains open.
• If the account name is invalid, such as @@a, you will receive error 208 and remain connected.
• If the principal is offline or account name specified is nonexistent (i.e. myname@hotmail), you will receive error 217 but will not be disconnected.
• If the principal that you are trying to invite is on-line and either blocking you, or has BLP set to AL and does not have you on his or her AL, you will receive error 216. This also does not disconnect you.
• If you repeatedly call someone who is blocking you, you may start to receive error 713.

Below are some examples of using the CAL command:

>>> CAL 2 name_123@hotmail.com\r\n
<<< CAL 2 RINGING 11752013\r\n

>>> CAL 3 nonexistent@passport.com\r\n
<<< 217 3\r\n

>>> CAL 4 offline@passport.com\r\n
<<< 217 4\r\n

>>> CAL 5 @@a\r\n
<<< 208 5\r\n

>>> CAL 5 blocking_you@passport.com\r\n
<<< 216 5\r\n
>>> CAL 5 blocking_you@passport.com\r\n
<<< 216 5\r\n
>>> CAL 5 blocking_you@passport.com\r\n
<<< 216 5\r\n
>>> CAL 5 blocking_you@passport.com\r\n
<<< 216 5\r\n
>>> CAL 5 blocking_you@passport.com\r\n
<<< 216 5\r\n
>>> CAL 5 blocking_you@passport.com\r\n
<<< 216 5\r\n
>>> CAL 5 blocking_you@passport.com\r\n
<<< 713 5\r\n

Only the person sending the CAL will see the outgoing CAL and the incoming CAL or errors. When the specified principal actually joins the session, every principal will receive a JOI.

JOI

If the CAL was successful, the specified principal will receive the RNG command from the NS. If they connect to the switchboard and authenticate, they will be part of the switchboard session. When that happens, every principal in the session (excluding the principal that just joined) will be sent the JOI command.

The JOI command has no TrID. The first parameter is the account name of the principal that just entered the session. The second parameter is the URL-encoded display name of the principal that just entered the session. Below is an example:

<<< JOI name_123@hotmail.com Name_123\r\n

Leaving a Switchboard Session

To leave a switchboard session, a client should send the OUT command with no TrID and no parameters. The switchboard will close the connection and remove you from the session. Disconnecting without sending an OUT command has the same effect. Below is an example of using the OUT command:

>>> OUT\r\n
<o> Switchboard Closes Connection

When a participant leaves a switchboard session, all other principals in the session (if there are any left) will receive the BYE command with no TrID and the account name of the principal that left as the first parameter. Below is an example:

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

Idle Sessions

If you are the only participant in a switchboard session (either because you haven't invited anyone yet or because everyone left), the switchboard will close the connection after five minutes of being alone. No command will be sent from the server before closing the connection.

If you are in a 2 person switchboard session, and no commands are sent from either principal for five minutes, the switchboard will send the BYE command to both principals showing that the other principal left and it will immediately close the connection. However, this BYE command has an additional parameter after the account name that says 1, showing that the switchboard was closed due to idleness. Below is an example:

<<< BYE example@passport.com 1\r\n
<o> Switchboard Closes Connection

The situation in a 3 or more person session is similar to that in a 2 person session, except that the idle duration is 15 minutes and you will only receive one BYE from one participant (randomly selected).

Official Client

Whenever someone using the official closes a message window that's attached to an open switchboard, it will disconnect from the switchboard. The official client will tell you when a principal leaves a switchboard with three or more participants, but it will not tell you in a switchboard with only 2 participants.

Relation to Notification Server

Because the integration between switchboard servers and the notification server is not very tight, a principal can log off of the NS and still be connected to one or more switchboards. When the official client logs out of MSN Messenger, it will send OUT to every active switchboard and then send OUT to the NS.