napster.txt

P2P NAP的C实现 P2P在网络应用中越来越流行

Nap protocol specification
==========================

By [e-mail]
19 March 2002

Original by [e-mail]
April 7, 2001

0.  Foreward by Dr. Scholl

This is meant to be an open specification.  If you find errors or know of
additional functionality not described hereafter, please send me email.
It benefits the entire community to have a complete and accurate protocol
specification. Not only does it allow for clients to be developed for any
platform, but also decreases the strain on the server having to parse out
bad client messages.

0.1  Foreward by CyberAlien

Original document is created by Dr.Scholl. I have fixed some messages,
added OpenNap and SlavaNap messages and extentions to messages, added
Napigator protocol specification.
If you have any comments please mail me at mailto:[e-mail]

1.  Recent Changes

* Fixed napigator protocol (12 October 2001)
* Fixed commands 100, 110 (12 October 2001)
* Updated to match opennap 0.44 and slavanap 2.0.0 capabilities (14 Dec 2001)
* Fixed description of ban command [612] (19 March 2002)

2.  Client-Server protocol

Nap protocol uses TCP for client to server communication.  Typically the
servers run on ports 8888 and 7777.  Note that this is different from the
`metaserver' (or redirector) which runs on port 8875.
Note: Napster 10.3 and older use port 8876 instead of 8875.

each message to/from the server is in the form of
	<length><type><data>
where <length> and <type> are 2 bytes each.  <length> specifies the length in
bytes of the <data> portion of the message.  Be aware that <length> and <type>
appear to be in little-endian format (least significant byte goes first).  For
example, in the C language you would encode the number 1 as
	const unsigned char num[2] = { 0x01, 0x00 };
and 256 would be encoded as
	const unsigned char num[2] = { 0x00, 0x01 };
[The above is for illustrative purposes only, there are much quicker ways to
actually encode a number. -ed]
The <data> portion of the message is a plain ASCII string.

Napster Beta 10.3+ use big-endian format instead of little-endian.
This means that 256 would be encoded as { 0x01, 0x00 }
and 1 as { 0x00, 0x01 };

Note that in many cases, strings are passed as double-quoted entries.  For
example, filenames and client id strings are always sent as
	"random band - generic cowboy song.mp3"
or
	"nap v0.8"
Where required, double quotes are used in the description of the messages
below.

Some additional information about use of quotes inside of quotes:
> The answer is, no, it doesn't do escaping of quotes.  If you try searching
> for the phrase 'a "quoted" string' on the windows client, you get no songs
> found, and "invalid search request" printed in yellow in your console
> window.  (don't know what code that is, sorry.)
>
> and no wonder-- a little birdie told me that the client sends this:
>
> FILENAME CONTAINS "a "quoted" string" MAX_RESULTS 100

[contributed by Ben Byer <[e-mail]>.  -ed]

Note that unlike the IRC protocol, each line does NOT end in \r\n.  The
<length> field specifies exactly how much data you should read.

3.  Message Types

The following section describes the format of the <data> section for each
specific message type.  Each field is denoted with <>.  The fields in a
message are separated by a single space character (ASCII 32).  Where
appropriate, examples of the <data> section for each message are given.

[SERVER] means that message is sent by server
[CLIENT] means that message is send by client
[NAPSTER] means that Napster client or server uses this message
[OPENNAP] means that this message is supported by OpenNap 0.44
[SLAVANAP] means that this message is supported by SlavaNap 2.0.0

Detecting server type is easy. When user logs in server sends MOTD
and OpenNap and SlavaNap sends string "VERSION opennap 0.44" or
"VERSION SlavaNap 2.0.0" among other MOTD strings.

<type> can be one of the following (converted to big-endian):

0	error message [SERVER]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: <message>

2	login [CLIENT]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: <nick> <password> <port> "<client-info>" <link-type> [ <num> ]

	<port> is the port the client is listening on for data transfer.  if
		this value is 0, it means that the client is behind a firewall
		and can only push files outward.  it is expected that requests
		for downloads be made using the 500 message (see below)
	<client-info> is a string containing the client version info
	<link-type> is an integer indicating the client's bandwidth
		0  unknown
		1  14.4 kbps
		2  28.8 kpbs
		3  33.6 kbps
		4  56.7 kbps
		5  64K ISDN
		6  128K ISDN
		7  Cable
		8  DSL
		9  T1
		10 T3 or greater
	<num> build number for the windows client [optional]
		
	Example:

	foo badpass 6699 "nap v0.8" 3

3	login ack [SERVER]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: <email> [<number>]

	the server sends this message to the client after a succesful
	login (2).  If the nick is registered, the <email> address given at
	registration time is returned.  If the nick is not registered, a
	dummy value is returned.

	<number> is added by Napster server.
		This is probably user's number.

4	version check [CLIENT] [SERVER]

	[NAPSTER,OPENNAP,SLAVANAP]

        Format: <version>

	Server sends [5] if an update is needed and [4] if not.

	<version> = string, version 2.0b5a sends "2.0"

5       "auto-upgrade" [SERVER]

	[NAPSTER]

        Format: <version>
        Beta5 Format: <version> <hostname:filename>

        Napster is out of date, get a new version.
        Used to be gaping security hole in Beta5.

        <version>  = string, the new version number.
        <hostname> = string, hostname of upgrade (http) server
        <filename> = string, filename

	<hostname> and <filename> are used only by Beta5
	Later versions ignore these values.

6	new user login [CLIENT]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: <nick> <pass> <port> "<client-info>" <speed> <email-address>

	This message is used when logging in for the first time to register
	a new nickname.  The client normally checks for an unused nick using
	the "check nickname" (7) message and upon receipt of a "nickname not
	registered" (8) from the server will proceceed to log in with this
	command.

	note: this message is similar to the 0x02 message, with the addition	
	of <email-address> on the end

	Example:

	foo foo 6699 "nap v0.8" 3 [e-mail]

7	nick check [CLIENT]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: <nick>

	Queries the server to see if <nick> is already registered.  This
	message is typically used prior to logging in for the first time to
	check for a valid nickname.

	Response to this message is one of 8, 9 or 10

8	nickname not registered [SERVER]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: (empty)

	The server sends this message in response to the "nick check" (7)
	message to indicate that the specified nickname is not already
	registered and is ok to use.

9	nickname already registered [SERVER]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: (empty)

	The server sends this message when the nickname the client has
	requested has already been registered by another user

10 (0x0a)	invalid nickname [SERVER]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: (empty)

	This server sends this message in response to the "check nickname"
	(7) messages when the specified nickname is invalid, usually due to
	bad characters such as spaces or other non-printable characters.

        The Napster, Inc. servers only accept (upper- and lower-case) nicks
        comprised of the following:
               abcdefghijklmnopqrstuvwxyz1234567890_[]{}-@^!$

11	password check [CLIENT]

	[NAPSTER,SLAVANAP]

	Format: <nick> <pass>

	This command is used by Napster only during setup sequence.
	If password is correct server replies with message 12. If not
	server sends message 0.

12	password OK [SERVER]

	[NAPSTER,SLAVANAP]

	Format: (empty)

	this message is returned in response to message 11 from the client

13	echo??? [SERVER]

	[NAPSTER]

	Format: <numeric>: [args]

	Prior to issuing a login (2) command, the server will echo back the
	received numeric and any arguments of any commands it receives.

14	login options [CLIENT]

	[NAPSTER]

	NAME:%s ADDRESS:%s CITY:%s STATE:%s PHONE:%s AGE:%s INCOME:%s EDUCATION:%s

	Example:

	NAME: kev  ADDRESS:  CITY: ephrata  STATE: pa  PHONE:  AGE: 60 or older INCOME: $100,000 or more        EDUCATION: Graduate Degree

	No reply is required.

15	Same as 14. Used by Beta7+ (I don't know if previous versions used command 15 or not)

	[NAPSTER]

100 (0x64)	client notification of shared file [CLIENT]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: "<filename>" <md5> <size> <bitrate> <frequency> <time>

	<md5> see section "MD5"
	<size> is bytes
	<bitrate> is kbps
	<frequency> is hz
	<time> is seconds
	
	Example:

	"generic band - generic song.mp3" b92870e0d41bc8e698cf2f0a1ddfeac7-443008 443332 128 44100 60

	For sharing non-mp3 files there is a command 10300 that is supported
	by OpenNap and SlavaNap, but most clients use command 100 (or 870)
	and just set bitrate=24 freq=16000 time=600.

102 (0x66)	remove file [CLIENT]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format: <filename>

	client requests to remove file from shared library

110		unshare all files [CLIENT, SERVER]

	[NAPSTER,OPENNAP,SLAVANAP]

	client: (empty)
	server: <num>

	Notifies the server that the client is no longer sharing any of the
	files previously shared. Server replies with 110 containing number
	of files that client shared before.

200 (0xc8)	client search request [CLIENT]

	[NAPSTER,OPENNAP,SLAVANAP]

	Format:

	[FILENAME CONTAINS "artist name"] MAX_RESULTS <max> [FILENAME CONTAINS
	"song"] [LINESPEED <compare> <link-type>] [BITRATE <compare> "<br>"] [FREQ
	<compare> "<freq>"] [WMA-FILE] [LOCAL_ONLY]

	For OpenNap and SlavaNap only:

	[TYPE <mime-type>] [FILENAME EXCLUDES "exclude string"] [SIZE <compare>
	<filesize_in_bytes>] [DURATION <compare> <song_duration_in_seconds>]

	For SlavaNap 2.x only:

	[SHOW_QUEUE] [SHOW_SOFTWARE]	



        The artist name and the song name are strings filename should include.
	There is no difference between artist name and song name.

        <max> is a number; if it is greater than 100, Napster server will only return
	100 results. With OpenNap and SlavaNap <max> can be greater than 100.

        <compare> is one of the following:
                "AT LEAST" "AT BEST" "EQUAL TO"

        <link-type> integer ranging from 1 to 10. see 0x02 (client login) for a description.

        <br> is a number, in kbps

        <freq> is a sample frequency, in Hz

	<mime-type> OpenNap and SlavaNap support other media types besides mp3.
		By default, searches will only match mp3 files.  A client can
		however search for other media types by specifying a partial
		MIME content-type (audio, video, text, application, image, mp3).
		(See message 10300 for adding media to the database).
		The special keyword `any' will match any media type in the
		database.

		The results of the search are returned as with mp3, except
		the fields for bitrate, sample frequency and length are
		meaningless. The client can then download as they would any
		other mp3 file.

	FILENAME EXCLUDES "..."

		allows filtering search results by excluded all files which
		match words in an exclude list.  this must be used in
		conjunction with FILENAME CONTAINS "...".
		(NOTE: as of Napster 2.0 BETA 8, words in the
		FILENAME CONTAINS string which are prefixed with a minus
		sign (-) are considered to be exclusive.)
		Can be used only with OpenNap and SlavaNap servers.

	SIZE, DURATION

		allows matching on the file size and song length in addition
		to the other file attributes. Can be used only with OpenNap
		and SlavaNap servers.

	LOCAL_ONLY causes the server to only search for files from users on
		the same server rather than all linked servers.

	SHOW_QUEUE this works only with SlavaNap 2.x servers. if causes server
		to add number of queued items for remote user to each search result.
		if remote user's software doesn't show queue server will add "n/a"
		instead of queue. otherwise server will return number counted
		with the following simple algorythm:
		 current_uploads + queued_uploads - max_uploads;
		so, if you can download from remote user without entering queue
		server will return any negative number, if user has maximum
		uploads right now server will return number of queued items.
		To set number of queued items use SlavaNap's command 8112. You
		can also retreive number of queued items using SlavaNap's command
		8113 instead of adding "SHOW_QUEUE" to search request.
		See also "readme.txt" in SlavaNap.

	SHOW_SOFTWARE this works only with SlavaNap 2.x servers. if causes server
		to add client's software signature to search result. This might
		be used if your client has its own special protocol and you
		don't want to disturb other clients with messages that other
		client wouldn't understand.
		If you use both "SHOW_QUEUE" and "SHOW_SOFTWARE" in search
		request, server will add queue first and software second to
		search result.
		See also "readme.txt" in SlavaNap.
		

        The windows client filters by ping time inside the client.
                It pretty much has to, and it's easy to see the
                result by setting ping time to at best 100 ms or
                so, and max search terms to 50.  You'll get back
                like 3 results, but the client will still tell you
                that it found "50 results".

        Examples:
                FILENAME CONTAINS "Sneaker Pimps" MAX_RESULTS 75 FILENAME
                         CONTAINS "tesko suicide" BITRATE "AT LEAST" "128"

                MAX_RESULTS 100 FILENAME CONTAINS "Ventolin" LINESPEED
                        "EQUAL TO" 10

	[Thanks to Ben Byer <[e-mail]> for this contribution.  -ed]


	SEE ALSO: 10300 share non-mp3 file.

201 (0xc9)	search response [SERVER]

	[NAPSTER,OPENNAP,SLAVANAP]

	"<filename>" <md5> <size> <bitrate> <frequency> <length> <nick> <ip>
	<link-type> [ [weight] | [queue] "[software]" ]

	<md5> see secton "MD5"
	<size> is file size in bytes
	<bitrate> is mp3 bit rate in kbps
	<frequency> is sample rate in hz
	<length> is the play length of the mp3 in seconds
	<nick> the person sharing the file
	<ip> is an unsigned long integer representing the ip address of the
		user with this file
	<link-type> see message client login (2) message for a description
	[weight]	a weighting factor to allow the client to sort the
	                list of results.  positive values indicate a "better"
			match, negative values indicate a "worse" match.
			If not present, the weight should be considered to be
			0.
	[queue]		for SlavaNap 2.x only. queued items number for remote
			user. server will return it if you have added
			"SHOW_QUEUE" to search request. parameter [weight]
			is not returned by slavanap server.
			
	[software]	for SlavaNap 2.x only. this parameter shows software
			that is used by remote client. parameter [weight]
			is not returned by slavanap server.