/***************** http://www.hypothetic.org/docs/msn/general/commands.php#trid ******************/ Everything sent between the client and the server is in the form of a command. Commands are represented with a three letter, all-caps, command code. All normal commands have a transaction ID (explained below) and end with a newline (also explained below). Commands sent by the client will generally cause the server to respond with one or more commands. There are four special types of commands which behave slightly differently than normal commands. Payload Commands span over multiple lines. Error commands have numbers instead of letters in their command code. Asynchronous commands are sent by the server without the client explicitly requesting them, and do not contain transaction IDs. Finally, the PNG command and some SYN responses don't contain transaction IDs. =============================================================================================== 客户端和服务端一切形势的数据传输都是以命令的方式进行的。命令由3个大写字母组成，后跟命令代码。所有的普通命令都有一个传输号 （下面会详细介绍），命令以一个新行（newline）符号结束（下面详细介绍）。客户端发送的命令通常会引起服务器的一个或多个答复命令 （response）。 有四种特殊的命令与一般的命令有些微的不同。有效载荷命令[数据携带命令]（payload commands） 跨越多行。 错误提示命令（error commands）的命令代码（command code ） 由数字组成。异步命令（Asynchronous commands） 是服务器得到客户端不明确的请求时发送的，并且没有传输号（transaction IDs）。最后，PNG 命令和一些 SYN 回复 也 不包含 传输号（transaction IDs）。 ================================================================================================ Every normal command ends with a newline (see the Payload Commands page for exceptions). The use of \r and \n throughout this document are explained here. The official client always ends commands with \r\n and the server always ends commands with \r\n. It is recommended that you do this too. ================================================================================================ 所有的普通命令都以新行结束（数据携带命令是一个特殊情况）。\r 和 \n 在整个文档中的意义在下面解释。官方的客户端总是以 \r\n 作为一条命令的结束、服务段也同样以 \r\n 结束一条命令。我们也推荐你这样做。 ================================================================================================ However, the server will accept commands ending with just \n, but not just \r. If you are looking to save as much bandwidth as possible, go ahead and use \n, and there shouldn't be any problems unless MSN changes their server code. Inside the payloads of payload commands, newlines are treated slightly differently. Their behaviour is discussed on the Payload Commands page. ================================================================================================ 当然，服务器也会接受只以 \n 结尾的命令，但不会接受只以 \r 结尾的命令。如果你希望尽可能多的节省带宽， 只使用 \n（用 \n 代替 \r\n）, 这不会造成任何问题，除非 MSN 改变他们的服务器编码。 在数据携带命令携带的数据中，[新行]被进行了些微的处理而有所不同。他们的特性我们将在 数据携带命令一节中进行讨论。 ================================================================================================ Parameters Parameters exist to provide additional information with each command. Most commands have at least one parameter. Each parameter is separated by a space. Some commands also have a transaction ID immediately after the command and before the parameters. For the purposes of this documentation, the TrID does not count as a parameter. The following command has one parameter: <<< FLN example@passport.com\r\n FLN is the command, example@passport.com is the parameter, and \r\n is the newline. It is possible to send certain commands with multiple spaces between parameters, tabs instead of spaces, tabs mixed with spaces, and trailing spaces and tabs. This has not been thoroughly tested. In any case, the server always sends one space in between parameters and no trailing whitespace (with the exception of the standard newlines). ================================================================================================ 参数 参数为每个命令提供附加信息。多数命令至少有一个参数。参数之间用空格分割，一些命令还有一个 传输号 紧跟在命令此后面而在参数前面。 在这篇文档当中，TrID(transaction ID 传输号)不被算作一个参数。 下面的命令带有一个参数： <<< FLN example@passport.com\r\n FLN 是命令词， example@passport.com 是参数。 \r\n 是[新行]符号。你可以用空格或者 tab 、空格与 tab 混合使用、 trailing space 与 tab 来 分隔多个参数的形式来传递多个参数。 服务器有时会发送 一个空白在参数和 trailing whitespace 之间（标准的[新行]例外） ================================================================================================= Transaction IDs (TrIDs) Transaction IDs, abbreviated as TrIDs, are used to match a client command with a server response. Commands sent by the client are required to contain a TrID, and commands from the server sent in direct response to that command will contain the same TrID (with the exceptions noted above). In most cases, there will be just one response to each client command. ================================================================================================= 传输编号(TrIDs) Transaction IDs(传输编号), 简记为 TrIDs,用与客户命令和服务器回复的匹配。客户端发送的命令必须包含一个 TrID(特殊注明的除外)。 多数情况下，每个客户命令只有一个回复。 ================================================================================================= Every TrID is a number between 0 and 4294967295 (2 to the power 32, minus 1). Even though completely legal, it is advisable not to use 0 as a TrID because some asynchronous commands use 0 as the TrID and it may cause confusion. The TrID always comes right after the three letter (or three digit, in the case of errors) command code, and they are separated by a space. If the command has parameters, the parameters will follow the TrID and they will be separated by another space. Otherwise, there will be no space after the TrID. Below is an example of sending the VER command with a TrID of 15 and receiving the response from the server. >>> VER 15 MSNP8 FOO CVR0 BAR\r\n <<< VER 15 MSNP8 CVR0\r\n ================================================================================================= 每一个TrID 都在 0 和 4294967295 之间（2 的32次方减一）。尽管非常符合规则但是不用 0 作为 TrID 是非常明智的，因为很多异步命令 用 0 作为 TrID 而且它容易引起混淆。 TrID 通常 在 三个字符（对于 错误提示命令 是 三个数字）组成的命令词的右边，而且他们和命令 词之间由空格分割。如果命令有参数，参数会在 TrID 的后边，参数与TrID 只见也由空格分割。如果没有参数，TrID 后面没有空格。 下面是一个发送和接收的示例，命令词是 VER ,TrID 是 5 >>> VER 15 MSNP8 FOO CVR0 BAR\r\n <<< VER 15 MSNP8 CVR0\r\n ================================================================================================= The server does not make any changes based on your TrID; it only responds using the same TrID you sent it. If your TrID is greater than 4294967295, the server will behave unpredictably. If you send a TrID that is not a positive integer, the server will immediately disconnect you. If you repeat the same TrID in multiple commands, the server will not do anything differently, but it will be more difficult for the client to track responses. ================================================================================================= 服务器不会在你的TrID 基础上作任何改变，它的回复中只会原样使用你发送给它的 TrID. 如果你的 TrID 大于 4294967295，服务器会 出现不可预测的错误，如果你传给服务器的 TrID 不是正整数 ，服务器会立刻结束连接。如果你在多个命令中重复使用相同的 TrID, 服务器不会做任何不同的事情，但是客户端将很难跟踪回复。 ================================================================================================= The official client always increments the TrID by one after sending each command. As long as you stay in the correct range and don't repeat TrIDs, it doesn't make much of a difference. Keeping the number low will save a small amount of bandwidth - probably not more than 5% of your total bandwidth for the session. Using random numbers will increase your processor use and not increase your security at all. ================================================================================================= 官方的客户端通常在每发送一个命令之后另 TrID 加 1 ，但你在适当的范围内而且不使用重复的 TrID, 不会造成很大的不同。保持你的 TrID 比较小 会节省一部分带宽---不会多于总的session 带宽的 5% ，用随机数会增加你的 CPU 的负担 而且不会为你的安全带来任何帮助。 ================================================================================================= Error Commands An error is a special type of command sent by the server in response to a client command which it couldn't obey or couldn't understand. Errors follow all of the normal rules of commands, except that the three-character command codes are always three-digit numbers. A detailed list of errors can be found in the Error List page. ================================================================================================= 错误提示命令 错误是服务器发送的一种特殊的命令，作为对客户端得不能执行或不能解释的命令的答复。错误提示命令除了命令词是由三个数字组成外， 遵循所有的标准命令格式。详细的错误列表可以从 错误列表页中找到。 ================================================================================================= If something goes wrong, an error will be sent in place of the expected command. For example, if a client sends an ADD command, it should normally receive another ADD command back from the server. However, if the client specifies a nonexistent account name as a parameter, the server will respond with error 201 instead of the ADD command. ================================================================================================= 一旦出现错误，一个错误提示命令会代替预期的命令。例如，如果客户端发送了一个 ADD 命令，通常他会从服务器收到另一个 ADD 命令。 但是如果客户端指定了一个不存在的 账户名 作为参数，服务端会返回 201 错误代替原来的 ADD 命令。 ================================================================================================= Clients never send error codes to the server. The server never sends error codes that aren't in response to any particular client command. ================================================================================================= 客户端从不发送错误提示命令到服务端。服务器不会发送特别针对客户命令的错附代码。 ================================================================================================= Error Syntax The syntax of an error command is very simple. The command code is just a three digit number, and it specifies the TrID of the client command it is in response to. There are no additional parameters. ================================================================================================= 错误提示命令的语法 错误提示命令的语法非常简单，命令词只有三个数字组成，并且指定其所对应的客户端命令的 TeID，除此没有别的参数。 (格是：命令词 TrID) ================================================================================================= However, according to the original IETF draft, errors can be sent with additional parameters. I have never seen anything like that sent, but just in case, every client should be prepared to receive parameters without crashing. ================================================================================================= 但是，根据原先的IETF 草稿，错误可以被另外的参数送. 我从未看见象那样的任何东西被传送，但是以防万一，每个客户端应为此做好准备。 ================================================================================================= Payload Commands Most messages are just one line of data, ending with a newline. Payload commands have a chunk of data following the newline. The length of this data (in bytes) is specified in the last parameter of the command. The payload commands in MSNP8 are QRY, PAG, NOT and (most importantly) MSG. Here is an example of a payload command: ================================================================================================= 数据携带命令 大多数消息只是一行以[新行]符号结尾的数据，数据携带命令则在[新行]符号后面跟着一大块数据。命令的最后一个参数 指明这块数据的大小（以字节为单位）。在MSNP8里的数据携带命令是QRY, PAG, NOT and (most importantly) MSG. 这里有一个数据携带命令的例子。 ================================================================================================= >>> QRY 1049 msmsgs@msnmsgr.com 32\r\n 8f2f5a91b72102cd28355e9fc9000d6e (no newline) See the payload commands page for more details. 你可以从 数据携带命令一页中看到更多详情。 ================================================================================================= Asynchronous Commands Asynchronous commands are commands sent by the server, but not in response to any command sent by the client. Because of their nature, they have no assigned TrID. Some asynchronous commands have no TrID, and just have the parameter immediately after the command code. Some of these commands are NLN, FLN, and BPR. ================================================================================================= 异步命令 异步命令是服务器发出的，但不是为了响应任何的客户命令。因为它们本身没有 分配的TrID.一些异步命令没有 TrID,只有一个参数 紧跟在命令词的后边。一些这样的命令(异步命令)是 NLN, FLN, 和 BPR 。 ================================================================================================= Other asynchronous commands always have a TrID of zero. Some of these commands are ADD and REM. The reason that these commands still have TrIDs is because they are also used as a client command with a server response. Only in special cases, like where a principal is added to the reverse list, does the server send the command as an asynchronous command with a TrID of zero. ================================================================================================= 另外一些异步命令带有一个等于零的 TrID,这样的命令比如：ADD 和 REM . 这些命令仍然有TrIDs的原因因为他们也被作为服务器对客户命令的反应。只有在特殊的情况下，比如一个主要的账户被加到反面目录 （站长理解为：黑名单，拒绝列表），服务器会发送一个带有值为 0 的TrID 的 异步命令。 ================================================================================================= Asynchronous commands can be sent at any legal place in the protocol - even between a block of related replies such as in between two ILNs. ================================================================================================= 异步命令可以在任何符合协议的地方传颂--即使是在一块有关联的答复之间，不如在两个 ILNs 之间。 ================================================================================================= Command Order Usually, replies to commands will come in the order that you sent the commands. But this is not always the case. Sometimes, you may send commands in the order of 1, 2, 3, and the server will respond to them in the order of 2, 3, 1. This is why TrIDs are very useful. ================================================================================================= 命令顺序 通常回复命令是按照你发送的命令的顺来的。但并不总是这样。有时，你按照 1，2，3 的顺序发送命令，但是服务器会按照 2，3，1 的顺序答复，此时， TrID 就很有用了。 ================================================================================================= Some commands have multiple responses from the server. These responses contain the same TrID as the original command (except SYN responses). A command that can have multiple responses is CHG. ================================================================================================= ================================================================================================= Unfortunately, there are no real rules on the order of unrelated commands. For example, a client can receive an ILN in the middle of a list of BPRs. If you examine the server behaviour enough, you can start to make rules, but Microsoft often changes the server implementation and you would have to start all over. It's best for a client to just expect anything to happen. ================================================================================================= ************************************************************** What syntax is used in this document? Raw Protocol This site includes many examples of dialogues between client and server, and between two clients. Client/server dialogues are always described from the point-of-view of the client. Client/client dialogues are described from the point-of-view of one or other client. A bold monospace font is always used for these dialogues. Text sent from the (local) client is always blue. Text sent from the server (or the other client) is always green. Information about the dialogue is always bluish green. A block of text sent by the (local) client is always preceded by >>> followed by a space. A block of text sent by the server (or the other client) is always preceded by <<< followed by a space. Other information is always preceded by and a space. At the end of a line of text sent by the server or the client, there are often newline characters. In most cases, it is a carriage return followed by a linefeed which is expressed as the light-grey \r\n. Note that this is two bytes, and is not the literal characters "backslash R backslash N". Special attention should be paid to newlines, as the simplest (and most common) programming mistakes in the Messenger protocol involve putting a newline where there shouldn't be one, forgetting to put one where there should be one, or mis-counting the size of a newline. When short examples of protocol are found in paragraphs, such as the name of a command or an example of a nickname, they are usually found in a bold monospace red font. ================================================================================ 文档中用到的语法的解释： 数据字典 这个网站的网页中包含很多客户端与服务端，客户端与客户端对话的例子。客户端和服务端的对话通常是从客户端的观点 （站在客户端的立场上） 出发的。客户端与客户端的通信是从其中一个客户端的观点出发的。这些对话的一般用粗体字标示。从（本地）客户端发出的文本通常 是蓝色的。 服务器（或者另一个客户端）发出的文本通常是绿色的。有关对话的新系通常是蓝绿色的。 （本地）客户端发送的一块文本通常跟在 >>>[空格] 之后。服务端或另一客户端发送的一段文本通常跟在 <<<[空格] 后面。 其他信息通常跟在 [空格] 后面。 在服务器或另一客户端发送的一行文本的最后通常跟着一个[新行符号]，通常情况下他是用浅灰色\r\n 表示的一个回车后、换行。 注意，这是两个字节并不表面上的 “反斜线 R 反斜线 N”。特别注意，一定要加新行符号，最简单的（也是最常见的） Messenger 协议编成错误 都是因为在不该加的地方加了一个[新行]符号，再该加[新行]的地方却忘记了加，或者是算错了[新行]所占的位数。 章节中的关于协议的短的例子，比如， 命令的名字 、昵称 ，他们通常是红色的粗体字。 **************************************************************