Joining a Switchboard Session
If you are invited to a switchboard session, you will receive a list of participants in the session after successfully authenticating. If you initiated the switchboard session, you will never receive this list.
The list of participants is sent with the
IRO command, probably standing for "initial roster". This is a list command and is therefore is very similar to that of the LSG command and the LST command. A separate
IRO will be sent for each participant. Note that you, the user that was just invited, are not included in this list.
IRO shall contain the same TrID as the
ANS you sent to authenticate with the switchboard.
- The first and second parameters of the
IRO command are the incrementing number and the total number respectively. The incrementing number starts at
1 for the first participant, and is equal to the total number for the last participant. The total number is the total number of participants in the session.
- The third parameter is the participant's account name.
- The fourth parameter is friendly name of the participant. However, if the participant changed his or her friendly since joining the switchboard session, this parameter will not be updated until the user leaves and rejoins the switchboard session.
After receiving the last
IRO (where the incrementing number is the same as the total number), you will receive
ANS with the same TrID as the
ANS that you sent initially, with the parameter
OK. After receiving this, you are officially part of the switchboard session and can send and receive messages.
Below is an example of authenticating with the switchboard and finding out that there are two other users (making a total of three):
<o> Client Connects to 18.104.22.168 1863 (Switchboard)
>>> ANS 1 email@example.com 849102291.520491113 11752013
<<< IRO 1 1 2 firstname.lastname@example.org Mike
<<< IRO 1 2 2 email@example.com My%20Name
<<< ANS 1 OK
<o> Continue SB Session . . .
A user cannot enter a switchboard session without being invited by a current participant. Any participant, not just the creator of the session, can invite other users. There is no known limit on the number of users in a switchboard session, but it is most likely greater than 30. There used to be a limit of five.
To invite a user into a switchboard session, send the
CAL command to the switchboard. It should have a TrID and the account name of the user 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 acknowledgment that you invited the user - the user 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 user invited.
There are several things that can go wrong with the
- If you try to invite a user 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 user 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 user is offline or account name specified is nonexistent (i.e.
myname@hotmail), you will receive error 217 but will not be disconnected.
- If the account name is invalid, such as
@@a, you will receive error 208 and remain connected.
- If the user that you are trying to invite is online 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.
Below are some examples of using the
>>> CAL 2 firstname.lastname@example.org
<<< CAL 2 RINGING 11752013
>>> CAL 3 email@example.com
<<< 217 3
>>> CAL 4 firstname.lastname@example.org
<<< 217 4
>>> CAL 5 @@a
<<< 208 5
>>> CAL 5 email@example.com
<<< 216 5
Only the person sending the
CAL will see the outgoing
CAL and the incoming
CAL or errors. When the specified user actually joins the session, every user will receive a
CAL was successful, the specified user 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 user in the session (excluding the user that just joined) will be sent the
JOI command has no TrID. The first parameter is the account name of the user that just entered the session. The second parameter is the URL-encoded friendly name of the user that just entered the session. Below is an example:
<<< JOI firstname.lastname@example.org Name_123
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 then close the connection. However, you may also close the connection with no command, and the switchboard will remove you from the switchboard session as long as you closed the connection properly. Below is an example of using the
<o> Switchboard Closes Connection
When a participant leaves a switchboard session, all other users in the session (if there are any left) will receive the
BYE command with no TrID and the account name of the user that left as the first parameter. Below is an example:
<<< BYE email@example.com
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 user for five minutes, the switchboard will send the
BYE command to both users showing that the other user 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 firstname.lastname@example.org 1
<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 for a random user in the session.
Whenever someone using the official closes a message window, it will disconnect from the switchboard, unless the switchboard was already closed from being idle. The official client will tell you when a user 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 user 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.