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