Mercurial > pidgin.yaz
diff doc/MSN-PROTOCOL @ 1560:72235e3fcff6
[gaim-migrate @ 1570]
Jason Boerner's --file patch. Also added/removed files from POTFILES.in and added the MSN protocol spec.
committer: Tailor Script <tailor@pidgin.im>
| author | Eric Warmenhoven <eric@warmenhoven.org> |
|---|---|
| date | Sat, 10 Mar 2001 22:42:47 +0000 |
| parents | |
| children | cb4fbcdae9eb |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/MSN-PROTOCOL Sat Mar 10 22:42:47 2001 +0000 @@ -0,0 +1,1176 @@ +Instant Messaging and Presence Protocol R. Movva +Internet Draft Microsoft +Category: Informational August, 1999 +Document: draft-movva-msn-messenger-protocol-00.txt +Document Expires: 2/00 W. Lai + Microsoft + August, 1999 + + + + MSN Messenger Service 1.0 Protocol + + + +Status of this Memo + + This document is an Internet-Draft and is NOT offered in accordance + with Section 10 of RFC2026, and the author does not provide the IETF + with any rights other than to publish as an Internet-Draft. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. Internet-Drafts are draft documents valid for a maximum of + six months and may be updated, replaced, or obsoleted by other + documents at any time. It is inappropriate to use Internet-Drafts as + reference material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This document and related documents are discussed on the impp + mailing list. To join the list, send mail to impp- + request@iastate.edu. To contribute to the discussion, send mail to + impp@iastate.edu. The archives are at http://lists.fsck.com/cgi- + bin/wilma/pip. The IMPP working group charter, including the current + list of group documents, can be found at + http://www.ietf.org/html.charters/impp-charter.html. + + + +1. Abstract + + Microsoft released a commercial Instant Messaging product in July of + 1999 called MSN Messenger Service. This document describes the + protocol used by that product for core instant messaging and + presence functionality. While this protocol does not meet many of + the requirements of the IMPP working group, it is provided as + background information on existing Instant Messaging + implementations. This protocol is provided 'as is' without warranty + of any kind. + + +Movva and Lai Category - Informational 1 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + +2. Conventions used in this document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in + this document are to be interpreted as described in RFC-2119. + + Protocol messages sent from client to server are preceded by "C:". + + Protocol messages sent from server to client are preceded by "S:". + + + +3. Introduction + + MSN Messenger Service enables a user to learn about the presence of + other people on the Internet, and to communicate with them in real- + time. This functionality is commonly referred to as "Instant + Messaging" (IM). + + This document describes the syntax and semantics of the MSN + Messenger Protocol, the communication protocol running between MSN + Messenger Service 1.0 clients and servers. Among the core services + that the MSN Messenger Servers provide to clients are: + + - Authenticated user logon. + - Adding and deleting members of the user's contact list. + - Changing the user's on-line state. + - Receipt of asynchronous, real-time, on-line state change + notifications from members of the user's contact list. + - Delivering lightweight, real-time messages to other users. + - Receipt of asynchronous, real-time messages from other users. + - Configuring the user's access permissions, to restrict the ability + of other users to view the user's on-line state or send messages + to the user. + + Additional background: + + 1. Some features extraneous to core instant messaging functionality + contained within the MSN Messenger Service 1.0 protocol are beyond + the scope of this document. Examples include client version + management and directory functionality. + + 2. The purpose of this document is to provide the members of the + IMPP working group with a reference implementation of a "monolithic" + IM system. That is, a system designed for massive scale, but not yet + capable of communication with servers other than those associated + with this specific service. Since any standard in this area will of + necessity be a "distributed" design that explicitly enables server- + to-server and service-to-service communication, this document will + serve primarily as a reference and example of one implementer's + choices when providing IM functionality at scale. + + +Movva and Lai Category - Informational 2 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + 3. This document reflects the protocol used in the 1.0 release of + MSN Messenger clients and servers, deployed on the Internet in July + of 1999. However, the service is in production and rapidly growing, + which almost certainly will necessitate changes to the protocol as + Microsoft gains operational experience with the service and expands + its feature set. This Internet Draft may not be updated with such + changes, and the changes may be made with little or no notice. + + + +4. MSN Messenger Server Component Overview + + MSN Messenger Service clients make connections to several different + kinds of servers. They are separate components to facilitate running + at scale - each component can be duplicated an arbitrary number of + times, independently of each other, to enable large numbers of + users. + +4.1 Dispatch Server (DS) + + The Dispatch Server is the initial point of connection between + client and server. Its primary functions are protocol version + negotiation, determination of which Notification Server (NS) is + associated with the client making a connection (via an algorithm of + the server's choosing), and referring the client to the proper NS. + +4.2 Notification Server (NS) + + The Notification Server is the primary server component. The client + and the Notification Server authenticate, synchronize user + properties, and exchange asynchronous event notifications. The + client's connection to the Notification Server occurs after the + referral from the Dispatch Server is completed, and persists without + interruption during the user's MSN Messenger Service session. + + Some of the events transmitted between a client and a Notification + Server are: State changes (e.g. client is on-line, client is + offline, client is idle), Switchboard Server invitation requests + (see below), and application-specific notifications that are beyond + the scope of this document. (E.g. new e-mail has arrived) + +4.3 Switchboard Server (SS) + + The Switchboard Server is the component through which clients can + establish lightweight communication sessions without requiring a + direct network connection between clients. The common usage of the + Switchboard Server is to provide instant messaging sessions. + When a client wishes to communicate with another client, it sends a + message to its Notification Server, which then refers the client to + a Switchboard Server. Once the SS connection is established, the + "destination" client receives a notification from its NS to connect + to the same SS. + + +Movva and Lai Category - Informational 3 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + +5. Protocol Conventions + +5.1 Connection Type + + The MSN Messenger Protocol currently works over TCP/IP. The MSN + Messenger server components support connections over port numbers + 1863, which is the registered port number assigned by the IANA + (http://www.isi.edu/in-notes/iana/assignments/port-numbers). + +5.2 Command Syntax + + MSN Messenger Protocol command syntax is ASCII and single line- + based. Commands begin with a case-sensitive, three-letter command + type, followed by zero or more parameters, and terminated by CRLF. + Parameters are separated by one or more whitespace characters and + cannot contain whitespace characters. Parameters that contain spaces + or extended (non 7-bit ASCII) characters should be encoded using + URL-style encoding (e.g. "%20" for space). Some commands accept un- + encoded binary data. In these cases, the length of the data is + transmitted as part of the command, and the data is transmitted + immediately following a CRLF of the command. + +5.3 Asynchronous Requests + + Commands issued from the client to the server that result in a reply + are known as requests. Requests are entirely asynchronous. The + client can submit several requests in sequence without waiting for + the server response after submitting each request. The server is + required to deliver a response or an error for each request + received, but it is not required to deliver the responses in the + same order as the requests were received. The client can determine + the request associated with a particular response by examining the + Transaction ID parameter (described below). + +5.4 User Handles + + MSN Messenger Protocol uses User Handles for identifying users. A + user handle (also known as "account name" and "logon name") is a + text representation of the user's identity that is both unique and + persistent. The user handle is syntactically equivalent to an e-mail + address, and as such is subject to the same restrictions for + character set, as described in RFC-822. Most notable among these + restrictions are the limitation to Latin alphanumeric characters and + a few symbols. The maximum acceptable length of the user handle is + 129 bytes. + + Implementation note: In the initial release of the client and + server, user handles are Hotmail account names. All user handles + must contain the "@hotmail.com" domain name, and user handles that + do not contain a domain name are not valid. + +5.5 Custom User Names + + +Movva and Lai Category - Informational 4 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + A custom user name (also known as "custom name" and "friendly name") + is a user's representation of the "friendly" textual name associated + with a user handle. (E.g. "Auntie Em" instead of em123@hotmail.com). + Custom user names are neither unique nor persistent, and can contain + any valid Unicode characters. Custom user names are represented in + UTF-8 as described in RFC-2044 and URL-encoded as described in RFC- + 1738 when transmitted between the client and server. The maximum + acceptable length of the encoded custom user name is 387 in the + current implementation. + +5.6 Transaction Identifiers + + The Transaction Identifier (a.k.a. Transaction ID) is a numeric + string representing a number between 0 and (2^32 - 1). It is a value + that a client includes with any command that it issues to the + server. In the current version of the protocol, the transaction + identifier is used to associate server responses with client-issued + commands. The server treats the transaction ID as an opaque number + and does not assume any relationship between successive Transaction + + IDs or any particular starting Transaction ID. It is the client's + responsibility to guarantee the uniqueness of the Transaction IDs + for the purpose of disambiguating the commands and/or responses. (A + future version of the protocol could enable the client to track the + status or cancel a particular transaction using the transaction ID.) + + When the server sends the response to a command to the client, it + must include in the response the transaction ID that the client sent + to the server when the client originally issued the command. In + cases where a server sends a command to a client that requires a + transaction ID but is not in response to a specific client command, + it will use 0 as the transaction ID. In cases where a server sends + multiple responses to a single client request, the server will use + the same transaction ID in each response. + +5.7 User List Types + + Some of the protocol commands are used to the manipulate lists of + users. The following types of user lists are supported by the + protocol: + + Forward List (FL) - The list of users for whom a given user wants to + receive state change notifications. The Forward List is what is most + commonly referred to as the user's "contact list." + + Reverse List (RL) - The list of users who have registered an + interest in seeing this user's state change notifications. + + Allow List (AL) - The list of users who the user has explicitly + allowed to see state change notifications and establish client-to- + client sessions via a Switchboard Server. + + + +Movva and Lai Category - Informational 5 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + Block List (BL) - The list of users who the user has explicitly + prevented from seeing state change notifications and establishing + client-to-client sessions via a Switchboard Server. + + + +6. Command Summary Table + + Command From To Description + ================================================================== + ACK Switchboard Client Sends a positive message + delivery acknowledgement. + ------------------------------------------------------------------- + ADD Client Notification Adds to the user's FL, AL, + Notification Client and BL. Notifies the client + of asynchronous additions + to a user's list. + ------------------------------------------------------------------- + ANS Client Switchboard Accepts a request for a + switchboard server session. + ------------------------------------------------------------------- + BLP Client Notification Changes the user's message + Notification Client privacy setting, which + determines how to treat + messages from users not + already in the BL or AL. + ------------------------------------------------------------------- + BYE Switchboard Client Notifies a client that a + user is no longer in the + session. + ------------------------------------------------------------------- + CAL Client Switchboard Initiates a switchboard + server session. + ------------------------------------------------------------------- + CHG Client Notification Sends a client state change + Notification Client to the server. + Echoes the success of + client's state change + request. + ------------------------------------------------------------------- + FLN Notification Client Notifies the client when + users in the FL go off- + line. + ------------------------------------------------------------------- + GTC Client Notification Changes the user's prompt + Notification Client setting, which determines + how the client reacts to + certain RL changes. + ------------------------------------------------------------------- + INF Client Dispatch, Requests set of support + Notification authentication protocol + Dispatch, Client from the server. + Notification Provides the set of + +Movva and Lai Category - Informational 6 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + supported authentication + protocols to the client. + ------------------------------------------------------------------- + ILN Notification Client Notifies the client of the + initial online state of a + user in the FL, while + either logging on or adding + a user to the FL. + ------------------------------------------------------------------- + IRO Switchboard Client Provides the initial roster + information for new users + joining the session. + ------------------------------------------------------------------- + JOI Switchboard Client Notifies a client that a + user is now in the session. + ------------------------------------------------------------------- + LST Client Notification Retrieves the server's + Notification Client version of the user's FL, + RL, AL, or BL. + ------------------------------------------------------------------- + MSG Client Switchboard Sends a message to the + members of the current + session. + ------------------------------------------------------------------- + MSG Notification, Client Delivers a message from + Switchboard another client or from a + server-side component. + ------------------------------------------------------------------- + NAK Switchboard Client Sends a negative message + delivery acknowledgement. + ------------------------------------------------------------------- + NLN Notification Client Notifies the client when + users in the FL go on-line + or when their on-line state + changes. + ------------------------------------------------------------------- + OUT All All Ends a client-server + Session. + ------------------------------------------------------------------- + REM Client Notification Removes from the user's FL, + Notification Client AL, and BL. + Notifies the client of + asynchronous removals from + a user's list. + ------------------------------------------------------------------- + RNG Notification Client Notifies the client of a + request by another client + to establish a session via + a switchboard server. + ------------------------------------------------------------------- + SYN Client Notification Initiates client-server + Notification Client property synchronization. + ------------------------------------------------------------------- + +Movva and Lai Category - Informational 7 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + USR All All Authenticates client with + server, possibly in + multiple passes. + ------------------------------------------------------------------ + VER Client Dispatch Negotiates common protocol + Dispatch Client dialect between client and + Server. + ------------------------------------------------------------------ + XFR Client Notification Requests a Switchboard + Notification Client server for use in + establishing a session. + ------------------------------------------------------------------- + XFR Dispatch Client Notification of login-NS to + Notification Client the client or notification + to move to a different NS. +======================================================================= + + + +7. Presence and State Protocol Details + + This is a detailed list of protocol commands associated with + presence functionality. They are defined in the order used by + clients. Commands associated with instant messages are discussed in + section 8 below. + +7.1 Protocol Versioning + + After the client connects to a dispatch server by opening a TCP + socket to port 1863, the client and server agree on a particular + protocol version before they proceed. The Client-Server protocol + version handshake involves the following command exchange: + + C: VER TrID dialect-name{ dialect-name...} + S: VER TrID dialect-name + + The client can provide multiple dialect names in preferred order. + The dialect-name parameter returned by the server is the version + server is designating for this connection + + The current protocol dialect-name supported by Messenger servers is + "MSNP2". The dialect names are not case-sensitive. + + The string "0" is a reserved dialect name and is used to indicate a + failure response. E.g.: + + S: VER TrID 0{ dialect-name ... } + +7.2 Server Policy Information + + The client next queries the server for variable "policy" + information. In this version of the protocol, the only policy + + +Movva and Lai Category - Informational 8 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + information returned by the server is the authentication package in + use. + + C: INF TrID + S: INF TrID SP{,SP...} + + SP identifies a security package - the name of the SASL mechanism to + use for authentication. "MD5" is used by the Notification Server, + "CKI" by the Switchboard Server. + +7.3 Authentication + + The client needs to authenticate itself after protocol version + handshake and identifying the security packages supported on the + server. The following are the client server interactions involved. + + C: USR TrID SP I{ AuthInitiateInfo} + S: USR TrID SP S{ AuthChallengeInfo} + C: USR TrID SP S{ AuthResponseInfo } + S: USR TrID OK UserHandle FriendlyName + + The SP parameter is the name of the security package("MD5"). The + next parameter is a sequence value, which must be I to (I)nitiate + the authentication process and S for all (S)ubsequent messages. If + authentication fails on the server, the client can start the + authentication process again. + + For the MD5 security package: + - The AuthInitiateInfo parameter provided by the client must be the + User handle. + - The AuthChallengeInfo parameter returned by the server contains a + challenge string. + - The AuthResponseInfo contains the binary response as a hexadecimal + string, which the MD5 hash of the challenge and the User password + strings concatenated together. + + The final response from the server contains, in addition to the user + handle, the current "Friendly Name" associated with the user handle. + This is a "Custom User Name" as described above. + +7.4 Referral + + There are three cases in which clients are referred from one server + to another: + + 1. The initial "Dispatch Server" refers the client to the + Notification Server to which it is assigned. + 2. Asynchronous referral by the Notification Server to reassign the + client to a different Notification Server if that server is + overloaded or undergoing maintenance. + 3. During Switchboard Session establishment, the assigned + Notification Server refers the client to a particular + switchboard server for use. This is discussed below. + +Movva and Lai Category - Informational 9 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + + In the current implementation the Dispatch Server uses the user + handle provided in the initial USR command above to assign the user + in question to a Notification Server. Alternate implementations + might not require referral at this stage. + + If received, referral is of the form: + + S: XFR TrID ReferralType Address[:PortNo] + + ReferralType is either "NS" or "SB" and defines the type of referral + to a Notification Server or Switchboard Server. + Address is a valid DNS name or IP address to a referred server, with + optional port# suffixed as ":PortNo". + + If this command is received from the server, the client should + attempt to log in to the server provided. + + In the case of "NS" referrals during logon, the Server automatically + closes the client connection after sending this XFR response so that + the client can connect to the new IP Address. + + If sent asynchronously, the client is responsible for closing the + connection. + + After a "NS" referral, the client will not receive any more messages + from the "old" NS, and also must not send any commands to the "old" + NS after receiving an XFR. + +7.5 Client User Property Synchronization + + Several of the user properties used by the Messenger application are + stored on the server. This is done for two reasons: + + 1) So that users can "roam", i.e. log in from different locations + and still have the appropriate data, such as their contact lists and + privacy settings. + 2) If changes occur to a user's Reverse List while that user was + offline (the user was added to another user's list), the client can + be updated with this information. + + For performance reasons it is useful to cache these properties on + the client, so that bandwidth usage is minimized in the typical case + where the user is not roaming and there were no Reverse List + changes. + + These requirements are met by the SYN command - synchronization. + + Once a client logs in successfully, it uses the SYN command to + ensure it has the latest version of the server-stored properties. + These properties include: Forward List, Reverse List, Block List, + Allow List, GTC setting (privacy setting when someone adds this user + to their Forward List), and BLP setting (the user's privacy mode). + +Movva and Lai Category - Informational 10 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + + The SYN command is: + + C: SYN TrID Ser# + S: SYN TrID Ser# + + The Ser# parameter sent by the client is the version of the + properties currently cached on the client. The server responds with + the current server version of the properties. If the server has a + newer version, the server will immediately follow the SYN reply by + updating the client with the latest version of the user properties. + These updates are done as described below, and are done without the + client explicitly initiating a LST, GTC or BLP command. Note that + the server will update all server-stored properties to the client, + regardless of how many entries have been changed. + + The following "List Retrieval and Property Management" section + describes the format of the user properties sent by the server. + After the SYN reply from the server, the user property updates will + be sent from the server in this sequence: GTC, BLP, LST FL, LST AL, + LST BL, LST RL. + + All the user property updates will share the same TrID as the SYN + command and reply. + +7.6 List Retrieval And Property Management + + Synchronizing can result in a batch of user properties and lists + getting sent by the server to the client. However, the client + application can also initiate a request to retrieve the server- + stored lists and properties. The following are the privacy property + and list retrieval commands. The response formats are the same + whether it is a client-initiated request, or whether it is a + response to the SYN process as described above. + + + List Command + + By issuing the LST command, the client can explicitly request that a + list be sent. The server will respond with a series of LST + responses, one LST response for each item in the requested list. + + C: LST TrID LIST + S: LST TrID LIST Ser# Item# TtlItems UserHandle CustomUserName + + - LIST is FL/RL/AL/BL for Forward List, Reverse List, Allow List, + and Block List, respectively. + - The Item# parameter contains the index of the item described in + this command message. (E.g. item 1 of N, 2 of N, etc.) + - The TtlItems parameter contains the total number of items in this + list. + - UserHandle is the user handle for this list item. + - CustomUserName is the friendly name for this list item. + + +Movva and Lai Category - Informational 11 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + If the list is empty, the response will be: + + S: LST TrID LIST Ser# 0 0 + + Reverse List Prompting + + The client can change its persistent setting for when to prompt the + user in reaction to an Reverse List change. This is accomplished via + the GTC command: + + C: GTC TrID [A | N] + S: GTC TrID Ser# [A | N] + + The value of the A/N parameter determines how the client should + behave when it discovers that a user is in its RL, but is not in its + AL or BL. (Note that this occurs when a user has been added to + another user's list, but has not been explicitly allowed or + blocked): + + A - Prompt the user as to whether the new user in the RL should be + added to the AL or the BL + N - Automatically add the new user in the RL to the AL + + The A/N parameter is not interpreted by the server, merely stored. + + The server will respond with the current setting if the change was + successful. Otherwise, it will return an error with the matching + TrID. If the client tries to change the setting to the same value as + the current setting, the server will respond with an error message. + + The default setting is A when a new user connects to the server for + the first time. + + Privacy Mode + + The client can change how the server handles instant messages from + users via the BLP command: + + C: BLP TrID [AL | BL] + S: BLP TrID Ser# [AL | BL] + + The AL/BL parameter determines how the server should treat messages + (MSG and RNG) from users. If the current setting is AL, messages + from users who are not in BL will be delivered. If the current + setting is BL, only messages from people who are in the AL will be + delivered. + + The server will respond with the current setting if the change was + successful. Otherwise, it will return an error with the matching + TrID. If the client tries to change the setting to the same value as + the current setting, the server will respond with an error message. + + + +Movva and Lai Category - Informational 12 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + The default setting is AL when a new user connects to the server for + the first time. + + +7.7 Client States + + After the client is authenticated and synchronized, the client + establishes its initial state with the server with the CHG command. + The syntax of the command is: + + C: CHG TrID State + S: CHG TrID State + + When the state is changed, the server will echo the settings back to + client. The state shall not be considered changed until the response + is received from the server. + + Note that the server can send a state change message to the client + at any time. If the server changes the state without a request from + the client, the TrID parameter will be 0. + + States are denoted by a string of three characters. The predefined + states that the server recognizes are: + + NLN - Make the client Online (after logging in) and send and receive + notifications about buddies. + FLN - Make the client Offline. If the client is already online, + offline notifications will be sent to users on the RL. No message + activity is allowed. In this state, the client can only synchronize + the lists as described above. + HDN - Make the client Hidden/Invisible. If the client is already + online, offline notifications will be sent to users on the RL. The + client will appear as Offline to others but can receive + online/offline notifications from other users, and can also + synchronize the lists. Clients cannot receive any instant messages + in this state. + + All other States are treated as sub-states of NLN (online). The + other States currently supported are: + BSY - Busy. + IDL - Idle. + BRB - Be Right Back. + AWY - Away From Computer. + PHN - On The Phone. + LUN - Out To Lunch. + +7.8 List Modifications + + The protocol supports generic commands to add and remove users from + various lists. This is used by clients to enable "Adding" contacts + to the list of folks being watched, or for the "Block" and "Allow" + features that define how users chooses to interact with one another. + + +Movva and Lai Category - Informational 13 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + However, these generic commands have different semantics based on + the list being modified. For example, only the server can add or + remove entries from the Reverse List - since it is an indirect + consequence of the user having been added to another user's Forward + List. + + The add and remove commands: + + C: ADD TrID LIST UserHandle CustomUserName + S: ADD TrID LIST ser# UserHandle CustomUserName + + C: REM TrID LIST UserHandle + S: REM TrID LIST ser# UserHandle + + Valid values for LIST in Client initiated adds and removes are + FL/AL/BL. + + All client initiated adds and removes will be echoed by the server + with a new serial number that should be persisted by the client + along with the list modification. If not successful, an error will + result. + + The protocol also supports the concept of an ADD or REM that the + client did not initiate. Server generated ADDs and REMs can have + LIST values of FL/AL/BL/RL. This is common with RL changes, which + are never initiated by the client, but is an indirect consequence of + this user having been added to someone's Forward List. If the RL + change happens while the user is online, it will trigger an + asynchronous ADD or REM command from the server. + + Asynchronous ADDs and REMs to the FL, AL, and BL can happen when the + server allows an authenticated user to make list changes from + another environment, such as a web site. In all of these cases, the + server will send the ADD or REM command with the TrID parameter + equal to 0. + +7.9 Notification Messages + + The client receives asynchronous notifications whenever a contact on + the user's Forward List changes its state. The notifications are of + the form: + + S: NLN Substate UserHandle FriendlyName + S: ILN TrID Substate UserHandle FriendlyName + S: FLN UserHandle + + NLN indicates that a user has come online. + - Substate can be any three-letter code (see "Client States" above). + - UserHandle and FriendlyName are the handle and names associated + with the user coming online. + + ILN is similar to the NLN message, and is received from the server + in response to an CHG or ADD command from the client: + +Movva and Lai Category - Informational 14 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + + 1. Immediately after the client logon and sends its first CHG + command to the NS. In this case several ILNs may be received - + one for each Forward List contact that is currently online. + 2. After the client sends an "ADD TrID FL UserHandle + CustomUserName" to the NS. (e.g. ILN for the new contact if that + contact is currently online) + + In both cases, TrID in the ILN is the same as the one sent by the + client in the CHG or ADD command. + + FLN means that the specified user is now offline. + +7.10 Connection Close + + The client issues the following command to logoff from the NS: + + C: OUT + S: OUT {StatusCode} + + The server will reply with an OUT to the client before it initiates + a disconnect, with an optional StatusCode. + + The StatusCode can be "OTH", which indicates that a client with the + same user handle and password has logged on to the server from + another location, or "SSD" meaning the server is being shut down for + maintenance. + + The server will drop the connection after sending the OUT. + +7.11 Error Information + + Error messages from the server are of the format: + + S: eee {TrID} {(error-info) {param...}} + + eee is a 3 digit decimal number indicating the error code. Error- + info contains the description of the error in a text string + localized to the server's locale. The optional parameters provide + indication of the client command causing the error. TrID is the + Transaction ID of the client command that caused this error. Any + server generated errors will not have Transaction IDs. + + + ERR_SYNTAX_ERROR 200 + ERR_INVALID_PARAMETER 201 + ERR_INVALID_USER 205 + ERR_FQDN_MISSING 206 + ERR_ALREADY_LOGIN 207 + ERR_INVALID_USERNAME 208 + ERR_INVALID_FRIENDLY_NAME 209 + ERR_LIST_FULL 210 + ERR_ALREADY_THERE 215 + +Movva and Lai Category - Informational 15 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + ERR_NOT_ON_LIST 216 + ERR_ALREADY_IN_THE_MODE 218 + ERR_ALREADY_IN_OPPOSITE_LIST 219 + ERR_SWITCHBOARD_FAILED 280 + ERR_NOTIFY_XFR_FAILED 281 + + ERR_REQUIRED_FIELDS_MISSING 300 + ERR_NOT_LOGGED_IN 302 + ERR_INTERNAL_SERVER 500 + ERR_DB_SERVER 501 + ERR_FILE_OPERATION 510 + ERR_MEMORY_ALLOC 520 + ERR_SERVER_BUSY 600 + ERR_SERVER_UNAVAILABLE 601 + ERR_PEER_NS_DOWN 602 + ERR_DB_CONNECT 603 + ERR_SERVER_GOING_DOWN 604 + ERR_CREATE_CONNECTION 707 + ERR_BLOCKING_WRITE 711 + ERR_SESSION_OVERLOAD 712 + ERR_USER_TOO_ACTIVE 713 + ERR_TOO_MANY_SESSIONS 714 + ERR_NOT_EXPECTED 715 + ERR_BAD_FRIEND_FILE 717 + ERR_AUTHENTICATION_FAILED 911 + ERR_NOT_ALLOWED_WHEN_OFFLINE 913 + ERR_NOT_ACCEPTING_NEW_USERS 920 + + + +8. Session based Instant Messaging Protocol Details + + MSN Messenger Service utilizes a lightweight, session-based + messaging scheme. In order for two clients to exchange instant + messages, they must first establish a common session via a + Switchboard Server. They can invite additional clients to join the + established session. + +8.1 Referral to Switchboard + + This process begins with a "calling" client requesting a referral + from its Notification Server to a Switchboard Server: + + C: XFR TrID SB + S: XFR TrID SB Address SP AuthChallengeInfo + + - SB is the type of referral being requested or granted. + - Address is the DNS name or IP address of a Switchboard Server that + has been assigned, and that the client should connect to. + - SP is the Security Package being used. In this version of the + protocol it is "CKI" only. + - AuthChallengeInfo is a cookie that the client needs to present to + the Switchboard server for authentication. + + +Movva and Lai Category - Informational 16 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + +8.2 Switchboard Connections and Authentication + + After the XFR reply is received, the client makes a TCP/IP + connection to the Switchboard server using port 1863. Note that a + lack of version negotiation in the switchboard connection is a + limitation of the current implementation. + + The client first needs to authenticates with the Switchboard Server: + + C: USR TrID UserHandle AuthResponseInfo + S: USR TrID OK UserHandle FriendlyName + + - AuthResponseInfo is the cookie for CKI security package returned + by the Notification Server in the XFR. + - UserHandle and FriendlyName are the Switchboard's echoes of the + user handle and friendly name of the user. + +8.3 Inviting Users to a Switchboard Session + + Any user in a Switchboard session can invite other users to join the + session. The CAL command is sent to the Switchboard server for this + purpose: + + C: CAL TrID UserHandle + S: CAL TrID Status SessionID + + The Messenger servers verify that the calling user has permissions + to contact the called user, with consideration given to the called + user's privacy settings and its online state. If instant messaging + with this user is not allowed, the server responds to the calling + user with an error. If it is allowed, the Switchboard server causes + a RNG command to be sent to the called client (see below), and + returns a CAL echo to the calling client. The CAL echo has these + parameters: + + - Status is a predefined status code - in this implementation it + must be "RINGING". + - SessionID is the ASCII representation of a decimal number that + uniquely identifies this session on the Switchboard Server. + +8.4 Getting Invited to a Switchboard Session + + The other side of the session establishment is the behavior of the + called client. The called client receives a RNG from its + Notification Server and is expected to connect to the Switchboard + Server and respond with an ANS. + + The client receives a RNG from the Notification Server as follows: + + S: RNG SessionID SwitchboardServerAddress SP AuthChallengeInfo + CallingUserHandle CallingUserFriendlyName + + - SessionID is a numeric ASCII session ID. + +Movva and Lai Category - Informational 17 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + - SwitchboardServerAddress is a DNS name or IP Address + - SP is the security package in use. In this implementation only + "CKI" is supported. + - AuthChallengeInfo is the cookie to be passed back to the + switchboard to gain entrance to the session. + - CallingUserHandle is the user handle of the caller. + - CallingUserFriendlyName is the custom user name of the caller. + + To join the session, the called client connects to the Switchboard + Server and carries out the following exchange to join the session: + + C: ANS TrID LocalUserHandle AuthResponseInfo SessionID + S: IRO TrID Participant# TotalParticipants UserHandle + FriendlyName + S: ANS TrID OK + + The IRO commands relay to the newly joined client roster information + about the current session. Each IRO command message from the + Switchboard contains one participant in the session. + - Participant# contains the index of the participant described in + this IRO command (e.g. 1 of N, 2 of N). + - TotalParticipants contains the total number of participants + currently in the session. + + The entire session roster will be sent to the new client joining the + session before any JOI or BYE commands described below. + + If no one is in the session when the user joins (an unexpected error + condition), the server skips directly to "ANS TrID OK" command. All + the responses from the server related to the issued ANS command will + contain the same TrID as the original client ANS request. + +8.5 Session Participant Changes + + When a new user joins a Switchboard session, the server sends the + following command to all participating clients, including the client + joining the session: + + S: JOI CalleeUserHandle CalleeUserFriendlyName + + - CalleeUserHandle is the user handle of the new participant. + - CalleeUserFriendlyName is the Custom User Name of the new + participant. + + If a client's connection with the Switchboard Server is dropped for + any reason, the server sends the following command to the remaining + clients in the session: + + S: BYE CalleeUserHandle + + - CalleeUserHandle is the user handle of the participant that left + the session. + + +Movva and Lai Category - Informational 18 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + Privacy Note: + If the client moved a contact to the BL while Switchboard sessions + are active, it is the client's responsibility to leave any session + that should now be blocked. The servers only enforce privacy + permissions when inviting users to a session. Further, the servers + only enforce privacy permission with respect to the calling user, + and not the other participants in a Switchboard session. Therefore, + in a multipoint session, it is possible for a user to participate in + a session with someone whom he has blocked, if a third party is + performing the invitation. + +8.6 Leaving a Switchboard Session + + When a client wishes to disconnect from the session, it sends the + following command and waits for the Switchboard to close the + connection: + + C: OUT + +8.7 Instant Messages + + Sending an Instant Message + + Once a client-to-client session has been established via the + Switchboard Server, sending an Instant Message to the participants + of the session is done as follows: + + C: MSG TrID [U | N | A] Length\r\nMessage + S: NAK TrID + S: ACK TrID + + U, N, and A correspond to the three delivery acknowledgement modes: + Unacknowledged, Negative-Acknowledgement-Only, and Acknowledgement. + Depending on the value of this parameter, either nothing, NAK, or + ACK will be sent back by the Switchboard Server to the client. + + For Unacknowledged mode, the Switchboard Server does not respond to + the sending client with the success or failure of message delivery. + + For Negative-Acknowledgement-Only mode, the Switchboard Server + responds to the send client only if the message could not be + delivered to the recipient client. + + Acknowledgement mode is not currently implemented. + + Length is the length of the Message parameter in bytes, whereas + Message is the actual message as described below. + +8.8 Receiving an Instant Message + + A client can receive a system-generated message from the + Notification Server, or it can receive an instant message from + + +Movva and Lai Category - Informational 19 + + MSN Messenger Service 1.0 Protocol Aug - 99 + + + another client via a Switchboard Server. The message is received in + the following format: + + S: MSG UserHandle FriendlyName Length\r\nMessage + + The UserHandle and FriendlyName are those of the sending user. + Length is the length of the message in bytes. + + Message is a MIME encoded stream, using a standard MIME header as + defined by RFC-1521 and RFC-822. + + Message is constructed as: + + MIME-Header\r\nMIME-Header\r\n\r\nMessageData + + MIME-Header is constructed as: + + string": "string + (E.g. "Content-Type: text/plain") + + The Content-Type MIME headers that the current client will use and + recognize are: + + "text/plain;charset=UTF-8" + "text/plain" + + If "charset=UTF-8" appears at the end of the Content-Type, the + Message Data is UTF-8 encoded. + + Note: The Switchboard Server does not interpret the contents of the + Message. + + + +9. Author's Addresses + + Ramu Movva + Microsoft Corporation + One Microsoft Way + Redmond WA 98052 + ramum@microsoft.com + + William Lai + Microsoft Corporation + One Microsoft Way + Redmond, WA 98052 + wlai@microsoft.com + + + +Movva and Lai Category - Informational 20