docs/soulseek_protocol.html

   1 <html><head><title>SoulSeek Protocol Documentation</title></head>
   2 <link rel="stylesheet" type="text/css" href="styles.css">
   3 <body>
   4 <h1>SoulSeek Protocol Documentation</h1>
   5 <div align=center>
   6 <h3>Table of Contents</h3>
   7 <table border=0 cellspacing=0 cellpadding=0><tr><td>
   8 <a href="#versionHistory">Version History</a><br>
   9 <a href="#introduction">Introduction</a><br>
  10 <a href="#overview">Overview</a><br>
  11 <a href="#constants">Constants</a><br>
  12 <a href="#messages">Messages</a><br>
  13 <a href="#serverMessages">Server Messages</a><br>
  14 <a href="#peerMessages">Peer Messages</a><br>
  15 <a href="#messageSequences">Message Sequences</a><br>
  16 </td></tr></table>
  17 </div><br>
  18
  19 <a name="versionHistory"></a><h2>Version History</h2>
  20 2003-01-26: Added peer messages and login sequence, had revelation about reusing existing peer socket from search result for file request, <a href="http://sourceforge.net/users/brienigma/">BriEnigma</a><br>
  21 2003-01-20: Initial revision, <a href="http://sourceforge.net/users/brienigma/">BriEnigma</a><br>
  22 CVS version ID: $Id$<br>
  23 Mental Note: When updating this document, remember to upload the
  24 latest version to the <a href="http://sourceforge.net/docman/?group_id=69129">SourceForge
  25 project documentation web page</a>.
  26
  27 <a name="introduction"></a><h2>Introduction</h2>
  28 <p>
  29 The SoulSeek protocol is not officially documented anywhere.  This document is the result
  30 of effort by members of the <a href="http://sourceforge.net/projects/soleseek/">SoleSeek</a>
  31 project team.  It was pieced together by examining the
  32 <a href="http://www.sensi.org/~ak/pyslsk/">Python SoulSeek</a> source code, as well as
  33 sniffing network packets.
  34 (Hey, Nir!  Please don't sue us inder the
  35 <a href="http://www.eff.org/IP/DMCA/">DMCA</a> for reverse engineering the
  36 protocol!)
  37 This document should not be considered the official
  38 specification.  It is our best guess at how the protocol works.
  39 </p>
  40
  41 <a name="overview"></a><h2>Overview</h2>
  42 <p>
  43 The SoulSeek protocol consists of a finite number of messages.
  44 Some of these messages are used for communicating between the
  45 client and server.  Others are used for communications between
  46 a client and a peer (another client).  All of these messages
  47 (with the exception of a couple of peer messages TODO:...are
  48 PeerInit and PierceFW the only exceptions?...) follow a
  49 standard format.
  50 </p>
  51
  52 <p>
  53 There are a few datatypes that the message blocks use:<br>
  54 (TODO: endian-ness? I always get mixed up.)<br><br>
  55 <table border=0 cellspacing=2 cellpadding=1>
  56 <tr><td valign=top class=standout>Integer</td>     <td valign=top class=standout>4 bytes, network byte ordering</td></tr>
  57 <tr><td valign=top class=standout>Byte</td>        <td valign=top class=standout>1 byte</td></tr>
  58 <tr><td valign=top class=standout>String</td>      <td valign=top class=standout>an integer (4 bytes) that specifies the length of the string, followed by the string data as 8-bit characters.  The string is not null-terminated.</td></tr>
  59 <tr><td valign=top class=standout>TODO:</td>       <td valign=top class=standout>are other datatypes used?</td>
  60 </table>
  61 </p>
  62
  63 <p>
  64 The standard message blocks start with an integer.  This integer defines
  65 the size of the message payload--everything contained in the message, but
  66 not including the 4-bytes length.  The payload starts with an integer
  67 that we shall call the <b>message code</b> that describes what type of
  68 message this is.  The datatype and meaning of the remaining payload data
  69 is dependant on the message code.  For example, the following is a very
  70 simple message, the Login message from the client to the server:<br>
  71 <div align=center><table border=1 cellspacing=0 cellpadding=1>
  72 <tr>
  73     <td style="background-color:#ffcccc;">Message Length</td>
  74     <td style="background-color:#ccffcc;" colspan=18>Message Payload</td>
  75 </tr>
  76 <tr>
  77     <td nowrap style="color:#ff0000;">4-byte-integer: 30</td>
  78     <td nowrap style="color:#009900;">4-byte-integer: 1</td>
  79     <td nowrap style="color:#009900;">4-byte-integer: 8</td>
  80     <td nowrap style="color:#009900;">J</td>
  81     <td nowrap style="color:#009900;">o</td>
  82     <td nowrap style="color:#009900;">h</td>
  83     <td nowrap style="color:#009900;">n</td>
  84     <td nowrap style="color:#009900;">G</td>
  85     <td nowrap style="color:#009900;">a</td>
  86     <td nowrap style="color:#009900;">l</td>
  87     <td nowrap style="color:#009900;">t</td>
  88     <td nowrap style="color:#009900;">4-byte-integer: 6</td>
  89     <td nowrap style="color:#009900;">s</td>
  90     <td nowrap style="color:#009900;">e</td>
  91     <td nowrap style="color:#009900;">c</td>
  92     <td nowrap style="color:#009900;">r</td>
  93     <td nowrap style="color:#009900;">e</td>
  94     <td nowrap style="color:#009900;">t</td>
  95     <td nowrap style="color:#009900;">4-byte-integer: 200</td>
  96 </tr>
  97 <tr>
  98     <td style="color:#ff0000;"></td>
  99     <td style="color:#009900;">Message Code 1 == "Login" (4 bytes)</td>
 100     <td style="color:#009900;" colspan=9>String, length 8 (12 bytes)</td>
 101     <td style="color:#009900;" colspan=7>String, length 6 (10 bytes)</td>
 102     <td style="color:#009900;">Version (4 bytes)</td>
 103 </tr>
 104 </table></div>
 105 This sends a message to the server with message code 1.  Since
 106 message code 1 is the Login message, the server knows to expect
 107 two strings and an integer.  The fist string, we can see is
 108 of length 8 and contains the letters "JohnGalt".  The second
 109 string is of length 6 and contains the letters "secret".
 110 The remaining integer is the number 200.
 111 </p>
 112
 113 <p>
 114 It is worth noting that messages with the same code may have
 115 different payloads, depending on the direction of the message:
 116 client-to-server (generally, a request) or server-to-client
 117 (generally, a response).
 118 In the above example, the message is a Login message
 119 from the client to the server.  The server responds to the
 120 client with message that also has the message code 1 ("Login"),
 121 but has a different payload.  Login messages originating at
 122 the server (we can think of it as a Login response message)
 123 contain a byte (1/0 for success/fail) followed by a string
 124 (a message about the results of the login or a server greeting).
 125 </p>
 126
 127
 128 <a name="constants"></a><h2>Constants</h2>
 129 <p>
 130 The SoulSeek protocol makes use of several constants:
 131 </p>
 132 <table border=0 cellspacing=2 cellpadding=2>
 133 <tr><td class=standout colspan=2 align=center><b>Status Codes</b></td></tr>
 134 <tr><td class=standout>-1</td>          <td class=standout>Unknown</td></tr>
 135 <tr><td class=standout>0</td>           <td class=standout>Offline</td></tr>
 136 <tr><td class=standout>1</td>           <td class=standout>Away</td></tr>
 137 <tr><td class=standout>2</td>           <td class=standout>Online</td></tr>
 138 <tr><td class=standout colspan=2 align=center><b>Transfer Direction</b></td></tr>
 139 <tr><td class=standout>0</td>           <td class=standout>Download</td></tr>
 140 <tr><td class=standout>1</td>           <td class=standout>Upload</td></tr>
 141 <tr><td class=standout colspan=2 align=center><b>TODO: There are probably more...</b></td></tr>
 142 </table>
 143
 144 <!-- =========================================================== -->
 145 <!-- =========================================================== -->
 146 <!-- =========================================================== -->
 147
 148 <a name="messages"></a><h2>Messages</h2>
 149
 150 <b>Jump directly to a server message:</b>
 151 <a href="#S1">Login:1</a>
 152 <a href="#S2">SetWaitPort:2</a>
 153 <a href="#S3">GetPeerAddress:3</a>
 154 <a href="#S5">AddUser:5</a>
 155 <a href="#S7">GetUserStatus:7</a>
 156 <a href="#S13">SayChatroom:13</a>
 157 <a href="#S14">JoinRoom:14</a>
 158 <a href="#S15">LeaveRoom:15</a>
 159 <a href="#S16">UserJoinedRoom:16</a>
 160 <a href="#S17">UserLeftRoom:17</a>
 161 <a href="#S18">ConnectToPeer:18</a>
 162 <a href="#S22">MessageUser:22</a>
 163 <a href="#S23">MessageAcked:23</a>
 164 <a href="#S26">FileSearch:26</a>
 165 <a href="#S28">SetStatus:28</a>
 166 <a href="#S35">SharedFoldersFiles:35</a>
 167 <a href="#S36">GetUserStats:36</a>
 168 <a href="#S40">QueuedDownloads:40</a>
 169 <a href="#S60">PlaceInLineResponse:60</a>
 170 <a href="#S62">RoomAdded:62</a>
 171 <a href="#S63">RoomRemoved:63</a>
 172 <a href="#S64">RoomList:64</a>
 173 <a href="#S65">ExactFileSearch:65</a>
 174 <a href="#S66">AdminMessage:66</a>
 175 <a href="#S67">GlobalUserList:67</a>
 176 <a href="#S68">TunneledMessage:68</a>
 177 <a href="#S69">PrivilegedUsers:69</a>
 178 <a href="#S91">AddToPrivileged:91</a>
 179 <a href="#S92">CheckPrivileges:92</a>
 180 <a href="#S1001">CantConnectToPeer:1001</a>
 181 <br>
 182 <b>Jump directly to a peer message:</b>
 183 <a href="#Pinit">PeerInit</a>
 184 <a href="#Pfw">PierceFW</a>
 185 <a href="#P4">GetSharedFileList:4</a>
 186 <a href="#P5">SharedFileList:5</a>
 187 <a href="#P9">FileSearchResult:9</a>
 188 <a href="#P15">UserInfoRequest:15</a>
 189 <a href="#P16">UserInfoReply:16</a>
 190 <a href="#P36">FolderContentsRequest:36</a>
 191 <a href="#P37">FolderContentsResponse:37</a>
 192 <a href="#P40">TransferRequest:40</a>
 193 <a href="#P41">TransferResponse:41</a>
 194 <a href="#P42">PlaceholdUpload:42</a>
 195 <a href="#P43">QueueUpload:43</a>
 196 <a href="#P44">PlaceInQueue:44</a>
 197 <a href="#P46">UploadFailed:46</a>
 198 <a href="#P50">QueueFailed:50</a>
 199 <a href="#P51">PlaceInQueueRequest:51</a>
 200 <br><br>
 201
 202 <!-- =========================================================== -->
 203 <!-- =========================================================== -->
 204 <!-- =========================================================== -->
 205
 206 <a name="serverMessages"></a><h2>Server Messages</h2>
 207
 208 <a name="S1"></a><h3>Login:1</h3>
 209 Client-to-Server (attempt to login)<br>
 210 <table border=0 cellspacing=2 cellpadding=2>
 211 <tr><td class=standout>integer</td><td class=standout>1 (Message Code)</td></tr>
 212 <tr><td class=standout>string</td><td class=standout>Username</td></tr>
 213 <tr><td class=standout>string</td><td class=standout>Password</td></tr>
 214 <tr><td class=standout>integer</td><td class=standout>Version</td></tr>
 215 </table><br>
 216
 217 Server-to-Client (login success/fail)<br>
 218 <table border=0 cellspacing=2 cellpadding=2>
 219 <tr><td class=standout>integer</td><td class=standout>1 (Message Code)</td></tr>
 220 <tr><td class=standout>byte</td><td class=standout>success (0=fail, 1=success)</td></tr>
 221 <tr><td class=standout>string</td><td class=standout>Login message (error message or greeting message)</td></tr>
 222 </table><br>
 223
 224 <a name="S2"></a><h3>SetWaitPort:2</h3>
 225 Client-to-Server<br>
 226 This is sent to the server to tell it what port we are listening on.<br>
 227 <table border=0 cellspacing=2 cellpadding=2>
 228 <tr><td class=standout>integer</td><td class=standout>2 (Message Code)</td></tr>
 229 <tr><td class=standout>integer</td><td class=standout>port number (generally 2234)</td></tr>
 230 </table><br>
 231
 232 Server-to-Client<br>
 233 It is believed that SetWaitPort messages are not sent from the server to the client.<br>
 234
 235 <a name="S3"></a><h3>GetPeerAddress:3</h3>
 236 Client-to-Server<br>
 237 This is sent to the server to ask for a peer's address (IP address and port), given
 238 the peer's username.<br>
 239 <table border=0 cellspacing=2 cellpadding=2>
 240 <tr><td class=standout>integer</td><td class=standout>3 (Message Code)</td></tr>
 241 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 242 </table><br>
 243
 244 Server-to-Client<br>
 245 This is the response from the server.<br>
 246 <table border=0 cellspacing=2 cellpadding=2>
 247 <tr><td class=standout>integer</td><td class=standout>3 (Message Code)</td></tr>
 248 <tr><td class=standout>string</td><td class=standout>username this address belongs to</td></tr>
 249 <tr><td class=standout>integer</td><td class=standout>IP address</td></tr>
 250 <tr><td class=standout>integer</td><td class=standout>port number</td></tr>
 251 </table><br>
 252
 253 <a name="S5"></a><h3>AddUser:5</h3>
 254 Client-to-Server<br>
 255 This message is sent when you want to start monitoring the online status of
 256 a user.  Once we start "watching" a user by sending this message, the
 257 server will send (TODO: is the message AddUser or GetUserStatus)
 258 messages to us whenever the user changes status (away, back, offline, etc).<br>
 259 Note: There also seems to be a GetPeerAddress response message returned
 260 automatically, along with the AddUser response message--even though the
 261 GetPeerAddress request was never made.  Can anyone confirm this?<br>
 262 <table border=0 cellspacing=2 cellpadding=2>
 263 <tr><td class=standout>integer</td><td class=standout>5 (Message Code)</td></tr>
 264 <tr><td class=standout>string</td><td class=standout>username to start watching</td></tr>
 265 </table><br>
 266
 267 Server-to-Client<br>
 268 <table border=0 cellspacing=2 cellpadding=2>
 269 <tr><td class=standout>integer</td><td class=standout>5 (Message Code)</td></tr>
 270 <tr><td class=standout>string</td><td class=standout>username being watching</td></tr>
 271 <tr><td class=standout>byte</td><td class=standout>whether the user exists</td></tr>
 272 </table><br>
 273
 274 <a name="S7"></a><h3>GetUserStatus:7</h3>
 275 Client-to-Server<br>
 276 This message is used to request a user's current status.<br>
 277 <table border=0 cellspacing=2 cellpadding=2>
 278 <tr><td class=standout>integer</td><td class=standout>7 (Message Code)</td></tr>
 279 <tr><td class=standout>string</td><td class=standout>username to get status of</td></tr>
 280 </table><br>
 281
 282 Server-to-client<br>
 283 This message is used by the server to report back to us a user's current status.
 284 <table border=0 cellspacing=2 cellpadding=2>
 285 <tr><td class=standout>integer</td><td class=standout>7 (Message Code)</td></tr>
 286 <tr><td class=standout>string</td><td class=standout>username this status applies to</td></tr>
 287 <tr><td class=standout>integer</td><td class=standout>status code, <a href="#constants">see above</a></td></tr>
 288 </table><br>
 289
 290 <a name="S13"></a><h3>SayChatroom:13</h3>
 291 Client-to-Server<br>
 292 This message is sent to say something in a chatroom.<br>
 293 <table border=0 cellspacing=2 cellpadding=2>
 294 <tr><td class=standout>integer</td><td class=standout>13 (Message Code)</td></tr>
 295 <tr><td class=standout>string</td><td class=standout>room</td></tr>
 296 <tr><td class=standout>string</td><td class=standout>message</td></tr>
 297 </table><br>
 298
 299 Server-to-Client<br>
 300 Somebody said something in a chatroom we are in.<br>
 301 <table border=0 cellspacing=2 cellpadding=2>
 302 <tr><td class=standout>integer</td><td class=standout>13 (Message Code)</td></tr>
 303 <tr><td class=standout>string</td><td class=standout>room</td></tr>
 304 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 305 <tr><td class=standout>string</td><td class=standout>message</td></tr>
 306 </table><br>
 307
 308 <a name="S14"></a><h3>JoinRoom:14</h3>
 309 Client-to-Server<br>
 310 We would like to join a chatroom.<br>
 311 <table border=0 cellspacing=2 cellpadding=2>
 312 <tr><td class=standout>integer</td><td class=standout>14 (Message Code)</td></tr>
 313 <tr><td class=standout>string</td><td class=standout>room</td></tr>
 314 </table><br>
 315
 316 Server-to-Client<br>
 317 We have joined the room.  Here is a list of all the people in the room.  (This
 318 could very easily be a giant set of data!)<br>
 319 <table border=0 cellspacing=2 cellpadding=2>
 320 <tr><td class=standout>integer</td><td class=standout>14 (Message Code)</td></tr>
 321 <tr><td class=standout>string</td><td class=standout>room</td></tr>
 322 <tr><td class=standout>integer</td><td class=standout>number of users in this room</td></tr>
 323 <tr><td class=standout>string</td><td class=standout>username #1</td></tr>
 324 <tr><td class=standout>string</td><td class=standout>username #2</td></tr>
 325 <tr><td colspan=2 align=center>:<br>:</td></tr>
 326 <tr><td class=standout>string</td><td class=standout>username #n</td></tr>
 327 <tr><td class=standout>integer</td><td class=standout>number of status code intgers (should be the same as number of users in the above field)</td></tr>
 328 <tr><td class=standout>integer</td><td class=standout>status code of username #1</td></tr>
 329 <tr><td class=standout>integer</td><td class=standout>status code of username #2</td></tr>
 330 <tr><td colspan=2 align=center>:<br>:</td></tr>
 331 <tr><td class=standout>integer</td><td class=standout>status code of username #n</td></tr>
 332 <tr><td class=standout>integer</td><td class=standout>number of statistics records (should be the same as number of users in the above field)</td></tr>
 333 <tr><td class=standout>integer</td><td class=standout>stats record 1: avgspeed of username #1</td></tr>
 334 <tr><td class=standout>integer</td><td class=standout>stats record 1: downloadnum of username #1</td></tr>
 335 <tr><td class=standout>integer</td><td class=standout>stats record 1: something of username #1</td></tr>
 336 <tr><td class=standout>integer</td><td class=standout>stats record 1: files of username #1</td></tr>
 337 <tr><td class=standout>integer</td><td class=standout>stats record 1: dirs of username #1</td></tr>
 338 <tr><td class=standout>integer</td><td class=standout>stats record 2: avgspeed of username #2</td></tr>
 339 <tr><td class=standout>integer</td><td class=standout>stats record 2: downloadnum of username #2</td></tr>
 340 <tr><td class=standout>integer</td><td class=standout>stats record 2: something of username #2</td></tr>
 341 <tr><td class=standout>integer</td><td class=standout>stats record 2: files of username #2</td></tr>
 342 <tr><td class=standout>integer</td><td class=standout>stats record 2: dirs of username #2</td></tr>
 343 <tr><td colspan=2 align=center>:<br>:</td></tr>
 344 <tr><td class=standout>integer</td><td class=standout>stats record n: avgspeed of username #n</td></tr>
 345 <tr><td class=standout>integer</td><td class=standout>stats record n: downloadnum of username #n</td></tr>
 346 <tr><td class=standout>integer</td><td class=standout>stats record n: something of username #n</td></tr>
 347 <tr><td class=standout>integer</td><td class=standout>stats record n: files of username #n</td></tr>
 348 <tr><td class=standout>integer</td><td class=standout>stats record n: dirs of username #n</td></tr>
 349 <tr><td class=standout>integer</td><td class=standout>number of slotsfull records</td></tr>
 350 <tr><td class=standout>integer</td><td class=standout>slotsfull field of username #1</td></tr>
 351 <tr><td class=standout>integer</td><td class=standout>slotsfull field of username #2</td></tr>
 352 <tr><td colspan=2 align=center>:<br>:</td></tr>
 353 <tr><td class=standout>integer</td><td class=standout>slotsfull field of username #n</td></tr>
 354 </table><br>
 355
 356 <a name="S15"></a><h3>LeaveRoom:15</h3>
 357 Client-to-Server<br>
 358 We would like to leave a chatroom.<br>
 359 <table border=0 cellspacing=2 cellpadding=2>
 360 <tr><td class=standout>integer</td><td class=standout>15 (Message Code)</td></tr>
 361 <tr><td class=standout>string</td><td class=standout>room</td></tr>
 362 </table><br>
 363
 364 Server-to-Client<br>
 365 Server tells us we have left the room.  Note that, in theory, this could
 366 happen at any time--it may not necessarily be a response to a LeaveRoom
 367 message.  It is entirely possible that the server could send this to kick
 368 you out of a room (although this author has never seen it happen).
 369 <br>
 370 <table border=0 cellspacing=2 cellpadding=2>
 371 <tr><td class=standout>integer</td><td class=standout>15 (Message Code)</td></tr>
 372 <tr><td class=standout>string</td><td class=standout>room</td></tr>
 373 </table><br>
 374
 375 <a name="S16"></a><h3>UserJoinedRoom:16</h3>
 376 Client-to-Server<br>
 377 This message is not sent from the client.<br><br>
 378
 379 Server-to-Client<br>
 380 User "x" has entered chat room "y".<br>
 381 <table border=0 cellspacing=2 cellpadding=2>
 382 <tr><td class=standout>integer</td><td class=standout>16 (Message Code)</td></tr>
 383 <tr><td class=standout>string</td><td class=standout>room</td></tr>
 384 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 385 </table><br>
 386
 387 <a name="S17"></a><h3>UserLeftRoom:17</h3>
 388 Client-to-Server<br>
 389 This message is not sent from the client.<br><br>
 390
 391 Server-to-Client<br>
 392 User "x" has left chat room "y".<br>
 393 <table border=0 cellspacing=2 cellpadding=2>
 394 <tr><td class=standout>integer</td><td class=standout>17 (Message Code)</td></tr>
 395 <tr><td class=standout>string</td><td class=standout>room</td></tr>
 396 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 397 </table><br>
 398
 399 <a name="S18"></a><h3>ConnectToPeer:18</h3>
 400 Client-to-Server
 401 If we cannot establish a direct connection to a user (for example,
 402 they are behind a firewall), we send this message to the server, which
 403 will tell the peer to connect back to us.<br>
 404 <table border=0 cellspacing=2 cellpadding=2>
 405 <tr><td class=standout>integer</td><td class=standout>18 (Message Code)</td></tr>
 406 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 407 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 408 <tr><td class=standout>string</td><td class=standout>type: "P"/"F" (see PeerInit)</td></tr>
 409 </table><br>
 410
 411 Server-to-Client<br>
 412 If someone cannot establish a connection with us (for instance, we are behind
 413 a firewall), the server sends this message to us.  We then attempt to
 414 establish a direct connection to the peer.<br>
 415 <table border=0 cellspacing=2 cellpadding=2>
 416 <tr><td class=standout>integer</td><td class=standout>18 (Message Code)</td></tr>
 417 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 418 <tr><td class=standout>string</td><td class=standout>type: "P"/"F" (see PeerInit)</td></tr>
 419 <tr><td class=standout>integer</td><td class=standout>ip address</td></tr>
 420 <tr><td class=standout>integer</td><td class=standout>port</td></tr>
 421 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 422 </table><br>
 423
 424 <a name="S22"></a><h3>MessageUser:22</h3>
 425 Client-to-Server<br>
 426 Send a private chat message to a user<br>
 427 <table border=0 cellspacing=2 cellpadding=2>
 428 <tr><td class=standout>integer</td><td class=standout>22 (Message Code)</td></tr>
 429 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 430 <tr><td class=standout>string</td><td class=standout>message</td></tr>
 431 </table><br>
 432
 433 Server-to-Client<br>
 434 Somebody sent us a private chat message<br>
 435 <table border=0 cellspacing=2 cellpadding=2>
 436 <tr><td class=standout>integer</td><td class=standout>22 (Message Code)</td></tr>
 437 <tr><td class=standout>integer</td><td class=standout>message ID</td></tr>
 438 <tr><td class=standout>integer</td><td class=standout>timestamp</td></tr>
 439 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 440 <tr><td class=standout>string</td><td class=standout>message</td></tr>
 441 </table><br>
 442
 443 <a name="S23"></a><h3>MessageAcked:23</h3>
 444 Client-to-Server<br>
 445 Confirmation of receiving a private chat message.  If we do not send it,
 446 the server will keep sending the chat phrase to us.<br>
 447 <table border=0 cellspacing=2 cellpadding=2>
 448 <tr><td class=standout>integer</td><td class=standout>23 (Message Code)</td></tr>
 449 <tr><td class=standout>integer</td><td class=standout>message ID</td></tr>
 450 </table><br>
 451
 452 Server-to-Client<br>
 453 This message is not sent from the server to the client.<br>
 454
 455 <a name="S26"></a><h3>FileSearch:26</h3>
 456 Client-to-Server<br>
 457 We send this to the server when we want to search for something.<br>
 458 <table border=0 cellspacing=2 cellpadding=2>
 459 <tr><td class=standout>integer</td><td class=standout>26 (Message Code)</td></tr>
 460 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 461 <tr><td class=standout>string</td><td class=standout>search text</td></tr>
 462 </table><br>
 463
 464 Server-to-Client
 465 The server sends this to tell us someone is searching for something.<br>
 466 <table border=0 cellspacing=2 cellpadding=2>
 467 <tr><td class=standout>integer</td><td class=standout>26 (Message Code)</td></tr>
 468 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 469 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 470 <tr><td class=standout>string</td><td class=standout>search text</td></tr>
 471 </table><br>
 472
 473 <a name="S28"></a><h3>SetStatus:28</h3>
 474 Client-to-Server<br>
 475 Change my away/online status.<br>
 476 <table border=0 cellspacing=2 cellpadding=2>
 477 <tr><td class=standout>integer</td><td class=standout>28 (Message Code)</td></tr>
 478 <tr><td class=standout>integer</td><td class=standout>new status, <a href="#constants">see above</a></td></tr>
 479 </table><br>
 480
 481 Server-to-Client<br>
 482 This message is not sent from the server to the client.
 483
 484 <a name="S35"></a><h3>SharedFoldersFiles:35</h3>
 485 Server-to-Client<br>
 486 We send this to the server to tell it how many files and folders we are
 487 sharing.<br>
 488 <table border=0 cellspacing=2 cellpadding=2>
 489 <tr><td class=standout>integer</td><td class=standout>35 (Message Code)</td></tr>
 490 <tr><td class=standout>integer</td><td class=standout>folder count</td></tr>
 491 <tr><td class=standout>integer</td><td class=standout>file count</td></tr>
 492 </table><br>
 493
 494 Server-to-Client<br>
 495 This message is not sent from the server to the client.
 496
 497 <a name="S36"></a><h3>GetUserStats:36</h3>
 498 Client-to-Server
 499 This message is not sent from the client to the server.<br><br>
 500
 501 Server-to-Client<br>
 502 The server sends this message to us to indicate a change in a user's
 503 statistics.<br>
 504 <table border=0 cellspacing=2 cellpadding=2>
 505 <tr><td class=standout>integer</td><td class=standout>36 (Message Code)</td></tr>
 506 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 507 <tr><td class=standout>integer</td><td class=standout>avgspeed</td></tr>
 508 <tr><td class=standout>integer</td><td class=standout>downloadnum</td></tr>
 509 <tr><td class=standout>integer</td><td class=standout>something</td></tr>
 510 <tr><td class=standout>integer</td><td class=standout>files</td></tr>
 511 <tr><td class=standout>integer</td><td class=standout>dirs</td></tr>
 512 </table><br>
 513
 514 <a name="S40"></a><h3>QueuedDownloads:40</h3>
 515 Client-to-Server<br>
 516 It is unknown whether this is valid.
 517 <br><br>
 518
 519 Server-to-Client<br>
 520 The server sends this to indicate if someone has download slots available.<br>
 521 <table border=0 cellspacing=2 cellpadding=2>
 522 <tr><td class=standout>integer</td><td class=standout>40 (Message Code)</td></tr>
 523 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 524 <tr><td class=standout>integer</td><td class=standout>slotsfull</td></tr>
 525 </table><br>
 526
 527
 528 <a name="S60"></a><h3>PlaceInLineResponse:60</h3>
 529 Client-to-Server<br>
 530 Ask the server what place in line we are ...?<br>
 531 <table border=0 cellspacing=2 cellpadding=2>
 532 <tr><td class=standout>integer</td><td class=standout>60 (Message Code)</td></tr>
 533 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 534 <tr><td class=standout>integer</td><td class=standout>token (token of original file request?)</td></tr>
 535 <tr><td class=standout>integer</td><td class=standout>place (...?)</td></tr>
 536 </table><br>
 537
 538 Server-to-Client
 539 The server sends this to indicate change in place in queue while we're waiting
 540 for files from the other peer.
 541 <table border=0 cellspacing=2 cellpadding=2>
 542 <tr><td class=standout>integer</td><td class=standout>60 (Message Code)</td></tr>
 543 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 544 <tr><td class=standout>integer</td><td class=standout>token (token of original file request?)</td></tr>
 545 <tr><td class=standout>integer</td><td class=standout>place</td></tr>
 546 </table><br>
 547
 548 <a name="S62"></a><h3>RoomAdded:62</h3>
 549 Client-to-Server<br>
 550 Unknown if this is valid.<br><br>
 551
 552 Server-to-Client<br>
 553 The server tells us a new room has been added<br>
 554 <table border=0 cellspacing=2 cellpadding=2>
 555 <tr><td class=standout>integer</td><td class=standout>62 (Message Code)</td></tr>
 556 <tr><td class=standout>string</td><td class=standout>room name</td></tr>
 557 </table><br>
 558
 559 <a name="S63"></a><h3>RoomRemoved:63</h3>
 560 Client-to-Server<br>
 561 Unknown if this is valid.<br><br>
 562
 563 Server-to-Client<br>
 564 The server tells us a room has been removed<br>
 565 <table border=0 cellspacing=2 cellpadding=2>
 566 <tr><td class=standout>integer</td><td class=standout>62 (Message Code)</td></tr>
 567 <tr><td class=standout>string</td><td class=standout>room name</td></tr>
 568 </table><br>
 569
 570 <a name="S64"></a><h3>RoomList:64</h3>
 571 Client-to-Server<br>
 572 Request a list of rooms?
 573 <table border=0 cellspacing=2 cellpadding=2>
 574 <tr><td class=standout>integer</td><td class=standout>64 (Message Code)</td></tr>
 575 </table><br>
 576
 577 Server-to-Client<br>
 578 The server tells us a list of rooms.
 579 <table border=0 cellspacing=2 cellpadding=2>
 580 <tr><td class=standout>integer</td><td class=standout>64 (Message Code)</td></tr>
 581 <tr><td class=standout>integer</td><td class=standout>number of rooms</td></tr>
 582 <tr><td class=standout>string</td><td class=standout>name of room #1</td></tr>
 583 <tr><td class=standout>string</td><td class=standout>name of room #2</td></tr>
 584 <tr><td colspan=2 align=center>:<br>:</td></tr>
 585 <tr><td class=standout>string</td><td class=standout>name of room #n</td></tr>
 586 <tr><td class=standout>integer</td><td class=standout>user count records</td></tr>
 587 <tr><td class=standout>integer</td><td class=standout>user count in room #1</td></tr>
 588 <tr><td class=standout>integer</td><td class=standout>user count in room #2</td></tr>
 589 <tr><td colspan=2 align=center>:<br>:</td></tr>
 590 <tr><td class=standout>integer</td><td class=standout>user count in room #n</td></tr>
 591 </table><br>
 592
 593 <a name="S65"></a><h3>ExactFileSearch:65</h3>
 594 Client-to-Server<br>
 595 It is unknown whether this is valid.  Normal file search is a symmetric
 596 operation (the Client-to-Server and Server-to-Client messages are exactly
 597 the same and both valid), which would lead one to believe that maybe the
 598 ExactFileSearch works the same way.
 599 <br><br>
 600
 601 Server-to-Client<br>
 602 Someone is searching for a file with an exact name<br>
 603 <table border=0 cellspacing=2 cellpadding=2>
 604 <tr><td class=standout>integer</td><td class=standout>65 (Message Code)</td></tr>
 605 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 606 <tr><td class=standout>string</td><td class=standout>filename</td></tr>
 607 <tr><td class=standout>string</td><td class=standout>folder</td></tr>
 608 <tr><td class=standout>integer</td><td class=standout>size</td></tr>
 609 <tr><td class=standout>integer</td><td class=standout>checksum</td></tr>
 610 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 611 </table><br>
 612
 613 <a name="S66"></a><h3>AdminMessage:66</h3>
 614 Client-to-Server<br>
 615 unknown if this is valid<br><br>
 616
 617 Server-to-Client<br>
 618 The admin is sending a broadcast message.  ("The service is going down
 619 for maintenance in 10 minutes!")<br>
 620 <table border=0 cellspacing=2 cellpadding=2>
 621 <tr><td class=standout>integer</td><td class=standout>66 (Message Code)</td></tr>
 622 <tr><td class=standout>string</td><td class=standout>message</td></tr>
 623 </table><br>
 624
 625 <a name="S67"></a><h3>GlobalUserList:67</h3>
 626 Client-to-Server<br>
 627 We send this to get a global list of all users online.<br>
 628 <table border=0 cellspacing=2 cellpadding=2>
 629 <tr><td class=standout>integer</td><td class=standout>67 (Message Code)</td></tr>
 630 </table><br>
 631
 632 Server-to-Client<br>
 633 The list of users.<br>
 634 <table border=0 cellspacing=2 cellpadding=2>
 635 <tr><td class=standout>integer</td><td class=standout>67 (Message Code)</td></tr>
 636 <tr><td class=standout colspan=2 align=center>See user list format in JoinRoom message</td></tr>
 637 </table><br>
 638
 639 <a name="S68"></a><h3>TunneledMessage:68</h3>
 640 Used to tunnel a message through the server, I would assume...(?)<br>
 641 <table border=0 cellspacing=2 cellpadding=2>
 642 <tr><td class=standout>integer</td><td class=standout>68 (Message Code)</td></tr>
 643 <tr><td class=standout>string</td><td class=standout>username (to? from? depends on direction?)</td></tr>
 644 <tr><td class=standout>integer</td><td class=standout>code</td></tr>
 645 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 646 <tr><td class=standout>integer</td><td class=standout>IP address</td></tr>
 647 <tr><td class=standout>integer</td><td class=standout>port</td></tr>
 648 <tr><td class=standout>string</td><td class=standout>message</td></tr>
 649 </table><br>
 650
 651
 652 <a name="S69"></a><h3>PrivilegedUsers:69</h3>
 653 Client-to-Server<br>
 654 Get a list of all users that made a donation<br>
 655 <table border=0 cellspacing=2 cellpadding=2>
 656 <tr><td class=standout>integer</td><td class=standout>69 (Message Code)</td></tr>
 657 </table><br>
 658
 659 Server-to-Client<br>
 660 The returned list of users<br>
 661 <table border=0 cellspacing=2 cellpadding=2>
 662 <tr><td class=standout>integer</td><td class=standout>69 (Message Code)</td></tr>
 663 <tr><td class=standout>integer</td><td class=standout>number of users</td></tr>
 664 <tr><td class=standout>string</td><td class=standout>username #1</td></tr>
 665 <tr><td class=standout>string</td><td class=standout>username #2</td></tr>
 666 <tr><td colspan=2 align=center>:<br>:</td></tr>
 667 <tr><td class=standout>string</td><td class=standout>username #n</td></tr>
 668 </table><br>
 669
 670 <a name="S91"></a><h3>AddToPrivileged:91</h3>
 671 TODO, but likely something only an admin can do.  We would assume it
 672 takes a username and a duration.
 673
 674 <a name="S92"></a><h3>CheckPrivileges:92</h3>
 675 Client-to-Server<br>
 676 How much privileged time do I have left from my donation?<br>
 677 <table border=0 cellspacing=2 cellpadding=2>
 678 <tr><td class=standout>integer</td><td class=standout>92 (Message Code)</td></tr>
 679 </table><br>
 680
 681 Server-to-Client<br>
 682 You have this many days.
 683 <table border=0 cellspacing=2 cellpadding=2>
 684 <tr><td class=standout>integer</td><td class=standout>69 (Message Code)</td></tr>
 685 <tr><td class=standout>integer</td><td class=standout>number of days(?)</td></tr>
 686 </table><br>
 687
 688 <a name="S1001"></a><h3>CantConnectToPeer:1001</h3>
 689 Client-to-Server<br>
 690 We send this to say we cannot connect to a peer after it has asked us to connect.<br>
 691 <table border=0 cellspacing=2 cellpadding=2>
 692 <tr><td class=standout>integer</td><td class=standout>1001 (Message Code)</td></tr>
 693 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 694 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 695 </table><br>
 696
 697 Server-to-Client<br>
 698 The server sends this if we asked a peer to connect and it cannot do it.  This means
 699 a connection cannot be established in either direction--both parties are
 700 firewalled.<br>
 701 <table border=0 cellspacing=2 cellpadding=2>
 702 <tr><td class=standout>integer</td><td class=standout>1001 (Message Code)</td></tr>
 703 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 704 </table><br>
 705
 706
 707 <br><br>
 708 <h3>Relogged?</h3>
 709 Server sends this if someone else logged in under our nickname then
 710 disconnects us.<br>
 711
 712 <h3>RemoveUser?</h3>
 713 Client-to-Server<br>
 714 Used when we no longer want to be kept updated about a user's status.  This
 715 message is defined in the Python code, but not associated with a message
 716 code.  Maybe it falls into one of the message code gaps?<br>
 717 <table border=0 cellspacing=2 cellpadding=2>
 718 <tr><td class=standout>integer</td><td class=standout>??? (Message Code)</td></tr>
 719 <tr><td class=standout>string</td><td class=standout>username to stop watching</td></tr>
 720 </table><br>
 721
 722 <h3>CantCreateRoom?</h3>
 723 Server-to-Client<br>
 724 The server sends this to tell us a new room cannot be created?<br>
 725
 726 <!-- =========================================================== -->
 727 <!-- =========================================================== -->
 728 <!-- =========================================================== -->
 729
 730 <a name="peerMessages"></a><h2>Peer Messages</h2>
 731 <b>Jump directly to a peer message:</b>
 732 <a href="#Pinit">PeerInit</a>
 733 <a href="#Pfw">PierceFW</a>
 734 <a href="#P4">GetSharedFileList:4</a>
 735 <a href="#P5">SharedFileList:5</a>
 736 <a href="#P9">FileSearchResult:9</a>
 737 <a href="#P15">UserInfoRequest:15</a>
 738 <a href="#P16">UserInfoReply:16</a>
 739 <a href="#P36">FolderContentsRequest:36</a>
 740 <a href="#P37">FolderContentsResponse:37</a>
 741 <a href="#P40">TransferRequest:40</a>
 742 <a href="#P41">TransferResponse:41</a>
 743 <a href="#P42">PlaceholdUpload:42</a>
 744 <a href="#P43">QueueUpload:43</a>
 745 <a href="#P44">PlaceInQueue:44</a>
 746 <a href="#P46">UploadFailed:46</a>
 747 <a href="#P50">QueueFailed:50</a>
 748 <a href="#P51">PlaceInQueueRequest:51</a>
 749 <br><br>
 750
 751 <a name="Pfw"></a><h3>PierceFW</h3>
 752 This is the very first message send by peer that established a
 753 connection, if it has been asked by other peer to do so. Token is taken
 754 from ConnectToPeer server message.<br>
 755
 756 <a name="Pinit"></a><h3>PeerInit</h3>
 757 This message is sent by peer that initiated a connection, not
 758 necessarily a peer that actually established it. Token apparently
 759 can be anything. Type is 'P' if it's anything but filetransfer, 'F'
 760 otherwise.<br>
 761 <table border=0 cellspacing=2 cellpadding=2>
 762 <tr><td class=standout><b>byte</b></td><td class=standout>1 (Message Code) <b>Note that this is a BYTE!</a></td></tr>
 763 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 764 <tr><td class=standout>string</td><td class=standout>type</td></tr>
 765 <tr><td class=standout>integer</td><td class=standout>??? This seems to always be a constant (300 or 0x0000012c)</td></tr>
 766 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 767 </table><br>
 768
 769
 770 <a name="P4"></a><h3>GetSharedFileList:4</h3>
 771 Client-to-Peer<br>
 772 The client sends this to a peer to ask for a list of files.<br>
 773 <table border=0 cellspacing=2 cellpadding=2>
 774 <tr><td class=standout>integer</td><td class=standout>4 (Message Code)</td></tr>
 775 </table><br>
 776
 777 Peer-to-Client<br>
 778 It is unknown whether this is used.<br>
 779
 780 <a name="P5"></a><h3>SharedFileList:5</h3>
 781 Client-to-Peer<br>
 782 It is unknown whether this is used.<br><br>
 783
 784 Peer-to-Client<br>
 785 A peer responds with this message when sent a GetSharedFileList.
 786 This message can be a little complex, considering it
 787 contains data from three nested loops: directories, which contain files,
 788 which contain attributes.  When implementing parsing of this message,
 789 it may be helpful to note that within each directory, the list of
 790 files (each with its own list of sttributes) is in the exact same format
 791 as the list of files returned from FileSearchResult.<br>
 792 <table border=0 cellspacing=2 cellpadding=2>
 793 <tr><td class=standout>integer</td><td class=standout>5 (Message Code)</td></tr>
 794 <tr><td class=standout colspan=2 align=center>The following data is zlib compressed:</td></tr>
 795 <tr><td class=standout>integer</td><td class=standout>Number of directories</td></tr>
 796 <tr><td class=standout>string</td><td class=standout>Directory name #1</td></tr>
 797 <tr><td class=standout>integer</td><td class=standout>Number of files in directory #1</td></tr>
 798 <tr><td class=standout>byte?</td><td class=standout>Dir#1, File#1 code(?)</td></tr>
 799 <tr><td class=standout>string</td><td class=standout>Dir#1, File#1 filename</td></tr>
 800 <tr><td class=standout>integer</td><td class=standout>Dir#1, File#1 size1</td></tr>
 801 <tr><td class=standout>integer</td><td class=standout>Dir#1, File#1 size2</td></tr>
 802 <tr><td class=standout>string</td><td class=standout>Dir#1, File#1 ext</td></tr>
 803 <tr><td class=standout>integer</td><td class=standout>Dir#1, File#1 number of attributes</td></tr>
 804 <tr><td class=standout>integer</td><td class=standout>Dir#1, File#1, Attr#1 type</td></tr>
 805 <tr><td class=standout>integer</td><td class=standout>Dir#1, File#1, Attr#1 value</td></tr>
 806 <tr><td colspan=2 align=center>:<br>:</td></tr>
 807 <tr><td class=standout>integer</td><td class=standout>Dir#1, File#1, Attr#n value</td></tr>
 808 <tr><td colspan=2 align=center>:<br>:<br>:<br>:</td></tr>
 809 <tr><td class=standout>integer</td><td class=standout>Dir#n, File#n, Attr#n value</td></tr>
 810 </table><br>
 811
 812 <a name="P9"></a><h3>FileSearchResult:9</h3>
 813 Client-to-Peer<br>
 814 It is unknown whether this is used.<br><br>
 815
 816 Peer-to-Client<br>
 817 This is sent in response to a file search match.  Token is taken from original
 818 FileSearch message.  You will note that the file data is similar to that of
 819 SharedFileList, only without the outermost loop (directories).  It contains
 820 simply a list of files, each with a list of attributes.
 821 <br>
 822 <table border=0 cellspacing=2 cellpadding=2>
 823 <tr><td class=standout>integer</td><td class=standout>9 (Message Code)</td></tr>
 824 <tr><td class=standout colspan=2 align=center>The following data is zlib compressed:</td></tr>
 825 <tr><td class=standout>string</td><td class=standout>username</td></tr>
 826 <tr><td class=standout>integer</td><td class=standout>token</td></tr>
 827 <tr><td class=standout>integer</td><td class=standout>Number of files</td></tr>
 828 <tr><td class=standout>byte</td><td class=standout>File #1, code</td></tr>
 829 <tr><td class=standout>string</td><td class=standout>File #1, filename</td></tr>
 830 <tr><td class=standout>integer</td><td class=standout>File #1, size1</td></tr>
 831 <tr><td class=standout>integer</td><td class=standout>File #1, size2</td></tr>
 832 <tr><td class=standout>string</td><td class=standout>File #1, ext</td></tr>
 833 <tr><td class=standout>integer</td><td class=standout>File #1, number of attributes</td></tr>
 834 <tr><td class=standout>integer</td><td class=standout>File #1, Attr #1 type</td></tr>
 835 <tr><td class=standout>integer</td><td class=standout>File #1, Attr #1 value</td></tr>
 836 <tr><td colspan=2 align=center>:<br>:</td></tr>
 837 <tr><td class=standout>integer</td><td class=standout>File #n, Attr #n value</td></tr>
 838 <tr><td class=standout>byte</td><td class=standout>Free upload slots</td></tr>
 839 <tr><td class=standout>integer</td><td class=standout>Upload speed</td></tr>
 840 <tr><td class=standout>integer</td><td class=standout>In Queue</td></tr>
 841 </table><br>
 842
 843 <a name="P15"></a><h3>UserInfoRequest:15</h3>
 844 Client-to-Peer<br>
 845 <table border=0 cellspacing=2 cellpadding=2>
 846 <tr><td class=standout>integer</td><td class=standout>15 (Message Code)</td></tr>
 847 </table><br>
 848
 849 Peer-to-Client<br>
 850 It is unknown whether this is used.<br><br>
 851
 852 <a name="P16"></a><h3>UserInfoReply:16</h3>
 853 Client-to-Peer<br>
 854 It is unknown whether this is used.<br><br>
 855
 856 Peer-to-Client<br>
 857 <table border=0 cellspacing=2 cellpadding=2>
 858 <tr><td class=standout>integer</td><td class=standout>16 (Message Code)</td></tr>
 859 <tr><td class=standout>string</td><td class=standout>User's description</td></tr>
 860 <tr><td class=standout>byte</td><td class=standout>Does this user have a pic?</td></tr>
 861 <tr><td class=standout>string</td><td class=standout>This data element is only present if the previous byte is true.  This string contains the user pic file content</td></tr>
 862 <tr><td class=standout>integer</td><td class=standout>User uploads</td></tr>
 863 <tr><td class=standout>integer</td><td class=standout>Total uploads</td></tr>
 864 <tr><td class=standout>integer</td><td class=standout>Queue size</td></tr>
 865 <tr><td class=standout>integer</td><td class=standout>Slots available</td></tr>
 866 </table><br>
 867
 868 <a name="P36"></a><h3>FolderContentsRequest:36</h3>
 869
 870 <a name="P37"></a><h3>FolderContentsResponse:37</h3>
 871
 872 <a name="P40"></a><h3>TransferRequest:40</h3>
 873 Client-to-Peer<br>
 874 Ask a peer for a file.  See the sequences section at the bottom of this
 875 document.  Token is [new, unique token? taken from another message?].<br>
 876 <table border=0 cellspacing=2 cellpadding=2>
 877 <tr><td class=standout>integer</td><td class=standout>40 (Message Code)</td></tr>
 878 <tr><td class=standout>integer</td><td class=standout>Direction constant, <a href="#constants">see above</a></td></tr>
 879 <tr><td class=standout>integer</td><td class=standout>Token</a></td></tr>
 880 <tr><td class=standout>string</td><td class=standout>filename</a></td></tr>
 881 <tr><td class=standout>integer</td><td class=standout>This data field is only present if direction==1.  File size.</a></td></tr>
 882 </table><br>
 883
 884 Peer-to-Client<br>
 885 Tell a peer we are about to send them a file.  (Used when piercing a
 886 firewall?)  The message format is exactly the same as the client-to-peer
 887 version.<br><br>
 888
 889 <a name="P41"></a><h3>TransferResponse:41</h3>
 890 Client-to-Peer or Peer-to-Client<br>
 891 This is the proper response to a TransferRequest message.  "Yes, I agree to
 892 take the file" or "no, I do not agree to take the file."  Token is taken
 893 from TransferRequest message.<br>
 894 <table border=0 cellspacing=2 cellpadding=2>
 895 <tr><td class=standout>integer</td><td class=standout>41 (Message Code)</td></tr>
 896 <tr><td class=standout>integer</td><td class=standout>Token</td></tr>
 897 <tr><td class=standout>byte</td><td class=standout>Allowed?</td></tr>
 898 <tr><td colspan=2 align=center>If Allowed is true:</td></tr>
 899 <tr><td class=standout>integer</td><td class=standout>Optionally, the file size</td></tr>
 900 <tr><td colspan=2 align=center>If Allowed is false:</td></tr>
 901 <tr><td class=standout>string</td><td class=standout>Optionally, a message explaining why the request was denied</td></tr>
 902 </table><br>
 903
 904 <a name="P42"></a><h3>PlaceholdUpload:42</h3>
 905 Not sure yet.<br>
 906 <table border=0 cellspacing=2 cellpadding=2>
 907 <tr><td class=standout>integer</td><td class=standout>42 (Message Code)</td></tr>
 908 <tr><td class=standout>string</td><td class=standout>Filename</td></tr>
 909 </table><br>
 910
 911 <a name="P43"></a><h3>QueueUpload:43</h3>
 912 Not sure yet.<br>
 913 <table border=0 cellspacing=2 cellpadding=2>
 914 <tr><td class=standout>integer</td><td class=standout>43 (Message Code)</td></tr>
 915 <tr><td class=standout>string</td><td class=standout>Filename</td></tr>
 916 </table><br>
 917
 918 <a name="P44"></a><h3>PlaceInQueue:44</h3>
 919 Client-to-Peer<br>
 920 It is unknown whether this is used.<br><br>
 921
 922 Peer-to-Client<br>
 923 You are in queue position x for file y.  This is the response to a
 924 PlaceInQueueRequest.<br>
 925 <table border=0 cellspacing=2 cellpadding=2>
 926 <tr><td class=standout>integer</td><td class=standout>44 (Message Code)</td></tr>
 927 <tr><td class=standout>string</td><td class=standout>filename</td></tr>
 928 <tr><td class=standout>integer</td><td class=standout>place</td></tr>
 929 </table><br>
 930
 931 <a name="P46"></a><h3>UploadFailed:46</h3>
 932 Not sure yet.<br>
 933 <table border=0 cellspacing=2 cellpadding=2>
 934 <tr><td class=standout>integer</td><td class=standout>46 (Message Code)</td></tr>
 935 <tr><td class=standout>string</td><td class=standout>Filename</td></tr>
 936 </table><br>
 937
 938 <a name="P50"></a><h3>QueueFailed:50</h3>
 939 Not sure yet.<br>
 940 <table border=0 cellspacing=2 cellpadding=2>
 941 <tr><td class=standout>integer</td><td class=standout>50 (Message Code)</td></tr>
 942 <tr><td class=standout>string</td><td class=standout>Filename</td></tr>
 943 <tr><td class=standout>string</td><td class=standout>Reason</td></tr>
 944 </table><br>
 945
 946 <a name="P51"></a><h3>PlaceInQueueRequest:51</h3>
 947 Client-to-Peer<br>
 948 What place in your queue am I?  The response is a PlaceInQueue message.<br>
 949 <table border=0 cellspacing=2 cellpadding=2>
 950 <tr><td class=standout>integer</td><td class=standout>51 (Message Code)</td></tr>
 951 </table><br>
 952
 953 Peer-to-Client<br>
 954 It is unknown whether this is used.<br><br>
 955
 956 <a name="messageSequences"></a><h2>Message Sequences</h2>
 957 <p>
 958 This section will attempt to describe the message sequences for
 959 common operations.
 960 </p>
 961 <h3>Login</h3>
 962 User logs in successfully, gets server greeting, gets privileged
 963 user list, gets chat room list, starts monitoring buddies
 964 <ul>
 965 <li>client sends Login message</li>
 966 <li>client sends SetWaitPort message</li>
 967 <li>server sends Login response message</li>
 968 <li>server automatically sends a RoomList response</li>
 969 <li>server automatically sends a PrivilegedUsers response</li>
 970 <li>client sends SharedFoldersFiles message</li>
 971 <li>client sends AddUser message for each buddy in buddy list</li>
 972 <li>server sends AddUser response for each buddy in the buddy list</li>
 973 </ul>
 974
 975 <h3>Search</h3>
 976 TODO: User performs a search
 977
 978 <h3>Chat</h3>
 979 TODO: User enters a room, listens, speaks, then exits room
 980
 981 <h3>Obtaining Peer Address, basic</h3>
 982 This sequence will grab a peer's address (ip+port), given the username, in the most simple manner.
 983 <ul>
 984 <li>Client sends GetPeerAddress message</li>
 985 <li>Server sends GetPeerAddress response</li>
 986 </ul>
 987
 988 <h3>Obtaining Peer Address, advanced</h3>
 989 This sequence will start monitoring a user (as if that user were on your buddy
 990 list), and use that information to not only obtain the address, but get
 991 notified if the user goes offline.</b>  This is the method that the Python
 992 SoulSeek client uses.
 993 <ul>
 994 <li>client sends GetUserStatus message to server</li>
 995 <li>server responds with GetUserStatus message with status</li>
 996 <li>client sends AddUser message to server</li>
 997 <li>server responds with AddUser message</li>
 998 <li>server sends unsolicited GetPeerAddress message</li>
 999 </ul>
1000
1001
1002 <h2>&nbsp;</h2>
1003 <table border=1 cellspacing=0 cellpadding=7>
1004 <tr><td>
1005 <b>Note:</b> The following File Transfer scenarios cover every combination and permutation of
1006 the three states (client FW, peer FW, queue).  They all assume the peer address has
1007 been obtained by one of the above methods.
1008 </td></tr></table>
1009
1010 <h3>File Transfer, basic</h3>
1011 Client may or may not be firewalled, peer is not firewalled, peer has no wait queue<br>
1012 <ul>
1013 <li>client opens a "P" type socket to the peer.  This need not be a NEW
1014 socket.  If a "P" type connection to the peer has already been established (for
1015 instance, because the peer has sent you a search result), it can be
1016 reused.</li>
1017 <li>client sends PeerInit "P" message immediately followed by TransferRequest message</li>
1018 <li>peer optionally sends back 12 bytes (the 5th is zero or one)<br>
1019     (Note from Brian: I am a little bit worried about the random 12 bytes that
1020     sometimes get sent before a TransferResponse message.  The first four bytes
1021     are obviously not a message length.  Like I said in the comments, the
1022     Python code (slskproto.py:SlskProtoThread..process_peer_input()) has some
1023     wacky if-elseif-else logic in there that gets called only if it is a non
1024     "F" peer connection and it is the first message received.)</li>
1025
1026 <li>peer sends back TransferResponse message</li>
1027 <li>client opens second socket to peer</li>
1028 <li>client sends PeerInit "F" message to peer</li>
1029 <li>peer sends file</li>
1030 <li>client closes second socket to peer</li>
1031 </ul>
1032
1033 <h3>File Transfer, firewall</h3>
1034 TODO: Client is not firewalled, peer is firewalled, peer has no wait queue
1035
1036 <h3>File Transfer, two firewalls</h3>
1037 Client is firewalled, peer is firewalled, wait queue does not matter<br>
1038 <ul><li>A peer-to-peer connection in this situation is impossible</li></ul>
1039
1040 <h3>File Transfer, queue 1</h3>
1041 TODO: Client is not firewalled, peer is not firewalled, peer has wait queue
1042
1043 <h3>File Transfer, queue 2</h3>
1044 TODO: Client is not firewalled, peer is firewalled, peer has wait queue
1045
1046 <h3>File Transfer, queue 3</h3>
1047 TODO: Client is firewalled, peer is not firewalled, peer has no wait queue
1048
1049 <hr size=2 noshade>
1050 End of Document
1051 </body>