SoulSeek Protocol DocumentationTable of ContentsVersion History
Introduction
Overview
Constants
Messages
Server Messages
Peer Messages
Message Sequences
Version History2003-10-05: Added integer to the Login message containing the IP of the client. Arend van Beelen jr.
2003-10-04: Correct statement about Soulseek message byte-ordering. They are little-endian. Robert Sayre
2003-03-16: Added PierceFW message summary, added to PlaceInQueueRequest message summary, Robert Sayre
2003-01-26: Added peer messages and login sequence, had revelation about reusing existing peer socket from search result for file request, BriEnigma
2003-01-20: Initial revision, BriEnigma
CVS version ID: $Id: protocol.html,v 1.11 2003/10/12 19:23:18 franklinmint Exp $
Mental Note: When updating this document, remember to upload the latest version to the SourceForge project documentation web page. Introduction
The SoulSeek protocol is not officially documented anywhere. This document is the result of effort by members of the SoleSeek project team. It was pieced together by examining the Python SoulSeek source code, as well as sniffing network packets. (Hey, Nir! Please don't sue us inder the DMCA for reverse engineering the protocol!) This document should not be considered the official specification. It is our best guess at how the protocol works.
Overview
The SoulSeek protocol consists of a finite number of messages. Some of these messages are used for communicating between the client and server. Others are used for communications between a client and a peer (another client). All of these messages (with the exception of a couple of peer messages TODO:...are PeerInit and PierceFW the only exceptions?...) follow a standard format.
There are a few datatypes that the message blocks use:
(TODO: endian-ness? I always get mixed up.)
Integer4 bytes, little endianByte1 byteStringan 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.TODO:are other datatypes used?
The standard message blocks start with an integer. This integer defines the size of the message payload--everything contained in the message, but not including the 4-bytes length. The payload starts with an integer that we shall call the message code that describes what type of message this is. The datatype and meaning of the remaining payload data is dependant on the message code. For example, the following is a very simple message, the Login message from the client to the server:
Message LengthMessage Payload4-byte-integer: 304-byte-integer: 14-byte-integer: 8JohnGalt4-byte-integer: 6secret4-byte-integer: 200Message Code 1 == "Login" (4 bytes)String, length 8 (12 bytes)String, length 6 (10 bytes)Version (4 bytes)This sends a message to the server with message code 1. Since message code 1 is the Login message, the server knows to expect two strings and an integer. The fist string, we can see is of length 8 and contains the letters "JohnGalt". The second string is of length 6 and contains the letters "secret". The remaining integer is the number 200.
It is worth noting that messages with the same code may have different payloads, depending on the direction of the message: client-to-server (generally, a request) or server-to-client (generally, a response). In the above example, the message is a Login message from the client to the server. The server responds to the client with message that also has the message code 1 ("Login"), but has a different payload. Login messages originating at the server (we can think of it as a Login response message) contain a byte (1/0 for success/fail) followed by a string (a message about the results of the login or a server greeting).
Constants
The SoulSeek protocol makes use of several constants:
Status Codes-1Unknown0Offline1Away2Online
Transfer Direction0Download1Upload
TODO: There are probably more...Messages
Jump directly to a server message: Login:1 SetWaitPort:2 GetPeerAddress:3 AddUser:5 GetUserStatus:7 SayChatroom:13 JoinRoom:14 LeaveRoom:15 UserJoinedRoom:16 UserLeftRoom:17 ConnectToPeer:18 MessageUser:22 MessageAcked:23 FileSearch:26 SetStatus:28 SharedFoldersFiles:35 GetUserStats:36 QueuedDownloads:40 PlaceInLineResponse:60 RoomAdded:62 RoomRemoved:63 RoomList:64 ExactFileSearch:65 AdminMessage:66 GlobalUserList:67 TunneledMessage:68 PrivilegedUsers:69 AddToPrivileged:91 CheckPrivileges:92 CantConnectToPeer:1001
Jump directly to a peer message: PeerInit PierceFW GetSharedFileList:4 SharedFileList:5 FileSearchResult:9 UserInfoRequest:15 UserInfoReply:16 FolderContentsRequest:36 FolderContentsResponse:37 TransferRequest:40 TransferResponse:41 PlaceholdUpload:42 QueueUpload:43 PlaceInQueue:44 UploadFailed:46 QueueFailed:50 PlaceInQueueRequest:51
Server MessagesLogin:1Client-to-Server (attempt to login)
integer1 (Message Code)stringUsernamestringPasswordintegerVersion
Server-to-Client (login success/fail)
integer1 (Message Code)bytesuccess (0=fail, 1=success)stringLogin message (error message or greeting message)integerOptional integer containing the external IPv4 address of the client. Only sent if the login was successful.
SetWaitPort:2Client-to-Server
This is sent to the server to tell it what port we are listening on.
integer2 (Message Code)integerport number (generally 2234)
Server-to-Client
It is believed that SetWaitPort messages are not sent from the server to the client.
GetPeerAddress:3Client-to-Server
This is sent to the server to ask for a peer's address (IP address and port), given the peer's username.
integer3 (Message Code)stringusername
Server-to-Client
This is the response from the server.
integer3 (Message Code)stringusername this address belongs tointegerIP addressintegerport number
AddUser:5Client-to-Server
This message is sent when you want to start monitoring the online status of a user. Once we start "watching" a user by sending this message, the server will send (TODO: is the message AddUser or GetUserStatus) messages to us whenever the user changes status (away, back, offline, etc).
Note: There also seems to be a GetPeerAddress response message returned automatically, along with the AddUser response message--even though the GetPeerAddress request was never made. Can anyone confirm this?
integer5 (Message Code)stringusername to start watching
Server-to-Client
integer5 (Message Code)stringusername being watchingbytewhether the user exists
GetUserStatus:7Client-to-Server
This message is used to request a user's current status.
integer7 (Message Code)stringusername to get status of
Server-to-client
This message is used by the server to report back to us a user's current status. integer7 (Message Code)stringusername this status applies tointegerstatus code, see above
SayChatroom:13Client-to-Server
This message is sent to say something in a chatroom.
integer13 (Message Code)stringroomstringmessage
Server-to-Client
Somebody said something in a chatroom we are in.
integer13 (Message Code)stringroomstringusernamestringmessage
JoinRoom:14Client-to-Server
We would like to join a chatroom.
integer14 (Message Code)stringroom
Server-to-Client
We have joined the room. Here is a list of all the people in the room. (This could very easily be a giant set of data!)
integer14 (Message Code)stringroomintegernumber of users in this roomstringusername #1stringusername #2:
:stringusername #nintegernumber of status code intgers (should be the same as number of users in the above field)integerstatus code of username #1integerstatus code of username #2:
:integerstatus code of username #nintegernumber of statistics records (should be the same as number of users in the above field)integerstats record 1: avgspeed of username #1integerstats record 1: downloadnum of username #1integerstats record 1: something of username #1integerstats record 1: files of username #1integerstats record 1: dirs of username #1integerstats record 2: avgspeed of username #2integerstats record 2: downloadnum of username #2integerstats record 2: something of username #2integerstats record 2: files of username #2integerstats record 2: dirs of username #2:
:integerstats record n: avgspeed of username #nintegerstats record n: downloadnum of username #nintegerstats record n: something of username #nintegerstats record n: files of username #nintegerstats record n: dirs of username #nintegernumber of slotsfull recordsintegerslotsfull field of username #1integerslotsfull field of username #2:
:integerslotsfull field of username #n
LeaveRoom:15Client-to-Server
We would like to leave a chatroom.
integer15 (Message Code)stringroom
Server-to-Client
Server tells us we have left the room. Note that, in theory, this could happen at any time--it may not necessarily be a response to a LeaveRoom message. It is entirely possible that the server could send this to kick you out of a room (although this author has never seen it happen).
integer15 (Message Code)stringroom
UserJoinedRoom:16Client-to-Server
This message is not sent from the client.
Server-to-Client
User "x" has entered chat room "y".
integer16 (Message Code)stringroomstringusername
UserLeftRoom:17Client-to-Server
This message is not sent from the client.
Server-to-Client
User "x" has left chat room "y".
integer17 (Message Code)stringroomstringusername
ConnectToPeer:18Client-to-Server If we cannot establish a direct connection to a user (for example, they are behind a firewall), we send this message to the server, which will tell the peer to connect back to us.
integer18 (Message Code)integertokenstringusernamestringtype: "P"/"F" (see PeerInit)
Server-to-Client
If someone cannot establish a connection with us (for instance, we are behind a firewall), the server sends this message to us. We then attempt to establish a direct connection to the peer.
integer18 (Message Code)stringusernamestringtype: "P"/"F" (see PeerInit)integerip addressintegerportintegertoken
MessageUser:22Client-to-Server
Send a private chat message to a user
integer22 (Message Code)stringusernamestringmessage
Server-to-Client
Somebody sent us a private chat message
integer22 (Message Code)integermessage IDintegertimestampstringusernamestringmessage
MessageAcked:23Client-to-Server
Confirmation of receiving a private chat message. If we do not send it, the server will keep sending the chat phrase to us.
integer23 (Message Code)integermessage ID
Server-to-Client
This message is not sent from the server to the client.
FileSearch:26Client-to-Server
We send this to the server when we want to search for something.
integer26 (Message Code)integertokenstringsearch text
Server-to-Client The server sends this to tell us someone is searching for something.
integer26 (Message Code)stringusernameintegertokenstringsearch text
SetStatus:28Client-to-Server
Change my away/online status.
integer28 (Message Code)integernew status, see above
Server-to-Client
This message is not sent from the server to the client. SharedFoldersFiles:35Server-to-Client
We send this to the server to tell it how many files and folders we are sharing.
integer35 (Message Code)integerfolder countintegerfile count
Server-to-Client
This message is not sent from the server to the client. GetUserStats:36Client-to-Server This message is not sent from the client to the server.
Server-to-Client
The server sends this message to us to indicate a change in a user's statistics.
integer36 (Message Code)stringusernameintegeravgspeedintegerdownloadnumintegersomethingintegerfilesintegerdirs
QueuedDownloads:40Client-to-Server
It is unknown whether this is valid.
Server-to-Client
The server sends this to indicate if someone has download slots available.
integer40 (Message Code)stringusernameintegerslotsfull
PlaceInLineResponse:60Client-to-Server
Ask the server what place in line we are ...?
integer60 (Message Code)stringusernameintegertoken (token of original file request?)integerplace (...?)
Server-to-Client The server sends this to indicate change in place in queue while we're waiting for files from the other peer. integer60 (Message Code)stringusernameintegertoken (token of original file request?)integerplace
RoomAdded:62Client-to-Server
Unknown if this is valid.
Server-to-Client
The server tells us a new room has been added
integer62 (Message Code)stringroom name
RoomRemoved:63Client-to-Server
Unknown if this is valid.
Server-to-Client
The server tells us a room has been removed
integer62 (Message Code)stringroom name
RoomList:64Client-to-Server
Request a list of rooms? integer64 (Message Code)
Server-to-Client
The server tells us a list of rooms. integer64 (Message Code)integernumber of roomsstringname of room #1stringname of room #2:
:stringname of room #nintegeruser count recordsintegeruser count in room #1integeruser count in room #2:
:integeruser count in room #n
ExactFileSearch:65Client-to-Server
It is unknown whether this is valid. Normal file search is a symmetric operation (the Client-to-Server and Server-to-Client messages are exactly the same and both valid), which would lead one to believe that maybe the ExactFileSearch works the same way.
Server-to-Client
Someone is searching for a file with an exact name
integer65 (Message Code)integertokenstringfilenamestringfolderintegersizeintegerchecksumstringusername
AdminMessage:66Client-to-Server
unknown if this is valid
Server-to-Client
The admin is sending a broadcast message. ("The service is going down for maintenance in 10 minutes!")
integer66 (Message Code)stringmessage
GlobalUserList:67Client-to-Server
We send this to get a global list of all users online.
integer67 (Message Code)
Server-to-Client
The list of users.
integer67 (Message Code)See user list format in JoinRoom message
TunneledMessage:68Used to tunnel a message through the server, I would assume...(?)
integer68 (Message Code)stringusername (to? from? depends on direction?)integercodeintegertokenintegerIP addressintegerportstringmessage
PrivilegedUsers:69Client-to-Server
Get a list of all users that made a donation
integer69 (Message Code)
Server-to-Client
The returned list of users
integer69 (Message Code)integernumber of usersstringusername #1stringusername #2:
:stringusername #n
AddToPrivileged:91TODO, but likely something only an admin can do. We would assume it takes a username and a duration. CheckPrivileges:92Client-to-Server
How much privileged time do I have left from my donation?
integer92 (Message Code)
Server-to-Client
You have this many days. integer69 (Message Code)integernumber of days(?)
CantConnectToPeer:1001Client-to-Server
We send this to say we cannot connect to a peer after it has asked us to connect.
integer1001 (Message Code)integertokenstringusername
Server-to-Client
The server sends this if we asked a peer to connect and it cannot do it. This means a connection cannot be established in either direction--both parties are firewalled.
integer1001 (Message Code)integertoken
Relogged?Server sends this if someone else logged in under our nickname then disconnects us.
RemoveUser?Client-to-Server
Used when we no longer want to be kept updated about a user's status. This message is defined in the Python code, but not associated with a message code. Maybe it falls into one of the message code gaps?
integer??? (Message Code)stringusername to stop watching
CantCreateRoom?Server-to-Client
The server sends this to tell us a new room cannot be created?
Peer Messages
Jump directly to a peer message: PeerInit PierceFW GetSharedFileList:4 SharedFileList:5 FileSearchResult:9 UserInfoRequest:15 UserInfoReply:16 FolderContentsRequest:36 FolderContentsResponse:37 TransferRequest:40 TransferResponse:41 PlaceholdUpload:42 QueueUpload:43 PlaceInQueue:44 UploadFailed:46 QueueFailed:50 PlaceInQueueRequest:51
PeerInitThis message is sent by peer that initiated a connection, not necessarily a peer that actually established it. Token apparently can be anything. Type is 'P' if it's anything but filetransfer, 'F' otherwise.
byte1 (Message Code)
Note that this is a BYTE!stringusernamestringtypeinteger??? This seems to always be a constant (300 or 0x0000012c)integertoken
PierceFWClient has asked the server to tell the peer to contact us. The token should be associated with the peer user.
byte0 (Message Code)
Note that this is a BYTE!integertoken
GetSharedFileList:4Client-to-Peer
The client sends this to a peer to ask for a list of files.
integer4 (Message Code)
Peer-to-Client
It is unknown whether this is used.
SharedFileList:5Client-to-Peer
It is unknown whether this is used.
Peer-to-Client
A peer responds with this message when sent a GetSharedFileList. This message can be a little complex, considering it contains data from three nested loops: directories, which contain files, which contain attributes. When implementing parsing of this message, it may be helpful to note that within each directory, the list of files (each with its own list of sttributes) is in the exact same format as the list of files returned from FileSearchResult.
integer5 (Message Code)The following data is zlib compressed:integerNumber of directoriesstringDirectory name #1integerNumber of files in directory #1byte?Dir#1, File#1 code(?)stringDir#1, File#1 filenameintegerDir#1, File#1 size1integerDir#1, File#1 size2stringDir#1, File#1 extintegerDir#1, File#1 number of attributesintegerDir#1, File#1, Attr#1 typeintegerDir#1, File#1, Attr#1 value:
:integerDir#1, File#1, Attr#n value:
:
:
:integerDir#n, File#n, Attr#n value
FileSearchResult:9Client-to-Peer
It is unknown whether this is used.
Peer-to-Client
This is sent in response to a file search match. Token is taken from original FileSearch message. You will note that the file data is similar to that of SharedFileList, only without the outermost loop (directories). It contains simply a list of files, each with a list of attributes.
integer9 (Message Code)The following data is zlib compressed:stringusernameintegertokenintegerNumber of filesbyteFile #1, codestringFile #1, filenameintegerFile #1, size1integerFile #1, size2stringFile #1, extintegerFile #1, number of attributesintegerFile #1, Attr #1 typeintegerFile #1, Attr #1 value:
:integerFile #n, Attr #n valuebyteFree upload slotsintegerUpload speedintegerIn Queue
UserInfoRequest:15Client-to-Peer
integer15 (Message Code)
Peer-to-Client
It is unknown whether this is used.
UserInfoReply:16Client-to-Peer
It is unknown whether this is used.
Peer-to-Client
integer16 (Message Code)stringUser's descriptionbyteDoes this user have a pic?stringThis data element is only present if the previous byte is true. This string contains the user pic file contentintegerUser uploadsintegerTotal uploadsintegerQueue sizeintegerSlots available
FolderContentsRequest:36FolderContentsResponse:37TransferRequest:40Client-to-Peer
Ask a peer for a file. See the sequences section at the bottom of this document. Token is [new, unique token? taken from another message?].
integer40 (Message Code)integerDirection constant, see aboveintegerTokenstringfilenameintegerThis data field is only present if direction==1. File size.
Peer-to-Client
Tell a peer we are about to send them a file. (Used when piercing a firewall?) The message format is exactly the same as the client-to-peer version.
TransferResponse:41Client-to-Peer or Peer-to-Client
This is the proper response to a TransferRequest message. "Yes, I agree to take the file" or "no, I do not agree to take the file." Token is taken from TransferRequest message.
integer41 (Message Code)integerTokenbyteAllowed?If Allowed is true:integerOptionally, the file sizeIf Allowed is false:stringOptionally, a message explaining why the request was denied
PlaceholdUpload:42Not sure yet.
integer42 (Message Code)stringFilename
QueueUpload:43Not sure yet.
integer43 (Message Code)stringFilename
PlaceInQueue:44Client-to-Peer
It is unknown whether this is used.
Peer-to-Client
You are in queue position x for file y. This is the response to a PlaceInQueueRequest.
integer44 (Message Code)stringfilenameintegerplace
UploadFailed:46Not sure yet.
integer46 (Message Code)stringFilename
QueueFailed:50Not sure yet.
integer50 (Message Code)stringFilenamestringReason
PlaceInQueueRequest:51Client-to-Peer
What place in your queue am I? The response is a PlaceInQueue message.
integer51 (Message Code)stringFilename
Peer-to-Client
It is unknown whether this is used.
Message Sequences
This section will attempt to describe the message sequences for common operations.
LoginUser logs in successfully, gets server greeting, gets privileged user list, gets chat room list, starts monitoring buddies client sends Login message client sends SetWaitPort message server sends Login response message server automatically sends a RoomList response server automatically sends a PrivilegedUsers response client sends SharedFoldersFiles message client sends AddUser message for each buddy in buddy list server sends AddUser response for each buddy in the buddy list SearchTODO: User performs a search ChatTODO: User enters a room, listens, speaks, then exits room Obtaining Peer Address, basicThis sequence will grab a peer's address (ip+port), given the username, in the most simple manner. Client sends GetPeerAddress message Server sends GetPeerAddress response Obtaining Peer Address, advancedThis sequence will start monitoring a user (as if that user were on your buddy list), and use that information to not only obtain the address, but get notified if the user goes offline. This is the method that the Python SoulSeek client uses. client sends GetUserStatus message to server server responds with GetUserStatus message with status client sends AddUser message to server server responds with AddUser message server sends unsolicited GetPeerAddress message
Note: The following File Transfer scenarios cover every combination and permutation of the three states (client FW, peer FW, queue). They all assume the peer address has been obtained by one of the above methods. File Transfer, basicClient may or may not be firewalled, peer is not firewalled, peer has no wait queue
client opens a "P" type socket to the peer. This need not be a NEW socket. If a "P" type connection to the peer has already been established (for instance, because the peer has sent you a search result), it can be reused. client sends PeerInit "P" message immediately followed by TransferRequest message peer optionally sends back 12 bytes (the 5th is zero or one)
(Note from Brian: I am a little bit worried about the random 12 bytes that sometimes get sent before a TransferResponse message. The first four bytes are obviously not a message length. Like I said in the comments, the Python code (slskproto.py:SlskProtoThread..process_peer_input()) has some wacky if-elseif-else logic in there that gets called only if it is a non "F" peer connection and it is the first message received.) peer sends back TransferResponse message client opens second socket to peer client sends PeerInit "F" message to peer peer sends file client closes second socket to peer File Transfer, firewallTODO: Client is not firewalled, peer is firewalled, peer has no wait queue File Transfer, two firewallsClient is firewalled, peer is firewalled, wait queue does not matter
A peer-to-peer connection in this situation is impossibleFile Transfer, queue 1TODO: Client is not firewalled, peer is not firewalled, peer has wait queue File Transfer, queue 2TODO: Client is not firewalled, peer is firewalled, peer has wait queue File Transfer, queue 3TODO: Client is firewalled, peer is not firewalled, peer has no wait queue End of Document
本文地址：http://com.8s8s.com/it/it22353.htm