patch #7442
[mldonkey.git] / docs / napster-protocol.txt
blob8ce71c90f35b9d733f3d81f11a318a3bea2ceb27
1 napster messages
2 ================
4 by drscholl@users.sourceforge.net
5 April 7, 2000
7 0.  Foreward
9 This is meant to be an open specification.  If you find errors or know of
10 additional functionality not described hereafter, please send me email.  It
11 benefits the entire community to have a complete and accurate protocol
12 specification.  Not only does it allow for clients to be developed for any
13 platform, but also decreases the strain on the server having to parse out
14 bad client messages.
16 Disclaimer: The following information was gathered by analyzing the protocol
17 between the linux nap client and may not resemble the official Windows client
18 protocol.
20 1.  Recent Changes
22 * Section 3: 430-432 channel invite messages (2001-04-07)
23 * Section 3: WMA-FILE used as checksum for .wma files (2001-03-12)
24 * numeric 607 adds download client's speed (2000-12-28)
25 * added new numerics 640-642 for direct client to client browsing support
26   (2000-12-23)
28 2.  Client-Server protocol
30 Napster uses TCP for client to server communication.  Typically the servers
31 run on ports 8888 and 7777.  Note that this is different from the `metaserver'
32 (or redirector) which runs on port 8875.
34 each message to/from the server is in the form of
35         <length><type><data>
36 where <length> and <type> are 2 bytes each.  <length> specifies the length in
37 bytes of the <data> portion of the message.  Be aware that <length> and <type>
38 appear to be in little-endian format (least significant byte goes first).  For
39 example, in the C language you would encode the number 1 as
40         const unsigned char num[2] = { 0x01, 0x00 };
41 and 256 would be encoded as
42         const unsigned char num[2] = { 0x00, 0x01 };
43 [The above is for illustrative purposes only, there are much quicker ways to
44 actually encode a number. -ed]
45 The <data> portion of the message is a plain ASCII string.
47 Note that in many cases, strings are passed as double-quoted entries.  For
48 example, filenames and client id strings are always sent as
49         "random band - generic cowboy song.mp3"
51         "nap v0.8"
52 Where required, double quotes are used in the description of the messages
53 below.
55 Some additional information about use of quotes inside of quotes:
56 > The answer is, no, it doesn't do escaping of quotes.  If you try searching
57 > for the phrase 'a "quoted" string' on the windows client, you get no songs
58 > found, and "invalid search request" printed in yellow in your console
59 > window.  (don't know what code that is, sorry.)
61 > and no wonder-- a little birdie told me that the client sends this:
63 > FILENAME CONTAINS "a "quoted" string" MAX_RESULTS 100
65 [contributed by Ben Byer <bbyer@rice.edu>.  -ed]
67 Note that unlike the IRC protocol, each line does NOT end in \r\n.  The
68 <length> field specifies exactly how much data you should read.
70 3.  Message Types
72 The following section describes the format of the <data> section for each
73 specific message type.  Each field is denoted with <>.  The fields in a
74 message are separated by a single space character (ASCII 32).  Where
75 appropriate, examples of the <data> section for each message are given.
77 <type> can be one of the following (converted to big-endian):
79 0       error message [SERVER]
81         Format: <message>
83 2       login [CLIENT]
85         Format: <nick> <password> <port> "<client-info>" <link-type> [ <num> ]
87         <port> is the port the client is listening on for data transfer.  if
88                 this value is 0, it means that the client is behind a firewall
89                 and can only push files outward.  it is expected that requests
90                 for downloads be made using the 500 message (see below)
91         <client-info> is a string containing the client version info
92         <link-type> is an integer indicating the client's bandwidth
93                 0  unknown
94                 1  14.4 kbps
95                 2  28.8 kpbs
96                 3  33.6 kbps
97                 4  56.7 kbps
98                 5  64K ISDN
99                 6  128K ISDN
100                 7  Cable
101                 8  DSL
102                 9  T1
103                 10 T3 or greater
104         <num> build number for the windows client [optional]
105                 
106         Example:
108         foo badpass 6699 "nap v0.8" 3
110 3       login ack [SERVER]
112         Format: <email>
114         the server sends this message to the client after a succesful
115         login (2).  If the nick is registered, the <email> address given at
116         registration time is returned.  If the nick is not registered, a
117         dummy value is returned.
119 4       version check [CLIENT]
121         Format: <version>
123         Server sends [5] if an update is needed. All other responses are
124         ignored.
126         <version> = string, version 2.0b5a sends "2.0"
128 5       "auto-upgrade" [SERVER]
130         Format: <version> <hostname:filename>
132         Napster is out of date, get a new version.
133         Or also known as gaping security hole.
135         <version>  = string, the new version number.
136         <hostname> = string, hostname of upgrade (http) server
137         <filename> = string, filename
139         Connections are always made to port 80.
141         The HTTP Request:
142                 GET <filename> HTTP/1.0
143                 Connection: Keep-Alive
144                 Host: <hostname>
146         Expected HTTP Response.
147                 Content-Length: <size>
148                 Content-Type: <doesn't matter>
149                 <data>
151         Upgrade file is save as "upgrade.exe".
152         And executed as: upgrade.exe UPGRADE "<current.exe>"
154         As far as I can tell no confirmation is requested by Napster when it
155         receives this message.  And immediately start to "auto-upgrade". To keep
156         users informed that Napster is doing something potentially very harmful
157         to their computer it displays a message saying it's "auto-upgrading".
159         I think this pretty bad, since all someone has to do is hack a napster
160         server et voila a zillion clients at your disposal.
162         As far as I known this only affects the Win32 2.0b5a Napster client.
163         Other clients/versions I don't know.
165         [This section was contributed by Thomas van der Heijden <thom@bart.nl>
166         -ed]
168 6       new user login [CLIENT]
170         Format: <nick> <pass> <port> "<client-info>" <speed> <email-address>
172         This message is used when logging in for the first time to register
173         a new nickname.  The client normally checks for an unused nick using
174         the "check nickname" (7) message and upon receipt of a "nickname not
175         registered" (8) from the server will proceceed to log in with this
176         command.
178         note: this message is similar to the 0x02 message, with the addition    
179         of <email-address> on the end
181         Example:
183         foo foo 6699 "nap v0.8" 3 email@here.com
185 7       nick check [CLIENT]
187         Format: <nick>
189         Queries the server to see if <nick> is already registered.  This
190         message is typically used prior to logging in for the first time to
191         check for a valid nickname.
193         Response to this message is one of 8, 9 or 10
195 8       nickname not registered [SERVER]
197         Format: (empty)
199         The server sends this message in response to the "nick check" (7)
200         message to indicate that the specified nickname is not already
201         registered and is ok to use.
203 9       nickname already registered [SERVER]
205         Format: (empty)
207         The server sends this message when the nickname the client has
208         requested has already been registered by another user
210 10 (0x0a)       invalid nickname [SERVER]
212         Format: (empty)
214         This server sends this message in response to the "check nickname"
215         (7) messages when the specified nickname is invalid, usually due to
216         bad characters such as spaces or other non-printable characters.
218         The Napster, Inc. servers only accept (upper- and lower-case) nicks
219         comprised of the following:
220                abcdefghijklmnopqrstuvwxyz1234567890_[]{}-@^!$
222 11      ??? [CLIENT]
224         Format: <nick> <pass>
226         [returns "parameters are unparsable" -ed]
228 12      ??? [SERVER]
230         Format: (empty)
232         this message is returned in response to message 11 from the client
234 13      echo??? [SERVER]
236         Format: <numeric>: [args]
238         Prior to issuing a login (2) command, the server will echo back the
239         received numeric and any arguments of any commands it receives.
241 14      login options [CLIENT]
243         NAME:%s ADDRESS:%s CITY:%s STATE:%s PHONE:%s AGE:%s INCOME:%s EDUCATION:%s
245         Example:
247         NAME: kev  ADDRESS:  CITY: ephrata  STATE: pa  PHONE:  AGE: 60 or older INCOME: $100,000 or more        EDUCATION: Graduate Degree
249 100 (0x64)      client notification of shared file [CLIENT]
251         Format: "<filename>" <md5> <size> <bitrate> <frequency> <time>
253         <md5> see section "MD5"
254         <size> is bytes
255         <bitrate> is kbps
256         <frequency> is hz
257         <time> is seconds
258         
259         Example:
261         "generic band - generic song.mp3" b92870e0d41bc8e698cf2f0a1ddfeac7 443332 128 44100 60
263 102 (0x66)      remove file [CLIENT]
265         Format: <filename>
267         client requests to remove file from shared library
269 110             unshare all files [CLIENT]
271         Format: (empty)
273         Notifies the server that the client is no longer sharing any of the
274         files previously shared.
276 200 (0xc8)      client search request [CLIENT]
278     [FILENAME CONTAINS "artist name"] MAX_RESULTS <max> [FILENAME CONTAINS
279 "song"] [LINESPEED <compare> <link-type>] [BITRATE <compare> "<br>"] [FREQ
280 <compare> "<freq>"] [WMA-FILE] [LOCAL_ONLY]
282         The artist name and the song name are, obviously, treated
283                 the same by the server; confirm this for yourself
284                 on the windows client.
286         max is a number; if it is greater than 100, the server will
287                 only return 100 results.
289         <compare> is one of the following:
290                 "AT LEAST" "AT BEST" "EQUAL TO"
292         <link-type> see 0x02 (client login) for a description
294         <br> is a number, in kbps
296         <freq> is a sample frequency, in Hz
298         LOCAL_ONLY causes the server to only search for files from users on
299                 the same server rather than all linked servers.
301         The windows client filters by ping time inside the client.
302                 It pretty much has to, and it's easy to see the
303                 result by setting ping time to at best 100 ms or
304                 so, and max search terms to 50.  You'll get back
305                 like 3 results, but the client will still tell you
306                 that it found "50 results".
308         Examples:
309                 FILENAME CONTAINS "Sneaker Pimps" MAX_RESULTS 75 FILENAME
310                          CONTAINS "tesko suicide" BITRATE "AT LEAST" "128"
312                 MAX_RESULTS 100 FILENAME CONTAINS "Ventolin" LINESPEED
313                         "EQUAL TO" 10
315         [Thanks to Ben Byer <bbyer@rice.edu> for this contribution.  -ed]
317 201 (0xc9)      search response [SERVER]
319         "<filename>" <md5> <size> <bitrate> <frequency> <length> <nick> <ip>
320         <link-type> [weight]
322         <md5> see secton "MD5"
323         <size> is file size in bytes
324         <bitrate> is mp3 bit rate in kbps
325         <frequency> is sample rate in hz
326         <length> is the play length of the mp3 in seconds
327         <nick> the person sharing the file
328         <ip> is an unsigned long integer representing the ip address of the
329                 user with this file
330         <link-type> see message client login (2) message for a description
331         [weight]        a weighting factor to allow the client to sort the
332                         list of results.  positive values indicate a "better"
333                         match, negative values indicate a "worse" match.
334                         If not present, the weight should be considered to be
335                         0.
337         Example:
339         "random band - random song.mp3" 7d733c1e7419674744768db71bff8bcd 2558199 128 44100 159 lefty 3437166285 4
341 202 (0xca)      end of search response from server [SERVER]
343         Format: (empty)
345 203 (0xcb)      download request [CLIENT]
347         Format: <nick> "<filename>"
349         client requests to download <filename> from <nick>.  client expects
350         to make an outgoing connection to <nick> on their specified data
351         port.
353         Example:
355         mred "C:\Program Files\Napster\generic cowboy song.mp3"
357         SEE ALSO: 500 alternate download request
359 204 (0xcc)      download ack [SERVER]
361         <nick> <ip> <port> "<filename>" <md5> <linespeed>
363         server sends this message in response to a 203 request.
365         <nick> is the user who has the file
366         <ip> is an unsigned long integer representing the ip address
367         <port> is the port <nick> is listening on
368         <filename> is the file to retrieve
369         <md5> is the md5 sum
370         <linespeed> is the user's connection speed (see login(2))
372         Example:
374         lefty 4877911892 6699 "generic band - generic song.mp3" 10fe9e623b1962da85eea61df7ac1f69 3
376 205 (0xcd)      private message to/from another user [CLIENT, SERVER]
378         <nick> <message>
380         note the same type is used for a client sending a msg or recieving one
382         [Commentary: this message causes problems if you consider linking
383         servers together.  With the current one server situation, the server
384         just rewrites the message it receives with the name of the client that
385         sent it and passes it to the recipient client.  However, in the case
386         where the recipient and sender are not on the same server, there is
387         loss of information without encapsulating it.  It would have been
388         better to put both the sender and recipient because if the servers
389         are ever linked they will have to make a new message type for this
390         situation.  -ed]
392 206 (0xce)      get error [SERVER]
394         <nick> "<filename>"
396         the server sends this message when the file that the user has
397         requested to download is unavailable (such as the user is not logged
398         in).
400 207 (0xcf)      add hotlist entry [CLIENT]
402         <user>
404         This message is used to add additional entries to the client's
405         hotlist.  The server will send 209 and 210 messages when a user
406         on the hotlist has logged in or out, respectively.
408 208 (0xd0)      hotlist [CLIENT]
410         <user>
412         This message is used to send the initial list of hotlist entries
413         during the initial login process.  It is normally send prior to
414         to the add file (100) commands.  To add more entries to the hotlist
415         after the initial list is sent, clients should use the 207 message
416         instead.
418 209 (0xd1)      user signon [SERVER]
420         <user> <speed>
422         server is notifying client that a user in their hotlist, <user>,
423         has signed on the server with link <speed>
425 210 (0xd2)      user signoff [SERVER]
427         <user>
429         server is notifying client that a user on their hotlist, <user>, has
430         signed off the server.
432         this message is also sent by the server when the client attempts to
433         browse a nonexistent client.  [why don't they just use 404 for
434         this? -ed]
436 211 (0xd3)      browse a user's files [CLIENT]
438         <nick>
440         the client sends this message when it wants to get a list of the files
441         shared by a specific client
443 212 (0xd4)      browse response [SERVER]
445         <nick> "<filename>" <md5> <size> <bitrate> <frequency> <time>
447         <nick> is the user contributing the file
448         <filename> is the mp3 file contributed
449         <md5> is the has of the mp3 file
450         <size> is the file size in bytes
451         <bitrate> is the mp3 bitrate in kbps
452         <frequence> is the sampling frequency in Hz
453         <time> is the play time in seconds
455         Example:
457         foouser "generic band - generic song.mp3" b92870e0d41bc8e698cf2f0a1ddfeac7 443332 128 44100 60
459 213 (0xd5)      end of browse list [SERVER]
461         <nick> [ip]
463         indicates no more entries in the browse list for <user>.  <ip> gives
464         the client's IP address.
466 214 (0xd6)      server stats [CLIENT, SERVER]
468         client: no data
469         server: <users> <# files> <size>
471         <size> is approximate total library size in gigabytes
472         this message is sent by the server occasionaly without request
474         Example:
476         553 64692 254
478 215 (0xd7)      request resume [CLIENT]
480         <checksum> <filesize>
482         client is requesting a list of all users which have the file with
483         the characteristics.  the server responds with a list of 216 messages
484         for each match, followed by a 217 message to terminate the list
486 216 (0xd8)      resume search response [SERVER]
488         <user> <ip> <port> <filename> <checksum> <size> <speed>
490         this message contains the matches for the resume request (215).  the
491         list is terminated by a 217 message.
493 217 (0xd9)      end of resume search list [SERVER]
495         no data.
497         this messag terminates a list of 216 messages initiated by a 215
498         client request
500 218 (0xda)      downloading file [CLIENT]
502         no body.
504         client sends this message to the server to indicate they are in the
505         process of downloading a file.  this adds 1 to the download count
506         which the server maintains.
508 219 (0xdb)      download complete [CLIENT]
510         no body.
512         client sends this message to the server to indicate they have
513         completed the file for which a prior 218 message was sent.  this
514         subtracts one from the download count the server maintains
516 220 (0xdc)      uploading file [CLIENT]
518         no body.
520         client sends this message to indicate they are uploading a file.
521         this adds one to the upload count maintained by the server.
523 221 (0xdd)      upload complete [CLIENT]
525         no body.
527         client sends this message when they are finished uploading a file.
528         this subtracts one from the upload count maintained by the server.
530 300 (0x12c)     optional ports [CLIENT]
532         <port>
534         This command allows the client to specify optional ports to try for
535         data connections if the one currently in use is unreachable by other
536         parties.
538 301 (0x12d)     hotlist ack [SERVER]
540         <user>
542         server is notifying client that <user> has successfully be added to
543         their hotlist
545 302 (0x12e)     hotlist error [SERVER]
547         <user>
549         server is notifying client that it was unable to add <user> to their
550         hotlist.  [can you only add registered nicks to your hotlist? -ed]
552 303 (0x12f)     remove user from hotlist [CLIENT]
554         <user>
556         client is notifying the server that it no longer wishes to request
557         notifications about <user> when they sign on or off the server.  no
558         response is sent in return.
560 310     ??? [CLIENT, SERVER]
562         client: no data
563         server: 0
565         unknown command.  server returns 0 regardless of any parameters
567 316     client disconnect??? [CLIENT, SERVER]
569         client: no data
570         server: 0
572         The server sends this message with a value of `0' when the client is
573         about to be disconnected.
575         It is unkonwn what this command does when issued by the client.  The
576         server appears to send the 316 message without disconnected the client
577         in this case.
579         [the server seems to send this message if you send it a numeric
580         greater than 1000.  the server will also disconnect you after
581         sending this message.  -ed]
583 320 (0x140)     user ignore list [CLIENT, SERVER]
585         client: no data
586         server: <count>
588         client request to display the list of ignored users.
589         server returns the number of users being ignored
591 321 (0x141)     user ignore list entry [SERVER]
593         <user>
595         server sends each ignored nick in response to a 320 request.  the
596         list is terminated by a 320 message with the number of ignored users.
598 322 (0x142)     add user to ignore list [CLIENT, SERVER]
600         <user>
602         server acks the request by returning the nick
604 323 (0x143)     remove user from ignore list [CLIENT]
606         <user>
608         server acks the request by returning the nick to be removed from
609         the ignore list.
611 324 (0x144)     user is not ignored [SERVER]
613         <user>
615         server indicates that <user> is not currently ignored in response to
616         a 323 request.
618 325 (0x145)     user is already ignored [SERVER]
620         <user>
622         server indicates the specified user is already on the user's ignore
623         list
625 326 (0x146)     clear ignore list [CLIENT, SERVER]
627         client: no data.
628         server: <count>
630         client requests the server clear its ignore list.  server returns the
631         number of entries removed from the ignore list.
633 330 (0x14a)     blocked ip list [CLIENT]
635 332 (0x14c)     block ip [CLIENT]
637 333 (0x14d)     unblock ip [CLIENT]
639 400 (0x190)     join channel [CLIENT]
641         <channel-name>
643         the client sends this command to join a channel
645 401 (0x191)     part channel [CLIENT, SERVER]
647         <channel-name>
649         The client sends this command to part a channel.  Server sends this
650         message to indicate that the client has parted the channel.  Note
651         that this is sometimes sent even when the client has not requested,
652         so a client _must_ be prepared to accept it at any time.
654 402 (0x192)     send public message [CLIENT]
656         <channel> <message>
658 403 (0x193)     public message [SERVER]
660         <channel> <nick> <text>
662         this message is sent by the server when a client sends a public message
663         to a channel.
665         Example:
667         80's espinozaf hello...hola
669 404 (0x194)     error message [SERVER]
671         <text>
673         This message is used to send general error messages to a client that
674         is logged in.  Note: Message 0 is only sent during the login process.
676         Examples:
678         User nosuchuser is not currently online.
679         Channel #nosuchchannel does not exist!
680         permission denied
681         ping failed, blah is not online
683 405 (0x195)     join acknowledge [SERVER]
685         <channel>
687         the server sends this message to the client to acknowlege that it
688         has joined the requested channel (400)
689         
690 406 (0x196)     join message [SERVER]
692         <channel> <user> <sharing> <link-type>
694         <user> has joined <channel>
696         Example:
698         80's WilmaFlinstone 12 2
700 407 (0x197)     user parted channel [SERVER]
702         <channel> <nick> <sharing> <linespeed>
704         Example:
706         80's DLongley 23 7
708 408 (0x198)     channel user list entry [SERVER]
710         this message is identical to the join (406) message.  the server will
711         send the list of users in the channel prior to the client join command
712         in this message.  joins that occur after the client has joined will
713         be noted by a 406 message.
715 409 (0x199)     end of channel user list [SERVER]
717         <channel>
719         this message is sent by the server to indicate it has sent all informati        about the users in a channel
721 410 (0x19a)     channel topic [CLIENT, SERVER]
723         <channel> <topic>
725         sent when joining a channel or a new topic is set.  a client requesting
726         topic change also uses this message.
728         [why didn't they put a field to indicate WHO changed the topic?  as
729         it is now you can only tell that it was changed.  -ed]
731 420 (0x1a4)     channel ban list [CLIENT, SERVER]
733         Format: <channel>
735         This command is used by clients to request the list of channel bans,
736         and by the server to indicate the end of the channel ban list for
737         a channel (also see 421).
739 421 (0x1a5)     channel ban list entry [SERVER]
741 422 (0x1a6)     channel ban [CLIENT]
743         <channel> <user|ip> [ "<reason>" ]
745 423 (0x1a7)     channel unban [CLIENT]
747         <channel> <user|ip> [ "<reason>" ]
749 424 (0x1a8)     channel ban clear [CLIENT]
751         Format: <channel>
753 425     channel motd (alternate topic (?)) [SERVER]
755         Format: <message>
757         [The server sends this command when a user joins one of the
758         predefined channels.  It seems to send a default message if the
759         topic for the channel is the default, otherwise it sends the current
760         channel topic.  -ed]
763 430     invite a user [CLIENT, SERVER]                                                 
764         client: <nick> <channel>                                               
765         server: <nick> <channel> "<topic>" <unknown_digit> <unknown_text>       
766                                                                                 
767         This command is used by Napster 2.0 BETA 9.6 to invite a user to        
768         a channel.                                                              
769         client:                                                                 
770                 <nick> - nick of invited user                                   
771                 <channel> - channel user <nick> was invited to                  
772         server:                                                                 
773                 <nick> - nick of user who was inviting                          
774                 <channel> - channel                                             
775                 <topic> - channel's topic                                       
776                 <unknown_digit> - ??? ("0" works fine)                          
777                 <unknown_text> - ??? ("Hello!" works fine)                      
778                                                                                 
779                 Last two arguments i cannot check because i temporary           
780                 don't have internet access (e-mail only). If someone            
781                 will test this message on napster.com servers please            
782                 send me results.                                                
783                                                                                 
784         When user receives 430 message user should reply with 431 or 432.       
785                                                                                 
786         Client example:                                                         
787                                                                                 
788         CyberAlien2 #test_channel                                               
789                                                                                 
790         Server  example:                                                        
791                                                                                 
792         CyberAlien3 #test_channel "Welcome to the #test_channel." 0 Hello!      
793                                                                                 
794         !!! If anyone known what should server reply instead of "0 Hello!"      
795         please tell me.                                                         
796                                                                                 
797                                                                                 
798 431     invitation accepted [CLIENT]                                                    
799         <user> <channel>                                                        
800                                                                                 
801         <user> - user who was inviting                                          
802                                                                                 
803 432     invitation declined [CLIENT]
805         format: copy of command received in 430 message                         
807 500 (0x1f4)     alternate download request [CLIENT]
809         <nick> "<filename>"
811         requests that <nick> make an outgoing connection to the requesters
812         client and send <filename>.  this message is for use when the
813         person sharing the file can only make an outgoing tcp connection
814         because of firewalls blocking incoming messages.  this message should
815         be used to request files from users who have specified their data
816         port as 0 in their login message
818 501 (0x1f5)     alternate download ack [SERVER]
820         <nick> <ip> <port> "<filename>" <md5> <speed>
822         this message is sent to the uploader when their data port is set to
823         0 to indicate they are behind a firewall and need to push all data
824         outware.  the uploader is responsible for connecting to the
825         downloader to transfer the file.
827 600 (0x258)     request user's link speed [CLIENT]
829         <nick>
831 601 (0x259)     link speed response [SERVER]
833         <nick> <linespeed>
835 602 (0x25a)     ??? [CLIENT]
837         <?>
839         server returns a 404 with "*gulp* Drink milk, it does a body good!"
841 603 (0x25b)     whois request [CLIENT]
843         <nick>
845 604 (0x25c)     whois response [SERVER]
847         <nick> "<user-level>" <time> "<channels>" "<status>" <shared>
848         <downloads> <uploads> <link-type> "<client-info>" [ <total downloads>
849         <total_uploads> <ip> <connecting port> <data port> <email> ]
851         <user-level> is one of "User", "Moderator", "Admin" or "Elite"
852         <time> is seconds this user has been connected
853         <channels> is the list of channels the client is a member of, each
854                 separated by a space (ASCII 32)
855         <status> is one of "Active", "Inactive" (offline) or "Remote" (on a
856                 different server)
857         <shared> is number of files user has available for download
858         <downloads> is the current number of downloads in progress
859         <uploads> is the current number of uploads in progress
860         <link-type> see 0x02 (client login) above
861         <client-info> see 0x02 (client login) above
863         The following fields are displayed for user level moderator and
864         above:
866         <total uploads>
867         <total downloads>
868         <ip>                    note: can be "unavailable"
869         <connecting port>
870         <data port>
871         <email>                 note: can be unavailable
873         Example:
875         lefty "User" 1203 "80's " "Active" 0 0 0 3 "nap v0.8"
877 605 (0x25d)     whowas response [SERVER]
879         <user> <level> <last-seen>
881         if the user listed in a 603 request is not currently online, the
882         server sends this message.
884         <user> is the user for which information was requested
885         <level> is the user's last known userlevel (user/mod/admin)
886         <last-seen> is the last time at which this user was seen, measured
887                 as seconds since 12:00am on January 1, 1970 (UNIX time_t).
889 606 (0x25e)     change user level [CLIENT]
891         <nick> <level>
893         changes the privileges for <nick> to <level>.  client must be admin
894         level to execute this request
896         [I have not verified this message since I don't have admin status
897         on any of the servers.  -ed]
899 607 (0x25f)     upload request [SERVER]
901         <nick> "<filename>" <speed>
903         this message is used to notify the client that user <nick> has
904         requested upload of <filename>
906         Example:
908         lefty "generic band - generic song.mp3" 7
910 608 (0x260)     accept upload request [CLIENT]
912         <nick> "<filename>"
914         client is notifying server that upload of <filename> to <nick> is
915         accepted, and that the requesting client may begin download
917         Example:
919         lefty "generic band - generic song.mp3"
921 609 (0x261)     accept failed [SERVER]
923         <nick> "<filename>"
925         this message is sent by the server when the client that the file was
926         requested from does not accept the upload request.
928 610 (0x262)     kill (disconnect) a user [CLIENT]
930         <nick> [ "<reason>" ]
932         client request to disconnect a user.
934 611 (0x263)     nuke a user [CLIENT]
936         <nick>
938         client request to delete account for <nick>
940 612 (0x264)     ban user [CLIENT]
942         <nick | ip> [ "<reason>" ]
944         client request to place a ban on either a specific nickname or
945         an ip address
947 613 (0x265)     set data port for user [CLIENT, SERVER]
949         client: <user> <port>
950         server: <port>
952         This command is used by administrators to request that another
953         client set the port used for data transfers to <port>.  The server
954         sends a message with the requested port number to the target
955         client.  NOTE: the target client can change its port number to
956         whatever it wishes using the 703 command.
958 614 (0x266)     unban user [CLIENT]
960         Format: <nick | ip> [ "<reason>" ]
962 615 (0x267)     show bans for server [CLIENT]
964         Format: (empty)
966         client requests the list of banned ips for the current server
968 616 (0x268)     (ip?) ban list entry [SERVER]
970         Format: <ip> <nick> "<reason>" <time> <n>
972         <ip> is the string version of the ip banned
973         <nick> is the user setting the ban
974         <reason> is the reason given
975         <time> is the time_t when the ban was set
976         <n> is ???.  value is either 0 or 1
978         This message is sent in response to the 615 client request, one
979         for each ban.  The list is terminated with a 0 length 615 message
980         from the server.
982         Example:
983         
984         207.172.245. valkyrie "DoS exploit" 947304224 0
986 617 (0x269)     list channels [CLIENT, SERVER]
988         Format: (empty)
990         client requests a list of channels on the server.  server responds
991         with 618/617
993         server indicates end of channel list using this message.
995 618 (0x26a)     channel list entry [SERVER]
997         Format: <channel-name> <number-of-users> <topic>
999         this is the server response to a 617 client request, one for each
1000         channel.
1002         Example:
1004         Help 50 OpenNap help channel
1006 619 (0x26b)     queue limit [CLIENT]
1008         Format: <nick> "<filename>" <n>
1010         a client may limit the number of downloads from a particular client.
1011         once the limit for a particular user has been reached, the uploading
1012         client can send this message to notify the downloader that they
1013         have hit the limit and can't have any more simultaneous downloads.
1014         <nick> is the user who hit the limit, <filename> is the file they
1015         were trying to download when they hit the limit, and <n> is the
1016         number of simultaneous downloads allowed.
1018         Example:
1020         joebob "C:\MP3\Generic Band - Generic Song.mp3" 3
1022 620 (0x26c)     queue limit [SERVER]
1024         <nick> "<filename>" <filesize> <digit>
1026         This message is sent by the server in response to the 619 client
1027         request, when one user needs to notify another that they have
1028         reached the maximum allowed simultaneous downloads.  When the server
1029         recieves the 619 request from the uploading client, it sends the 620
1030         message to the downloading client.  The only difference in format is
1031         the addition of the <nick> field in the 620 message which specifies
1032         the username of the uploading agent which is notifying the
1033         downloader that the queue is full.
1035         Example:
1037         joebob "C:\MP3\Generic Band - Generic Song.mp3" 1234567 3
1039 621 (0x26d)     message of the day [CLIENT, SERVER]
1041         <text>
1043         Server: each 621 message contains a single line of text
1045         Client: client sends a 621 command with no data to request the
1046         motd be sent.  The server will usually send this automatically after
1047         a user logs in, so this command allows a user to reread it upon
1048         request.
1050 622 (0x26e)     muzzle a user [CLIENT]
1052         <nick> [ "<reason>" ]
1054         client requests that <nick> not be allowed to send public messages
1056 623 (0x26f)     unmuzzle a user [CLIENT]
1058         <nick> [ "<reason>" ]
1060         client requests that the enforced silence on <nick> be lifted
1062 624 (0x270)     un-nuke a user [CLIENT]
1064         <user>
1066 625 (0x271)     change a user's linespeed [CLIENT]
1068         <user> <speed>
1070 626 (0x272)     data port error [CLIENT, SERVER]
1072         <user>
1074         When a downloading client detects that the uploader's data port
1075         is unreachable, it should send a 626 message to the server with
1076         the nick of the user for which the connection failed.  The server
1077         then relays the message to the uploader, substituing the
1078         downloader's nickname in the message.
1080 627 (0x273)     operator message [CLIENT, SERVER]
1082         client: <text>
1083         server: <nick> <text>
1085         client request to send a message to all admins/moderators
1087 628 (0x274)     global message [CLIENT, SERVER]
1089         client: <text>
1090         server: <nick> <text>
1092         client request send a message to all users
1094 629 (0x275)     banned users [SERVER]
1096         Format: <nick>
1098         when displaying the ban list for the server, this message is used
1099         to indicate banned nicknames.
1101 630-639 missing
1103 640     direct browse request [CLIENT, SERVER]
1105         Client: <nick>
1106         Server: <nick> [ip port]
1108         Client: request files for <nick>
1109         Server: <nick> is requesting your files.  optionally, <ip> and
1110                 <port> are given if the client getting browsed is firewalled
1112         This message is sent to initiate a direct client to client browsing of
1113         shared files.
1115         See section 5.3.
1117 641     direct browse accept [CLIENT, SERVER]
1119         Client: <nick>
1120         Server: <nick> <ip> <port>
1122         The client to be browsed sends this message back to the server to
1123         indicate it is willing to accept a direct browse from <nick>.
1125         The server sends this message to the requestor of the browse to
1126         indicate where it should connect in order to do a direct browse from
1127         <nick>.
1129         See section 5.3
1131 642     direct browse error [SERVER]
1133         <nick> "message"
1135         Server sends this messags in response to a 640 request if there is an
1136         error (eg. both clients are firewalled, or the browsee is not sharing
1137         any files).
1139         See section 5.3
1141 643-649 missing
1143 650-651 ??? [CLIENT]
1145         permission denied.
1147 652 (0x28c)     cloak user [CLIENT]
1149         sets the current user to "invisible"
1151 653-699 missing.
1153 700     change link speed [CLIENT]
1155         <speed>
1157         client is notifying server that its correct link speed is <speed>,
1158         in the range 0-10 (see the login message for details).
1160 701     change user password [CLIENT]
1162         <password>
1164         client wishes to change their password
1166 702     change email address [CLIENT]
1168         <email address>
1170         client wishes to change their email address
1172 703     change data port [CLIENT]
1174         <port>
1176         client is changing the data port being listened on for file
1177         transfers
1179 704-747 missing.
1181 748     login attempt [SERVER]
1183         the server sends this message to a logged in client when another
1184         client attempts to log in with the same nickname.
1186 749     missing.
1188 750 (0x2ee)     server ping [CLIENT, SERVER]
1190         server: none
1191         client: <user>
1193         Napster 2.0b5a sends the username in a response to a 750 from the
1194         server.
1196         [server returns an empty 750 command in response. server ping? -ed]
1198 751 (0x2ef)     ping user [CLIENT, SERVER]
1200         <user>
1202         client is attempting to determine if <user>'s connection is alive
1204 752 (0x2f0)     pong response [CLIENT, SERVER]
1206         <user>
1208         this message is sent in response to the the 751 (PING) requeset
1210 753 (0x2f1)     change password for another user [CLIENT]
1212         <user> <password> "<reason>"
1214         allows an administrator to change the password for another user
1216 754-769 missing.
1218 770     ??? [CLIENT]
1220         permission denied.
1222 771     ??? [CLIENT]
1224         permission denied.
1226 772-799 missing.
1228 800 (0x320)     reload config [CLIENT]
1230         <config variable>
1232         resets configuration parameter to its default value
1234 801 (0x321)     server version [CLIENT]
1236         no data.
1238         client request's a server's version
1240 802-804 missing.
1242 805     ???
1244         [returns permission denied. -ed]
1246 810 (0x32a)     set config [CLIENT]
1248         <config string>
1250         request a change in server configuration variables
1252 811 (0x32b)     ???     [CLIENT]
1254         [returns permission denied. -ed]
1256 820 (0x334)     clear channel [CLIENT]
1258         <channel>
1260         remove all users from the specified channel
1262 821 (0x335)     redirect client to another server [CLIENT, SERVER]
1264         client: <user> <server> <port>
1265         server: <server> <port>
1266         
1267         This command allows an administrator to redirect clients to another
1268         server.
1270 822 (0x336)     cycle client [CLIENT, SERVER]
1272         client: <user> <metaserver>
1273         server: <metaserver>
1275         This commands allows an administrator to make a client restart the
1276         login process by first connecting to the metaserver (redirector) at
1277         <host>.
1279 823 (0x337)     set channel level [CLIENT]
1281         <channel> <level>
1283         Sets <channel> such that users must be at least <level> in order to
1284         enter the channel
1286 824 (0x338)     emote [CLIENT, SERVER]
1288         client: <channel> "<text>"
1289         server: <channel> <user> "<text>"
1291         A variation of the public message command to indicate an action by
1292         the user.  Often implemented as the "/me" command in IRC clients.
1294 825 (0x339)     user list entry [SERVER]
1296         <channel> <user> <files shared> <speed>
1298         an 825 message is sent for each user in the channel specified by the
1299         830 message
1301         Example:
1303         Help testor3 0 3
1305         [This appears to be exactly the same format as the 408 message.  -ed]
1307 826 (0x33a)     channel limit [CLIENT]
1309         <channel> <limit>
1311         sets the maximum number of users that may enter a channel.  <limit>
1312         is an integer value between 0 and 999999999.  setting it higher that
1313         this results in the limit being set to -1.  by default, created
1314         channels have a limit of 200.  there appears to be no restriction on
1315         any channel member changing the limit, and no notification is given
1317 827 (0x33b)     show all channels [CLIENT, SERVER]
1319         no data.
1321         client request to show all channels, including "hidden" channels.
1322         the server also sends this message to terminate
1324 828 (0x33c)     channel list [SERVER]
1326         <channel> <users> <n1> <level> <limit> "<topic>"
1328         the server sends a list of 828 commands, one for each channel,
1329         including "hidden" channels that don't show up in the normal channel
1330         list.
1332         <level> is the mimimum user level required for entry into a channel
1333         <limit> is the max number of users allowed in a channel
1335         <n1> is either 0 or 1.  seems to be 1 if the channel was user
1336         created, or 0 if a predefined channel???
1338 829 (0x33d)     kick user from channel [CLIENT]
1340         <channel> <user> [ "<reason>" ]
1342 830 (0x33e)     list users in channel [CLIENT, SERVER]
1344         <channel>
1346         client requests a list of all users in <channel>.  server responds
1347         with a 825 response for each user, followed by an 830 response with
1348         no data [why didn't they just use the 409 message? -ed]
1350 831 (0x33f)     global user list [CLIENT]
1352         [returns permission denied.  -ed]
1354 832-869 missing.
1356 870     add files by directory [CLIENT]
1358         Format: "<directory>" "<file>" <md5> <size> <bitrate> <freq> <duration>
1359         [ ... ]
1361         This command allows a client to share multiple files in the same
1362         directory as a shortcut to multiple 100 (share file) commands.
1363         <directory> is the path which should be prepended to all the given
1364         filenames in the rest of the command.  <file> is the name of the file
1365         to share *without* its directory component.  When other clients do a
1366         browse/share, the real path will be reported as <directory>/<file>.
1368         The portion of this command after the <directory> may be repeated as
1369         many times as necessary for files in the same directory. NOTE: most
1370         servers will not accept commands of length longer than 2048 bytes
1371         so you still may need to break up the files into multiple commands
1372         if there are many files in a single directory.
1374 871-899 missing.
1376 900     connection test [SERVER]
1378         <ip> <port> <data>
1380         <ip>   - string,  ip address to connect to.
1381         <port> - integer, port to connect to
1382         <data> - string,  data to send to server.
1384         Try to connect to <ip> on <port> for atmost 1000 seconds.  If the
1385         connection succeeds send the <data> to target.
1387         [reported by Thomas van der Heijden <thom@bart.nl>]
1389 901     listen test [SERVER]
1391         <port> <timeout> <data>
1393         <port>    - integer, port to listen on
1394         <timeout> - integer, time to wait for connection in seconds
1395         <data>    - string,  data to send after connection has been made.
1397         Listen on <port> for <timeout> seconds. If a connection arrives,
1398         return <data> to sender.
1400         [reported by Thomas van der Heijden <thom@bart.nl>]
1402 920     ??? [CLIENT]
1404         Format: 1
1406         This is sent by the BETA8 client prior to login.  Purpose unknown.
1408 3.  MD5
1410 It looks like the vast majority of the files are hashed using the first
1411 299,008 bytes of the file.  There have been some cases where the hash
1412 matches at 300,032 bytes, but no correlation has been drawn as to when that
1413 happens.  The speculation at this point is that it might have to do with
1414 the existence of a ID3v2 tag, or perhaps the file was sampled at 48kHz...?
1416 The current method seems to be: skip id3v2, seek to frame sync and hash.
1418 Note: the linux nap client (versions 0.7 - 0.9) seem to hash exactly 300,000
1419 bytes, which is NOT what the official windows client does.
1421 More recent Napster clients seem to send the string WMA-FILE as the checksum
1422 instead of the actual hash value for .wma files.
1424 5.  Client-Client Protocol
1426 File transfer occur directly between clients without passing through the
1427 server.  There are four transfer modes, upload, download, firewalled upload,
1428 firewalled download.  The normal method of transfer is that the client
1429 wishing to download a file makes a TCP connection to the client holding the
1430 file on their data port.  However, in the case where the client sharing the
1431 file is behind a firewall, it is necessary for them to "push" the data by
1432 making a TCP connection to the downloader's data port.
1434 5.1  Normal Downloading
1436 Regardless of which mode, the downloading client will first issue either a 
1437 search(200) or browse(211) command to the server.  This returns a list of
1438 files and information on the client sharin the file.  To request a download,
1439 a get(203) request is sent to the server.  The server will respond with
1440 a get ack(204) containing more detailed information.
1442 This is the point at which the different methods diverge.  If the 204 get
1443 ack says that the remote clients data port is 0, you must send a 500 request
1444 to the server requesting that the remote client send the data to you.  In
1445 this case you wait for the remote client to connect to your own data port.
1447 In the case where the sharing client is not firewalled, you make a TCP
1448 connection to the data port specified in the 204 message from the server.
1449 The remote client should accept the connection and immediately send one
1450 ASCII char, `1' (ASCII 49).  Once you read this char, you send a request
1451 for the file you wish to download.  First send the string "GET" in a single
1452 packet, then send
1453         <mynick> "<filename>" <offset>
1454 where <mynick> is your napster user name, <filename> is the file you wish to
1455 download, and <offset> if the byte offst in the file to begin the transfer
1456 at (if you are downloading for the first time, and not resuming a prior
1457 transfer, you should uses 0 to start at the beginning of the file).
1459 The remote client will then return the file size, or an error message such
1460 as "INVALID REQUEST" or "FILE NOT SHARED".  Note that the file size is not
1461 terminated in any special way, and the best way to figure out the size is to
1462 keep reading until you hit a character that is not a digit (it will usually
1463 be 0xff which is the start of the MP3 frame sync header, but if a ID3v2
1464 tag is present it might look different).  Immediately following the file
1465 size is where the data stream for the file begins.
1467 Once the data transfer is initiated, the downloader should notify the server
1468 that they are downloading a file by sending the 218 message.  Once the
1469 transfer is complete, you send a 219 message to indicate you have finished
1470 the download.  Note that this is cummalitive, so that if you are downloading
1471 multiple files, you send one 218/219 pair for EACH concurrent download--this
1472 is how the server knows how many transfers you have going on.  Likewise,
1473 the uploader should send one 220 messge for each upload, and one 221 when
1474 each upload has finished.
1476 5.2  Firwalled Downloading
1478 As described above, when the file needs to be pushed from a client behind a
1479 firewall, the downloader sends a 500 message to the server.  This causes a
1480 501 message to be sent to the uploader, which is similar to the 204 message
1481 for a normal download.
1483 Once the uploader receives the 501 message from the server, they should make
1484 a TCP connection to the downloader's data port (given in the 501 message).
1485 Upon connection, the downloader's client will sent one byte, the ASCII
1486 character `1'.  The uploader should then send the string "SEND" in a single
1487 packet, and then the information:
1488         <mynick> "<filename>" <size>
1489 where <mynick> is the uploader's napster user name, <filename> is the file
1490 being sent, and <size> is the size of the file in bytes.
1492 Upon receipt, the downloading client will either send the byte offset at
1493 whcih the transfer should start, or an error message such as
1494 "INVALID REQUEST".  The byte offset should be sent as a single packet
1495 in plain ASCII digits.  Just as with above in section 4.1, a 0 byte offset
1496 indicates the transfer should begin at the start of the file.
1498 Each client should notify the server that they are uploading or downloading
1499 with the 218/219 (downloading) or 220/221 (uploading) command pairs (see
1500 section 4.1 for more detailed information).
1502 5.3 Client to Client Browsing
1504 Napster 2.0 BETA 8 adds a feature which allows direct client-to-client
1505 browsing of file lists.  To request a browse, a client uses the
1506         640 <nick>
1507 command.  The server then sends a
1508         640 <requester>
1509 to the client which is getting browsed with the nick of the client that is
1510 requesting the browse.  If the client accepts the browse request, it sends
1511 back a
1512         641 <requestor>
1513 to the server with the nick of the client requesting the browse.  The
1514 server then sends a
1515         641 <nick> <ip> <port>
1516 to the requesting client.  In the case of an error, the server will send a 642
1517 command in response to the 640 command.
1519 The browsing client then makes a TCP conection to the remote client's data
1520 port.  After getting the "1" character, the browsing client sends a
1521         GETLIST
1522 At which point the remote client sends its nick followed by a linefeed (\n)
1523 by itself in a single packet (ie, one write() call)
1524         <nick> LF
1525 followed by the list of files being shared (the format being the same as
1526 the data of the "share" command).  Each line is terminated by a linefeed char.
1527 At the end of the list, an additional linefeed char is sent and then the
1528 client closes the connection.
1530 In the case that the remote client is firewalled, the browse list will have to
1531 be pushed to the requesting client.  The remote client makes a TCP connection
1532 to the requesting client, then sends
1533         SENDLIST <nick>\n
1534 followed by the list of files, as with the "GETLIST" command response.
1536 6.  Where to get more help?
1538 Join the napdev mailing list by sending email to napdev-subscribe@onelist.com
1539 or by visiting the community page http://www.onelist.com/community/napdev/.
1540 This list is designed for open source napster developers to share information
1541 about the specification or applications.
1543 7.  Acknowledgements
1545 A big THANKS goes to the following people who contributed valuable information
1546 to this specification:
1548 Ben Byer <bbyer@rice.edu>
1549 JT <jtraub@dragoncat.net>
1550 Evan Martin <eeyem@u.washington.edu>
1551 Colten Edwards (aka panasync@efnet) <edwards@bitchx.dimension6.com>
1552 Thomas van der Heijden <thom@bart.nl>