Some other notes not contained in this spec.

REA TrID UserHandle FriendlyName - will change your friendly name



---

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

             ڰ               217 

             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

	     ڰ ʹ  Ҽ  921






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

