Mercurial > pidgin.yaz
annotate doc/MSN-PROTOCOL @ 2155:3619cbbd6bdf
[gaim-migrate @ 2165]
this warning was getting annoying.
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Wed, 22 Aug 2001 22:25:17 +0000 |
parents | cb4fbcdae9eb |
children |
rev | line source |
---|---|
2038
cb4fbcdae9eb
[gaim-migrate @ 2048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1560
diff
changeset
|
1 Some other notes not contained in this spec. |
cb4fbcdae9eb
[gaim-migrate @ 2048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1560
diff
changeset
|
2 REA TrID UserHandle FriendlyName - will change your friendly name |
cb4fbcdae9eb
[gaim-migrate @ 2048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1560
diff
changeset
|
3 |
cb4fbcdae9eb
[gaim-migrate @ 2048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1560
diff
changeset
|
4 --- |
1560 | 5 Instant Messaging and Presence Protocol R. Movva |
6 Internet Draft Microsoft | |
7 Category: Informational August, 1999 | |
8 Document: draft-movva-msn-messenger-protocol-00.txt | |
9 Document Expires: 2/00 W. Lai | |
10 Microsoft | |
11 August, 1999 | |
12 | |
13 | |
14 | |
15 MSN Messenger Service 1.0 Protocol | |
16 | |
17 | |
18 | |
19 Status of this Memo | |
20 | |
21 This document is an Internet-Draft and is NOT offered in accordance | |
22 with Section 10 of RFC2026, and the author does not provide the IETF | |
23 with any rights other than to publish as an Internet-Draft. | |
24 | |
25 Internet-Drafts are working documents of the Internet Engineering | |
26 Task Force (IETF), its areas, and its working groups. Note that | |
27 other groups may also distribute working documents as Internet- | |
28 Drafts. Internet-Drafts are draft documents valid for a maximum of | |
29 six months and may be updated, replaced, or obsoleted by other | |
30 documents at any time. It is inappropriate to use Internet-Drafts as | |
31 reference material or to cite them other than as "work in progress." | |
32 | |
33 The list of current Internet-Drafts can be accessed at | |
34 http://www.ietf.org/ietf/1id-abstracts.txt | |
35 | |
36 The list of Internet-Draft Shadow Directories can be accessed at | |
37 http://www.ietf.org/shadow.html. | |
38 | |
39 This document and related documents are discussed on the impp | |
40 mailing list. To join the list, send mail to impp- | |
41 request@iastate.edu. To contribute to the discussion, send mail to | |
42 impp@iastate.edu. The archives are at http://lists.fsck.com/cgi- | |
43 bin/wilma/pip. The IMPP working group charter, including the current | |
44 list of group documents, can be found at | |
45 http://www.ietf.org/html.charters/impp-charter.html. | |
46 | |
47 | |
48 | |
49 1. Abstract | |
50 | |
51 Microsoft released a commercial Instant Messaging product in July of | |
52 1999 called MSN Messenger Service. This document describes the | |
53 protocol used by that product for core instant messaging and | |
54 presence functionality. While this protocol does not meet many of | |
55 the requirements of the IMPP working group, it is provided as | |
56 background information on existing Instant Messaging | |
57 implementations. This protocol is provided 'as is' without warranty | |
58 of any kind. | |
59 | |
60 | |
61 Movva and Lai Category - Informational 1 | |
62 | |
63 MSN Messenger Service 1.0 Protocol Aug - 99 | |
64 | |
65 | |
66 | |
67 2. Conventions used in this document | |
68 | |
69 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |
70 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in | |
71 this document are to be interpreted as described in RFC-2119. | |
72 | |
73 Protocol messages sent from client to server are preceded by "C:". | |
74 | |
75 Protocol messages sent from server to client are preceded by "S:". | |
76 | |
77 | |
78 | |
79 3. Introduction | |
80 | |
81 MSN Messenger Service enables a user to learn about the presence of | |
82 other people on the Internet, and to communicate with them in real- | |
83 time. This functionality is commonly referred to as "Instant | |
84 Messaging" (IM). | |
85 | |
86 This document describes the syntax and semantics of the MSN | |
87 Messenger Protocol, the communication protocol running between MSN | |
88 Messenger Service 1.0 clients and servers. Among the core services | |
89 that the MSN Messenger Servers provide to clients are: | |
90 | |
91 - Authenticated user logon. | |
92 - Adding and deleting members of the user's contact list. | |
93 - Changing the user's on-line state. | |
94 - Receipt of asynchronous, real-time, on-line state change | |
95 notifications from members of the user's contact list. | |
96 - Delivering lightweight, real-time messages to other users. | |
97 - Receipt of asynchronous, real-time messages from other users. | |
98 - Configuring the user's access permissions, to restrict the ability | |
99 of other users to view the user's on-line state or send messages | |
100 to the user. | |
101 | |
102 Additional background: | |
103 | |
104 1. Some features extraneous to core instant messaging functionality | |
105 contained within the MSN Messenger Service 1.0 protocol are beyond | |
106 the scope of this document. Examples include client version | |
107 management and directory functionality. | |
108 | |
109 2. The purpose of this document is to provide the members of the | |
110 IMPP working group with a reference implementation of a "monolithic" | |
111 IM system. That is, a system designed for massive scale, but not yet | |
112 capable of communication with servers other than those associated | |
113 with this specific service. Since any standard in this area will of | |
114 necessity be a "distributed" design that explicitly enables server- | |
115 to-server and service-to-service communication, this document will | |
116 serve primarily as a reference and example of one implementer's | |
117 choices when providing IM functionality at scale. | |
118 | |
119 | |
120 Movva and Lai Category - Informational 2 | |
121 | |
122 MSN Messenger Service 1.0 Protocol Aug - 99 | |
123 | |
124 | |
125 3. This document reflects the protocol used in the 1.0 release of | |
126 MSN Messenger clients and servers, deployed on the Internet in July | |
127 of 1999. However, the service is in production and rapidly growing, | |
128 which almost certainly will necessitate changes to the protocol as | |
129 Microsoft gains operational experience with the service and expands | |
130 its feature set. This Internet Draft may not be updated with such | |
131 changes, and the changes may be made with little or no notice. | |
132 | |
133 | |
134 | |
135 4. MSN Messenger Server Component Overview | |
136 | |
137 MSN Messenger Service clients make connections to several different | |
138 kinds of servers. They are separate components to facilitate running | |
139 at scale - each component can be duplicated an arbitrary number of | |
140 times, independently of each other, to enable large numbers of | |
141 users. | |
142 | |
143 4.1 Dispatch Server (DS) | |
144 | |
145 The Dispatch Server is the initial point of connection between | |
146 client and server. Its primary functions are protocol version | |
147 negotiation, determination of which Notification Server (NS) is | |
148 associated with the client making a connection (via an algorithm of | |
149 the server's choosing), and referring the client to the proper NS. | |
150 | |
151 4.2 Notification Server (NS) | |
152 | |
153 The Notification Server is the primary server component. The client | |
154 and the Notification Server authenticate, synchronize user | |
155 properties, and exchange asynchronous event notifications. The | |
156 client's connection to the Notification Server occurs after the | |
157 referral from the Dispatch Server is completed, and persists without | |
158 interruption during the user's MSN Messenger Service session. | |
159 | |
160 Some of the events transmitted between a client and a Notification | |
161 Server are: State changes (e.g. client is on-line, client is | |
162 offline, client is idle), Switchboard Server invitation requests | |
163 (see below), and application-specific notifications that are beyond | |
164 the scope of this document. (E.g. new e-mail has arrived) | |
165 | |
166 4.3 Switchboard Server (SS) | |
167 | |
168 The Switchboard Server is the component through which clients can | |
169 establish lightweight communication sessions without requiring a | |
170 direct network connection between clients. The common usage of the | |
171 Switchboard Server is to provide instant messaging sessions. | |
172 When a client wishes to communicate with another client, it sends a | |
173 message to its Notification Server, which then refers the client to | |
174 a Switchboard Server. Once the SS connection is established, the | |
175 "destination" client receives a notification from its NS to connect | |
176 to the same SS. | |
177 | |
178 | |
179 Movva and Lai Category - Informational 3 | |
180 | |
181 MSN Messenger Service 1.0 Protocol Aug - 99 | |
182 | |
183 | |
184 5. Protocol Conventions | |
185 | |
186 5.1 Connection Type | |
187 | |
188 The MSN Messenger Protocol currently works over TCP/IP. The MSN | |
189 Messenger server components support connections over port numbers | |
190 1863, which is the registered port number assigned by the IANA | |
191 (http://www.isi.edu/in-notes/iana/assignments/port-numbers). | |
192 | |
193 5.2 Command Syntax | |
194 | |
195 MSN Messenger Protocol command syntax is ASCII and single line- | |
196 based. Commands begin with a case-sensitive, three-letter command | |
197 type, followed by zero or more parameters, and terminated by CRLF. | |
198 Parameters are separated by one or more whitespace characters and | |
199 cannot contain whitespace characters. Parameters that contain spaces | |
200 or extended (non 7-bit ASCII) characters should be encoded using | |
201 URL-style encoding (e.g. "%20" for space). Some commands accept un- | |
202 encoded binary data. In these cases, the length of the data is | |
203 transmitted as part of the command, and the data is transmitted | |
204 immediately following a CRLF of the command. | |
205 | |
206 5.3 Asynchronous Requests | |
207 | |
208 Commands issued from the client to the server that result in a reply | |
209 are known as requests. Requests are entirely asynchronous. The | |
210 client can submit several requests in sequence without waiting for | |
211 the server response after submitting each request. The server is | |
212 required to deliver a response or an error for each request | |
213 received, but it is not required to deliver the responses in the | |
214 same order as the requests were received. The client can determine | |
215 the request associated with a particular response by examining the | |
216 Transaction ID parameter (described below). | |
217 | |
218 5.4 User Handles | |
219 | |
220 MSN Messenger Protocol uses User Handles for identifying users. A | |
221 user handle (also known as "account name" and "logon name") is a | |
222 text representation of the user's identity that is both unique and | |
223 persistent. The user handle is syntactically equivalent to an e-mail | |
224 address, and as such is subject to the same restrictions for | |
225 character set, as described in RFC-822. Most notable among these | |
226 restrictions are the limitation to Latin alphanumeric characters and | |
227 a few symbols. The maximum acceptable length of the user handle is | |
228 129 bytes. | |
229 | |
230 Implementation note: In the initial release of the client and | |
231 server, user handles are Hotmail account names. All user handles | |
232 must contain the "@hotmail.com" domain name, and user handles that | |
233 do not contain a domain name are not valid. | |
234 | |
235 5.5 Custom User Names | |
236 | |
237 | |
238 Movva and Lai Category - Informational 4 | |
239 | |
240 MSN Messenger Service 1.0 Protocol Aug - 99 | |
241 | |
242 | |
243 A custom user name (also known as "custom name" and "friendly name") | |
244 is a user's representation of the "friendly" textual name associated | |
245 with a user handle. (E.g. "Auntie Em" instead of em123@hotmail.com). | |
246 Custom user names are neither unique nor persistent, and can contain | |
247 any valid Unicode characters. Custom user names are represented in | |
248 UTF-8 as described in RFC-2044 and URL-encoded as described in RFC- | |
249 1738 when transmitted between the client and server. The maximum | |
250 acceptable length of the encoded custom user name is 387 in the | |
251 current implementation. | |
252 | |
253 5.6 Transaction Identifiers | |
254 | |
255 The Transaction Identifier (a.k.a. Transaction ID) is a numeric | |
256 string representing a number between 0 and (2^32 - 1). It is a value | |
257 that a client includes with any command that it issues to the | |
258 server. In the current version of the protocol, the transaction | |
259 identifier is used to associate server responses with client-issued | |
260 commands. The server treats the transaction ID as an opaque number | |
261 and does not assume any relationship between successive Transaction | |
262 | |
263 IDs or any particular starting Transaction ID. It is the client's | |
264 responsibility to guarantee the uniqueness of the Transaction IDs | |
265 for the purpose of disambiguating the commands and/or responses. (A | |
266 future version of the protocol could enable the client to track the | |
267 status or cancel a particular transaction using the transaction ID.) | |
268 | |
269 When the server sends the response to a command to the client, it | |
270 must include in the response the transaction ID that the client sent | |
271 to the server when the client originally issued the command. In | |
272 cases where a server sends a command to a client that requires a | |
273 transaction ID but is not in response to a specific client command, | |
274 it will use 0 as the transaction ID. In cases where a server sends | |
275 multiple responses to a single client request, the server will use | |
276 the same transaction ID in each response. | |
277 | |
278 5.7 User List Types | |
279 | |
280 Some of the protocol commands are used to the manipulate lists of | |
281 users. The following types of user lists are supported by the | |
282 protocol: | |
283 | |
284 Forward List (FL) - The list of users for whom a given user wants to | |
285 receive state change notifications. The Forward List is what is most | |
286 commonly referred to as the user's "contact list." | |
287 | |
288 Reverse List (RL) - The list of users who have registered an | |
289 interest in seeing this user's state change notifications. | |
290 | |
291 Allow List (AL) - The list of users who the user has explicitly | |
292 allowed to see state change notifications and establish client-to- | |
293 client sessions via a Switchboard Server. | |
294 | |
295 | |
296 | |
297 Movva and Lai Category - Informational 5 | |
298 | |
299 MSN Messenger Service 1.0 Protocol Aug - 99 | |
300 | |
301 | |
302 Block List (BL) - The list of users who the user has explicitly | |
303 prevented from seeing state change notifications and establishing | |
304 client-to-client sessions via a Switchboard Server. | |
305 | |
306 | |
307 | |
308 6. Command Summary Table | |
309 | |
310 Command From To Description | |
311 ================================================================== | |
312 ACK Switchboard Client Sends a positive message | |
313 delivery acknowledgement. | |
314 ------------------------------------------------------------------- | |
315 ADD Client Notification Adds to the user's FL, AL, | |
316 Notification Client and BL. Notifies the client | |
317 of asynchronous additions | |
318 to a user's list. | |
319 ------------------------------------------------------------------- | |
320 ANS Client Switchboard Accepts a request for a | |
321 switchboard server session. | |
322 ------------------------------------------------------------------- | |
323 BLP Client Notification Changes the user's message | |
324 Notification Client privacy setting, which | |
325 determines how to treat | |
326 messages from users not | |
327 already in the BL or AL. | |
328 ------------------------------------------------------------------- | |
329 BYE Switchboard Client Notifies a client that a | |
330 user is no longer in the | |
331 session. | |
332 ------------------------------------------------------------------- | |
333 CAL Client Switchboard Initiates a switchboard | |
334 server session. | |
335 ------------------------------------------------------------------- | |
336 CHG Client Notification Sends a client state change | |
337 Notification Client to the server. | |
338 Echoes the success of | |
339 client's state change | |
340 request. | |
341 ------------------------------------------------------------------- | |
342 FLN Notification Client Notifies the client when | |
343 users in the FL go off- | |
344 line. | |
345 ------------------------------------------------------------------- | |
346 GTC Client Notification Changes the user's prompt | |
347 Notification Client setting, which determines | |
348 how the client reacts to | |
349 certain RL changes. | |
350 ------------------------------------------------------------------- | |
351 INF Client Dispatch, Requests set of support | |
352 Notification authentication protocol | |
353 Dispatch, Client from the server. | |
354 Notification Provides the set of | |
355 | |
356 Movva and Lai Category - Informational 6 | |
357 | |
358 MSN Messenger Service 1.0 Protocol Aug - 99 | |
359 | |
360 | |
361 supported authentication | |
362 protocols to the client. | |
363 ------------------------------------------------------------------- | |
364 ILN Notification Client Notifies the client of the | |
365 initial online state of a | |
366 user in the FL, while | |
367 either logging on or adding | |
368 a user to the FL. | |
369 ------------------------------------------------------------------- | |
370 IRO Switchboard Client Provides the initial roster | |
371 information for new users | |
372 joining the session. | |
373 ------------------------------------------------------------------- | |
374 JOI Switchboard Client Notifies a client that a | |
375 user is now in the session. | |
376 ------------------------------------------------------------------- | |
377 LST Client Notification Retrieves the server's | |
378 Notification Client version of the user's FL, | |
379 RL, AL, or BL. | |
380 ------------------------------------------------------------------- | |
381 MSG Client Switchboard Sends a message to the | |
382 members of the current | |
383 session. | |
384 ------------------------------------------------------------------- | |
385 MSG Notification, Client Delivers a message from | |
386 Switchboard another client or from a | |
387 server-side component. | |
388 ------------------------------------------------------------------- | |
389 NAK Switchboard Client Sends a negative message | |
390 delivery acknowledgement. | |
391 ------------------------------------------------------------------- | |
392 NLN Notification Client Notifies the client when | |
393 users in the FL go on-line | |
394 or when their on-line state | |
395 changes. | |
396 ------------------------------------------------------------------- | |
397 OUT All All Ends a client-server | |
398 Session. | |
399 ------------------------------------------------------------------- | |
400 REM Client Notification Removes from the user's FL, | |
401 Notification Client AL, and BL. | |
402 Notifies the client of | |
403 asynchronous removals from | |
404 a user's list. | |
405 ------------------------------------------------------------------- | |
406 RNG Notification Client Notifies the client of a | |
407 request by another client | |
408 to establish a session via | |
409 a switchboard server. | |
410 ------------------------------------------------------------------- | |
411 SYN Client Notification Initiates client-server | |
412 Notification Client property synchronization. | |
413 ------------------------------------------------------------------- | |
414 | |
415 Movva and Lai Category - Informational 7 | |
416 | |
417 MSN Messenger Service 1.0 Protocol Aug - 99 | |
418 | |
419 | |
420 USR All All Authenticates client with | |
421 server, possibly in | |
422 multiple passes. | |
423 ------------------------------------------------------------------ | |
424 VER Client Dispatch Negotiates common protocol | |
425 Dispatch Client dialect between client and | |
426 Server. | |
427 ------------------------------------------------------------------ | |
428 XFR Client Notification Requests a Switchboard | |
429 Notification Client server for use in | |
430 establishing a session. | |
431 ------------------------------------------------------------------- | |
432 XFR Dispatch Client Notification of login-NS to | |
433 Notification Client the client or notification | |
434 to move to a different NS. | |
435 ======================================================================= | |
436 | |
437 | |
438 | |
439 7. Presence and State Protocol Details | |
440 | |
441 This is a detailed list of protocol commands associated with | |
442 presence functionality. They are defined in the order used by | |
443 clients. Commands associated with instant messages are discussed in | |
444 section 8 below. | |
445 | |
446 7.1 Protocol Versioning | |
447 | |
448 After the client connects to a dispatch server by opening a TCP | |
449 socket to port 1863, the client and server agree on a particular | |
450 protocol version before they proceed. The Client-Server protocol | |
451 version handshake involves the following command exchange: | |
452 | |
453 C: VER TrID dialect-name{ dialect-name...} | |
454 S: VER TrID dialect-name | |
455 | |
456 The client can provide multiple dialect names in preferred order. | |
457 The dialect-name parameter returned by the server is the version | |
458 server is designating for this connection | |
459 | |
460 The current protocol dialect-name supported by Messenger servers is | |
461 "MSNP2". The dialect names are not case-sensitive. | |
462 | |
463 The string "0" is a reserved dialect name and is used to indicate a | |
464 failure response. E.g.: | |
465 | |
466 S: VER TrID 0{ dialect-name ... } | |
467 | |
468 7.2 Server Policy Information | |
469 | |
470 The client next queries the server for variable "policy" | |
471 information. In this version of the protocol, the only policy | |
472 | |
473 | |
474 Movva and Lai Category - Informational 8 | |
475 | |
476 MSN Messenger Service 1.0 Protocol Aug - 99 | |
477 | |
478 | |
479 information returned by the server is the authentication package in | |
480 use. | |
481 | |
482 C: INF TrID | |
483 S: INF TrID SP{,SP...} | |
484 | |
485 SP identifies a security package - the name of the SASL mechanism to | |
486 use for authentication. "MD5" is used by the Notification Server, | |
487 "CKI" by the Switchboard Server. | |
488 | |
489 7.3 Authentication | |
490 | |
491 The client needs to authenticate itself after protocol version | |
492 handshake and identifying the security packages supported on the | |
493 server. The following are the client server interactions involved. | |
494 | |
495 C: USR TrID SP I{ AuthInitiateInfo} | |
496 S: USR TrID SP S{ AuthChallengeInfo} | |
497 C: USR TrID SP S{ AuthResponseInfo } | |
498 S: USR TrID OK UserHandle FriendlyName | |
499 | |
500 The SP parameter is the name of the security package("MD5"). The | |
501 next parameter is a sequence value, which must be I to (I)nitiate | |
502 the authentication process and S for all (S)ubsequent messages. If | |
503 authentication fails on the server, the client can start the | |
504 authentication process again. | |
505 | |
506 For the MD5 security package: | |
507 - The AuthInitiateInfo parameter provided by the client must be the | |
508 User handle. | |
509 - The AuthChallengeInfo parameter returned by the server contains a | |
510 challenge string. | |
511 - The AuthResponseInfo contains the binary response as a hexadecimal | |
512 string, which the MD5 hash of the challenge and the User password | |
513 strings concatenated together. | |
514 | |
515 The final response from the server contains, in addition to the user | |
516 handle, the current "Friendly Name" associated with the user handle. | |
517 This is a "Custom User Name" as described above. | |
518 | |
519 7.4 Referral | |
520 | |
521 There are three cases in which clients are referred from one server | |
522 to another: | |
523 | |
524 1. The initial "Dispatch Server" refers the client to the | |
525 Notification Server to which it is assigned. | |
526 2. Asynchronous referral by the Notification Server to reassign the | |
527 client to a different Notification Server if that server is | |
528 overloaded or undergoing maintenance. | |
529 3. During Switchboard Session establishment, the assigned | |
530 Notification Server refers the client to a particular | |
531 switchboard server for use. This is discussed below. | |
532 | |
533 Movva and Lai Category - Informational 9 | |
534 | |
535 MSN Messenger Service 1.0 Protocol Aug - 99 | |
536 | |
537 | |
538 | |
539 In the current implementation the Dispatch Server uses the user | |
540 handle provided in the initial USR command above to assign the user | |
541 in question to a Notification Server. Alternate implementations | |
542 might not require referral at this stage. | |
543 | |
544 If received, referral is of the form: | |
545 | |
546 S: XFR TrID ReferralType Address[:PortNo] | |
547 | |
548 ReferralType is either "NS" or "SB" and defines the type of referral | |
549 to a Notification Server or Switchboard Server. | |
550 Address is a valid DNS name or IP address to a referred server, with | |
551 optional port# suffixed as ":PortNo". | |
552 | |
553 If this command is received from the server, the client should | |
554 attempt to log in to the server provided. | |
555 | |
556 In the case of "NS" referrals during logon, the Server automatically | |
557 closes the client connection after sending this XFR response so that | |
558 the client can connect to the new IP Address. | |
559 | |
560 If sent asynchronously, the client is responsible for closing the | |
561 connection. | |
562 | |
563 After a "NS" referral, the client will not receive any more messages | |
564 from the "old" NS, and also must not send any commands to the "old" | |
565 NS after receiving an XFR. | |
566 | |
567 7.5 Client User Property Synchronization | |
568 | |
569 Several of the user properties used by the Messenger application are | |
570 stored on the server. This is done for two reasons: | |
571 | |
572 1) So that users can "roam", i.e. log in from different locations | |
573 and still have the appropriate data, such as their contact lists and | |
574 privacy settings. | |
575 2) If changes occur to a user's Reverse List while that user was | |
576 offline (the user was added to another user's list), the client can | |
577 be updated with this information. | |
578 | |
579 For performance reasons it is useful to cache these properties on | |
580 the client, so that bandwidth usage is minimized in the typical case | |
581 where the user is not roaming and there were no Reverse List | |
582 changes. | |
583 | |
584 These requirements are met by the SYN command - synchronization. | |
585 | |
586 Once a client logs in successfully, it uses the SYN command to | |
587 ensure it has the latest version of the server-stored properties. | |
588 These properties include: Forward List, Reverse List, Block List, | |
589 Allow List, GTC setting (privacy setting when someone adds this user | |
590 to their Forward List), and BLP setting (the user's privacy mode). | |
591 | |
592 Movva and Lai Category - Informational 10 | |
593 | |
594 MSN Messenger Service 1.0 Protocol Aug - 99 | |
595 | |
596 | |
597 | |
598 The SYN command is: | |
599 | |
600 C: SYN TrID Ser# | |
601 S: SYN TrID Ser# | |
602 | |
603 The Ser# parameter sent by the client is the version of the | |
604 properties currently cached on the client. The server responds with | |
605 the current server version of the properties. If the server has a | |
606 newer version, the server will immediately follow the SYN reply by | |
607 updating the client with the latest version of the user properties. | |
608 These updates are done as described below, and are done without the | |
609 client explicitly initiating a LST, GTC or BLP command. Note that | |
610 the server will update all server-stored properties to the client, | |
611 regardless of how many entries have been changed. | |
612 | |
613 The following "List Retrieval and Property Management" section | |
614 describes the format of the user properties sent by the server. | |
615 After the SYN reply from the server, the user property updates will | |
616 be sent from the server in this sequence: GTC, BLP, LST FL, LST AL, | |
617 LST BL, LST RL. | |
618 | |
619 All the user property updates will share the same TrID as the SYN | |
620 command and reply. | |
621 | |
622 7.6 List Retrieval And Property Management | |
623 | |
624 Synchronizing can result in a batch of user properties and lists | |
625 getting sent by the server to the client. However, the client | |
626 application can also initiate a request to retrieve the server- | |
627 stored lists and properties. The following are the privacy property | |
628 and list retrieval commands. The response formats are the same | |
629 whether it is a client-initiated request, or whether it is a | |
630 response to the SYN process as described above. | |
631 | |
632 | |
633 List Command | |
634 | |
635 By issuing the LST command, the client can explicitly request that a | |
636 list be sent. The server will respond with a series of LST | |
637 responses, one LST response for each item in the requested list. | |
638 | |
639 C: LST TrID LIST | |
640 S: LST TrID LIST Ser# Item# TtlItems UserHandle CustomUserName | |
641 | |
642 - LIST is FL/RL/AL/BL for Forward List, Reverse List, Allow List, | |
643 and Block List, respectively. | |
644 - The Item# parameter contains the index of the item described in | |
645 this command message. (E.g. item 1 of N, 2 of N, etc.) | |
646 - The TtlItems parameter contains the total number of items in this | |
647 list. | |
648 - UserHandle is the user handle for this list item. | |
649 - CustomUserName is the friendly name for this list item. | |
650 | |
651 | |
652 Movva and Lai Category - Informational 11 | |
653 | |
654 MSN Messenger Service 1.0 Protocol Aug - 99 | |
655 | |
656 | |
657 If the list is empty, the response will be: | |
658 | |
659 S: LST TrID LIST Ser# 0 0 | |
660 | |
661 Reverse List Prompting | |
662 | |
663 The client can change its persistent setting for when to prompt the | |
664 user in reaction to an Reverse List change. This is accomplished via | |
665 the GTC command: | |
666 | |
667 C: GTC TrID [A | N] | |
668 S: GTC TrID Ser# [A | N] | |
669 | |
670 The value of the A/N parameter determines how the client should | |
671 behave when it discovers that a user is in its RL, but is not in its | |
672 AL or BL. (Note that this occurs when a user has been added to | |
673 another user's list, but has not been explicitly allowed or | |
674 blocked): | |
675 | |
676 A - Prompt the user as to whether the new user in the RL should be | |
677 added to the AL or the BL | |
678 N - Automatically add the new user in the RL to the AL | |
679 | |
680 The A/N parameter is not interpreted by the server, merely stored. | |
681 | |
682 The server will respond with the current setting if the change was | |
683 successful. Otherwise, it will return an error with the matching | |
684 TrID. If the client tries to change the setting to the same value as | |
685 the current setting, the server will respond with an error message. | |
686 | |
687 The default setting is A when a new user connects to the server for | |
688 the first time. | |
689 | |
690 Privacy Mode | |
691 | |
692 The client can change how the server handles instant messages from | |
693 users via the BLP command: | |
694 | |
695 C: BLP TrID [AL | BL] | |
696 S: BLP TrID Ser# [AL | BL] | |
697 | |
698 The AL/BL parameter determines how the server should treat messages | |
699 (MSG and RNG) from users. If the current setting is AL, messages | |
700 from users who are not in BL will be delivered. If the current | |
701 setting is BL, only messages from people who are in the AL will be | |
702 delivered. | |
703 | |
704 The server will respond with the current setting if the change was | |
705 successful. Otherwise, it will return an error with the matching | |
706 TrID. If the client tries to change the setting to the same value as | |
707 the current setting, the server will respond with an error message. | |
708 | |
709 | |
710 | |
711 Movva and Lai Category - Informational 12 | |
712 | |
713 MSN Messenger Service 1.0 Protocol Aug - 99 | |
714 | |
715 | |
716 The default setting is AL when a new user connects to the server for | |
717 the first time. | |
718 | |
719 | |
720 7.7 Client States | |
721 | |
722 After the client is authenticated and synchronized, the client | |
723 establishes its initial state with the server with the CHG command. | |
724 The syntax of the command is: | |
725 | |
726 C: CHG TrID State | |
727 S: CHG TrID State | |
728 | |
729 When the state is changed, the server will echo the settings back to | |
730 client. The state shall not be considered changed until the response | |
731 is received from the server. | |
732 | |
733 Note that the server can send a state change message to the client | |
734 at any time. If the server changes the state without a request from | |
735 the client, the TrID parameter will be 0. | |
736 | |
737 States are denoted by a string of three characters. The predefined | |
738 states that the server recognizes are: | |
739 | |
740 NLN - Make the client Online (after logging in) and send and receive | |
741 notifications about buddies. | |
742 FLN - Make the client Offline. If the client is already online, | |
743 offline notifications will be sent to users on the RL. No message | |
744 activity is allowed. In this state, the client can only synchronize | |
745 the lists as described above. | |
746 HDN - Make the client Hidden/Invisible. If the client is already | |
747 online, offline notifications will be sent to users on the RL. The | |
748 client will appear as Offline to others but can receive | |
749 online/offline notifications from other users, and can also | |
750 synchronize the lists. Clients cannot receive any instant messages | |
751 in this state. | |
752 | |
753 All other States are treated as sub-states of NLN (online). The | |
754 other States currently supported are: | |
755 BSY - Busy. | |
756 IDL - Idle. | |
757 BRB - Be Right Back. | |
758 AWY - Away From Computer. | |
759 PHN - On The Phone. | |
760 LUN - Out To Lunch. | |
761 | |
762 7.8 List Modifications | |
763 | |
764 The protocol supports generic commands to add and remove users from | |
765 various lists. This is used by clients to enable "Adding" contacts | |
766 to the list of folks being watched, or for the "Block" and "Allow" | |
767 features that define how users chooses to interact with one another. | |
768 | |
769 | |
770 Movva and Lai Category - Informational 13 | |
771 | |
772 MSN Messenger Service 1.0 Protocol Aug - 99 | |
773 | |
774 | |
775 However, these generic commands have different semantics based on | |
776 the list being modified. For example, only the server can add or | |
777 remove entries from the Reverse List - since it is an indirect | |
778 consequence of the user having been added to another user's Forward | |
779 List. | |
780 | |
781 The add and remove commands: | |
782 | |
783 C: ADD TrID LIST UserHandle CustomUserName | |
784 S: ADD TrID LIST ser# UserHandle CustomUserName | |
785 | |
786 C: REM TrID LIST UserHandle | |
787 S: REM TrID LIST ser# UserHandle | |
788 | |
789 Valid values for LIST in Client initiated adds and removes are | |
790 FL/AL/BL. | |
791 | |
792 All client initiated adds and removes will be echoed by the server | |
793 with a new serial number that should be persisted by the client | |
794 along with the list modification. If not successful, an error will | |
795 result. | |
796 | |
797 The protocol also supports the concept of an ADD or REM that the | |
798 client did not initiate. Server generated ADDs and REMs can have | |
799 LIST values of FL/AL/BL/RL. This is common with RL changes, which | |
800 are never initiated by the client, but is an indirect consequence of | |
801 this user having been added to someone's Forward List. If the RL | |
802 change happens while the user is online, it will trigger an | |
803 asynchronous ADD or REM command from the server. | |
804 | |
805 Asynchronous ADDs and REMs to the FL, AL, and BL can happen when the | |
806 server allows an authenticated user to make list changes from | |
807 another environment, such as a web site. In all of these cases, the | |
808 server will send the ADD or REM command with the TrID parameter | |
809 equal to 0. | |
810 | |
811 7.9 Notification Messages | |
812 | |
813 The client receives asynchronous notifications whenever a contact on | |
814 the user's Forward List changes its state. The notifications are of | |
815 the form: | |
816 | |
817 S: NLN Substate UserHandle FriendlyName | |
818 S: ILN TrID Substate UserHandle FriendlyName | |
819 S: FLN UserHandle | |
820 | |
821 NLN indicates that a user has come online. | |
822 - Substate can be any three-letter code (see "Client States" above). | |
823 - UserHandle and FriendlyName are the handle and names associated | |
824 with the user coming online. | |
825 | |
826 ILN is similar to the NLN message, and is received from the server | |
827 in response to an CHG or ADD command from the client: | |
828 | |
829 Movva and Lai Category - Informational 14 | |
830 | |
831 MSN Messenger Service 1.0 Protocol Aug - 99 | |
832 | |
833 | |
834 | |
835 1. Immediately after the client logon and sends its first CHG | |
836 command to the NS. In this case several ILNs may be received - | |
837 one for each Forward List contact that is currently online. | |
838 2. After the client sends an "ADD TrID FL UserHandle | |
839 CustomUserName" to the NS. (e.g. ILN for the new contact if that | |
840 contact is currently online) | |
841 | |
842 In both cases, TrID in the ILN is the same as the one sent by the | |
843 client in the CHG or ADD command. | |
844 | |
845 FLN means that the specified user is now offline. | |
846 | |
847 7.10 Connection Close | |
848 | |
849 The client issues the following command to logoff from the NS: | |
850 | |
851 C: OUT | |
852 S: OUT {StatusCode} | |
853 | |
854 The server will reply with an OUT to the client before it initiates | |
855 a disconnect, with an optional StatusCode. | |
856 | |
857 The StatusCode can be "OTH", which indicates that a client with the | |
858 same user handle and password has logged on to the server from | |
859 another location, or "SSD" meaning the server is being shut down for | |
860 maintenance. | |
861 | |
862 The server will drop the connection after sending the OUT. | |
863 | |
864 7.11 Error Information | |
865 | |
866 Error messages from the server are of the format: | |
867 | |
868 S: eee {TrID} {(error-info) {param...}} | |
869 | |
870 eee is a 3 digit decimal number indicating the error code. Error- | |
871 info contains the description of the error in a text string | |
872 localized to the server's locale. The optional parameters provide | |
873 indication of the client command causing the error. TrID is the | |
874 Transaction ID of the client command that caused this error. Any | |
875 server generated errors will not have Transaction IDs. | |
876 | |
877 | |
878 ERR_SYNTAX_ERROR 200 | |
879 ERR_INVALID_PARAMETER 201 | |
880 ERR_INVALID_USER 205 | |
881 ERR_FQDN_MISSING 206 | |
882 ERR_ALREADY_LOGIN 207 | |
883 ERR_INVALID_USERNAME 208 | |
884 ERR_INVALID_FRIENDLY_NAME 209 | |
885 ERR_LIST_FULL 210 | |
886 ERR_ALREADY_THERE 215 | |
887 | |
888 Movva and Lai Category - Informational 15 | |
889 | |
890 MSN Messenger Service 1.0 Protocol Aug - 99 | |
891 | |
892 | |
893 ERR_NOT_ON_LIST 216 | |
894 ERR_ALREADY_IN_THE_MODE 218 | |
895 ERR_ALREADY_IN_OPPOSITE_LIST 219 | |
896 ERR_SWITCHBOARD_FAILED 280 | |
897 ERR_NOTIFY_XFR_FAILED 281 | |
898 | |
899 ERR_REQUIRED_FIELDS_MISSING 300 | |
900 ERR_NOT_LOGGED_IN 302 | |
901 ERR_INTERNAL_SERVER 500 | |
902 ERR_DB_SERVER 501 | |
903 ERR_FILE_OPERATION 510 | |
904 ERR_MEMORY_ALLOC 520 | |
905 ERR_SERVER_BUSY 600 | |
906 ERR_SERVER_UNAVAILABLE 601 | |
907 ERR_PEER_NS_DOWN 602 | |
908 ERR_DB_CONNECT 603 | |
909 ERR_SERVER_GOING_DOWN 604 | |
910 ERR_CREATE_CONNECTION 707 | |
911 ERR_BLOCKING_WRITE 711 | |
912 ERR_SESSION_OVERLOAD 712 | |
913 ERR_USER_TOO_ACTIVE 713 | |
914 ERR_TOO_MANY_SESSIONS 714 | |
915 ERR_NOT_EXPECTED 715 | |
916 ERR_BAD_FRIEND_FILE 717 | |
917 ERR_AUTHENTICATION_FAILED 911 | |
918 ERR_NOT_ALLOWED_WHEN_OFFLINE 913 | |
919 ERR_NOT_ACCEPTING_NEW_USERS 920 | |
920 | |
921 | |
922 | |
923 8. Session based Instant Messaging Protocol Details | |
924 | |
925 MSN Messenger Service utilizes a lightweight, session-based | |
926 messaging scheme. In order for two clients to exchange instant | |
927 messages, they must first establish a common session via a | |
928 Switchboard Server. They can invite additional clients to join the | |
929 established session. | |
930 | |
931 8.1 Referral to Switchboard | |
932 | |
933 This process begins with a "calling" client requesting a referral | |
934 from its Notification Server to a Switchboard Server: | |
935 | |
936 C: XFR TrID SB | |
937 S: XFR TrID SB Address SP AuthChallengeInfo | |
938 | |
939 - SB is the type of referral being requested or granted. | |
940 - Address is the DNS name or IP address of a Switchboard Server that | |
941 has been assigned, and that the client should connect to. | |
942 - SP is the Security Package being used. In this version of the | |
943 protocol it is "CKI" only. | |
944 - AuthChallengeInfo is a cookie that the client needs to present to | |
945 the Switchboard server for authentication. | |
946 | |
947 | |
948 Movva and Lai Category - Informational 16 | |
949 | |
950 MSN Messenger Service 1.0 Protocol Aug - 99 | |
951 | |
952 | |
953 8.2 Switchboard Connections and Authentication | |
954 | |
955 After the XFR reply is received, the client makes a TCP/IP | |
956 connection to the Switchboard server using port 1863. Note that a | |
957 lack of version negotiation in the switchboard connection is a | |
958 limitation of the current implementation. | |
959 | |
960 The client first needs to authenticates with the Switchboard Server: | |
961 | |
962 C: USR TrID UserHandle AuthResponseInfo | |
963 S: USR TrID OK UserHandle FriendlyName | |
964 | |
965 - AuthResponseInfo is the cookie for CKI security package returned | |
966 by the Notification Server in the XFR. | |
967 - UserHandle and FriendlyName are the Switchboard's echoes of the | |
968 user handle and friendly name of the user. | |
969 | |
970 8.3 Inviting Users to a Switchboard Session | |
971 | |
972 Any user in a Switchboard session can invite other users to join the | |
973 session. The CAL command is sent to the Switchboard server for this | |
974 purpose: | |
975 | |
976 C: CAL TrID UserHandle | |
977 S: CAL TrID Status SessionID | |
978 | |
979 The Messenger servers verify that the calling user has permissions | |
980 to contact the called user, with consideration given to the called | |
981 user's privacy settings and its online state. If instant messaging | |
982 with this user is not allowed, the server responds to the calling | |
983 user with an error. If it is allowed, the Switchboard server causes | |
984 a RNG command to be sent to the called client (see below), and | |
985 returns a CAL echo to the calling client. The CAL echo has these | |
986 parameters: | |
987 | |
988 - Status is a predefined status code - in this implementation it | |
989 must be "RINGING". | |
990 - SessionID is the ASCII representation of a decimal number that | |
991 uniquely identifies this session on the Switchboard Server. | |
992 | |
993 8.4 Getting Invited to a Switchboard Session | |
994 | |
995 The other side of the session establishment is the behavior of the | |
996 called client. The called client receives a RNG from its | |
997 Notification Server and is expected to connect to the Switchboard | |
998 Server and respond with an ANS. | |
999 | |
1000 The client receives a RNG from the Notification Server as follows: | |
1001 | |
1002 S: RNG SessionID SwitchboardServerAddress SP AuthChallengeInfo | |
1003 CallingUserHandle CallingUserFriendlyName | |
1004 | |
1005 - SessionID is a numeric ASCII session ID. | |
1006 | |
1007 Movva and Lai Category - Informational 17 | |
1008 | |
1009 MSN Messenger Service 1.0 Protocol Aug - 99 | |
1010 | |
1011 | |
1012 - SwitchboardServerAddress is a DNS name or IP Address | |
1013 - SP is the security package in use. In this implementation only | |
1014 "CKI" is supported. | |
1015 - AuthChallengeInfo is the cookie to be passed back to the | |
1016 switchboard to gain entrance to the session. | |
1017 - CallingUserHandle is the user handle of the caller. | |
1018 - CallingUserFriendlyName is the custom user name of the caller. | |
1019 | |
1020 To join the session, the called client connects to the Switchboard | |
1021 Server and carries out the following exchange to join the session: | |
1022 | |
1023 C: ANS TrID LocalUserHandle AuthResponseInfo SessionID | |
1024 S: IRO TrID Participant# TotalParticipants UserHandle | |
1025 FriendlyName | |
1026 S: ANS TrID OK | |
1027 | |
1028 The IRO commands relay to the newly joined client roster information | |
1029 about the current session. Each IRO command message from the | |
1030 Switchboard contains one participant in the session. | |
1031 - Participant# contains the index of the participant described in | |
1032 this IRO command (e.g. 1 of N, 2 of N). | |
1033 - TotalParticipants contains the total number of participants | |
1034 currently in the session. | |
1035 | |
1036 The entire session roster will be sent to the new client joining the | |
1037 session before any JOI or BYE commands described below. | |
1038 | |
1039 If no one is in the session when the user joins (an unexpected error | |
1040 condition), the server skips directly to "ANS TrID OK" command. All | |
1041 the responses from the server related to the issued ANS command will | |
1042 contain the same TrID as the original client ANS request. | |
1043 | |
1044 8.5 Session Participant Changes | |
1045 | |
1046 When a new user joins a Switchboard session, the server sends the | |
1047 following command to all participating clients, including the client | |
1048 joining the session: | |
1049 | |
1050 S: JOI CalleeUserHandle CalleeUserFriendlyName | |
1051 | |
1052 - CalleeUserHandle is the user handle of the new participant. | |
1053 - CalleeUserFriendlyName is the Custom User Name of the new | |
1054 participant. | |
1055 | |
1056 If a client's connection with the Switchboard Server is dropped for | |
1057 any reason, the server sends the following command to the remaining | |
1058 clients in the session: | |
1059 | |
1060 S: BYE CalleeUserHandle | |
1061 | |
1062 - CalleeUserHandle is the user handle of the participant that left | |
1063 the session. | |
1064 | |
1065 | |
1066 Movva and Lai Category - Informational 18 | |
1067 | |
1068 MSN Messenger Service 1.0 Protocol Aug - 99 | |
1069 | |
1070 | |
1071 Privacy Note: | |
1072 If the client moved a contact to the BL while Switchboard sessions | |
1073 are active, it is the client's responsibility to leave any session | |
1074 that should now be blocked. The servers only enforce privacy | |
1075 permissions when inviting users to a session. Further, the servers | |
1076 only enforce privacy permission with respect to the calling user, | |
1077 and not the other participants in a Switchboard session. Therefore, | |
1078 in a multipoint session, it is possible for a user to participate in | |
1079 a session with someone whom he has blocked, if a third party is | |
1080 performing the invitation. | |
1081 | |
1082 8.6 Leaving a Switchboard Session | |
1083 | |
1084 When a client wishes to disconnect from the session, it sends the | |
1085 following command and waits for the Switchboard to close the | |
1086 connection: | |
1087 | |
1088 C: OUT | |
1089 | |
1090 8.7 Instant Messages | |
1091 | |
1092 Sending an Instant Message | |
1093 | |
1094 Once a client-to-client session has been established via the | |
1095 Switchboard Server, sending an Instant Message to the participants | |
1096 of the session is done as follows: | |
1097 | |
1098 C: MSG TrID [U | N | A] Length\r\nMessage | |
1099 S: NAK TrID | |
1100 S: ACK TrID | |
1101 | |
1102 U, N, and A correspond to the three delivery acknowledgement modes: | |
1103 Unacknowledged, Negative-Acknowledgement-Only, and Acknowledgement. | |
1104 Depending on the value of this parameter, either nothing, NAK, or | |
1105 ACK will be sent back by the Switchboard Server to the client. | |
1106 | |
1107 For Unacknowledged mode, the Switchboard Server does not respond to | |
1108 the sending client with the success or failure of message delivery. | |
1109 | |
1110 For Negative-Acknowledgement-Only mode, the Switchboard Server | |
1111 responds to the send client only if the message could not be | |
1112 delivered to the recipient client. | |
1113 | |
1114 Acknowledgement mode is not currently implemented. | |
1115 | |
1116 Length is the length of the Message parameter in bytes, whereas | |
1117 Message is the actual message as described below. | |
1118 | |
1119 8.8 Receiving an Instant Message | |
1120 | |
1121 A client can receive a system-generated message from the | |
1122 Notification Server, or it can receive an instant message from | |
1123 | |
1124 | |
1125 Movva and Lai Category - Informational 19 | |
1126 | |
1127 MSN Messenger Service 1.0 Protocol Aug - 99 | |
1128 | |
1129 | |
1130 another client via a Switchboard Server. The message is received in | |
1131 the following format: | |
1132 | |
1133 S: MSG UserHandle FriendlyName Length\r\nMessage | |
1134 | |
1135 The UserHandle and FriendlyName are those of the sending user. | |
1136 Length is the length of the message in bytes. | |
1137 | |
1138 Message is a MIME encoded stream, using a standard MIME header as | |
1139 defined by RFC-1521 and RFC-822. | |
1140 | |
1141 Message is constructed as: | |
1142 | |
1143 MIME-Header\r\nMIME-Header\r\n\r\nMessageData | |
1144 | |
1145 MIME-Header is constructed as: | |
1146 | |
1147 string": "string | |
1148 (E.g. "Content-Type: text/plain") | |
1149 | |
1150 The Content-Type MIME headers that the current client will use and | |
1151 recognize are: | |
1152 | |
1153 "text/plain;charset=UTF-8" | |
1154 "text/plain" | |
1155 | |
1156 If "charset=UTF-8" appears at the end of the Content-Type, the | |
1157 Message Data is UTF-8 encoded. | |
1158 | |
1159 Note: The Switchboard Server does not interpret the contents of the | |
1160 Message. | |
1161 | |
1162 | |
1163 | |
1164 9. Author's Addresses | |
1165 | |
1166 Ramu Movva | |
1167 Microsoft Corporation | |
1168 One Microsoft Way | |
1169 Redmond WA 98052 | |
1170 ramum@microsoft.com | |
1171 | |
1172 William Lai | |
1173 Microsoft Corporation | |
1174 One Microsoft Way | |
1175 Redmond, WA 98052 | |
1176 wlai@microsoft.com | |
1177 | |
1178 | |
1179 | |
1180 Movva and Lai Category - Informational 20 |