plan9fox/acme/bin/source/acd/submit

CDDB SUBMISSION
---------------

Your software may allow users to enter CDDB data and then submit them
to the freedb archive.  
There are two methods of submission: <a href="#email">via e-mail</a> or <a href="#http">via http</a> using submit.cgi

<a name="email"></a>1. Submission via e-mail
------------------------

Your software has to send the entry to the
following address:

	freedb-submit@freedb.org

You may implement a button or somesuch in your software's user-interface
to facilitate this.  The destination e-mail address should be made
user-configurable.

There should be one e-mail message per freedb entry.  The mail Subject
line should be in the form "cddb category discid".  For example:

Subject: cddb rock 850f970b

The body of the e-mail message should be in the format of a CDDB file
entry as described <a href="http://freedb.freedb.org/software/old/DBFORMAT">here</a>.  The messages should contain only
plain ASCII text.  Do not attach encoded information or add special
escape sequences.

Note that the disc ID specified in the mail Subject line should
also appear in the list of disc IDs in the DISCID= field of the
CDDB file entry.  If not, it is considered an error and the submission
will be rejected.

You should only allow categories that are currently supported by the
freedb (blues, classical, country, data, folk, jazz, misc, newage,
reggae, rock, soundtrack).  Submissions specifying unsupported
categories will be rejected.

Please do not allow a user to submit CD database entries that
have completely unfilled contents (i.e., blank information in the
disc artist/title as well as the track titles, or filled with
useless default information like "track 1", "track 2", etc.).
While the current CD database server checks and rejects submissions
that have a blank DTITLE line, it doesn't (and can't feasibly) check
the track titles effectively, nor can it check any of these fields
if they are filled with a default string.  If it were, it would
have to be hacked to know about the default strings of every possible
client.

Thus, please design your client with this in mind.  This is a somewhat
tricky thing to do, as some CDs contain blank tracks with no titles
and you need to allow for that.  An example minimum requirement
that a CD player client should meet is listed below:

1. Don't allow the "send" or "submit" feature to be activated if
   the CD database information form is not edited at all.
2. Check that the disc artist/title contains something (that the user
   typed in).
3. Check that all of the tracks have a title filled in by the user 
   (some (but not all!) may be blank, but not the default string).

This should minimize the number of useless garbage being submitted
into the CD database.

Before you release your software, please be sure that it produces
submissions that adheres to the CDDB file format, and that the frame
offset, disc length, and disc ID information are correctly computed.
For testing, please make your software send submissions to the
following e-mail address (rather than the real submission site at
freedb-submit@freedb.org):

	test-submit@freedb.org

The test address performs sanity checking on the CDDB submission and
sends back pass/fail confirmation, but does not actually deposit the
entry in the CD database.

<a name="http"></a>2. Submission via http
----------------------

For submit via http, your application has to transmit the entry to the
database through a CGI program at the following URL:

http://freedb.freedb.org/~cddb/submit.cgi

Submissions are made through the CGI program as follows. You must only use
the "POST" method of sending data; "GET" is not supported. There are several
HTTP "Entity-Header" fields that must be included in the data followed by a
blank line, followed by the "Entity-Body" (a.k.a the CDDB entry) in the
format described in Appendix B below. The required header fields are:

Category: CDDB_category
Discid: CDDB_discid
User-Email: user@domain
Submit-Mode: test_or_submit
Content-Length: length_of_CDDB_entry

Where:

- "CDDB_category" is one of the valid CDDB categories (blues, classical,
  country, data, folk, jazz, misc, newage, reggae, rock, soundtrack).
  Invalid categories will result in the entry being rejected.

- "CDDB_discid" is the 8-digit hex CDDB disc ID of the entry as described in
  the "<a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=6">Discid howto</a>" section. This must be the same disc ID that appears
  in the "DISCID=" section of the entry being submitted. If not, the entry
  will be rejected.

- "user@domain" is the valid email address of the user submitting the entry.
  This is required in case a submission failure notice must be sent to the
  user.

- "test_or_submit" is the word "test" or "submit" (without the surrounding
  quotes) to indicate whether the submission is a test submission or a real
  submission to the database, respectively. See <a href="#testsubmission">below</a> for an explanation of
  test submissions.

- "length_of_CDDB_entry" is the size in bytes of the CDDB entry being
  submitted. This number does not include the length of the header or the
  blank line separating the HTTP header and the CDDB entry.

There are several additional optional HTTP header fields that may also
be specified (but which are currently not used by the freedb):

Charset: character_set_of_CDDB_entry
X-Cddbd-Note: message for user

Where:

- "character_set_of_CDDB_entry" is one of ISO-8859-1 or US-ASCII (lower case
  may be used if desired). This specifies to the CDDB server which character
  set the CDDB entry has been encoded in. If your application knows the
  user's character set, then you should specify it here. Only these two
  character sets are supported currently. DO NOT specify the character set
  if your application does not have any way of verifying the user's character
  set (i.e. do not guess; it's better not to specify it at all).

- "message for user" is an arbitrary message to be included at the top of
  any rejection notice that may be sent to the submitting user.

An example submission showing the HTTP command, "Entity-Header" and "Entity-
Body" follows:

POST /~cddb/submit.cgi HTTP/1.0
Category: rock
Discid: 2a09310a
User-Email: joe@joeshost.joesdomain.com
Submit-Mode: submit
Charset: ISO-8859-1
X-Cddbd-Note: Problems with Super CD Player? Send email to support@supercd.com.
Content-Length: 820

# xmcd
#
# Track frame offsets:
[ data omitted in this example for brevity ]
PLAYORDER=

Note the blank line between the "Content-Length" header field and the
"# xmcd" which marks the beginning of the CDDB entry.

When your application submits an entry through the CGI program, it will
respond with a 3-digit response code indicating whether or not the entry has
been forwarded to the freedb server for inclusion in the database, followed
by a textual description of the response code. For example:

200 OK, submission has been sent.
400 Internal error: failed to forward submission.
500 Missing required header information.

These are but a few of the possible responses. 
See the description of the <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=28">CDDB server protocol</a> for more information on 
handling response codes.

The body of the freedb entry being submitted should be sent verbatim as
described in the <a href="http://freedb.freedb.org/software/old/DBFORMAT">database-format specification</a>. DO NOT encode the data in any 
way before transmitting it; data must be sent as raw text. For example, 
Windows programmers should not use the Windows URL encode function prior to
calling the submit CGI program. Doing so may lead to corrupt data being sent
and also possibly to rejected submissions.

You may implement a button or somesuch in your software's user interface
to initiate submissions. Rejected submissions are automatically returned
via email to the sender specified in the "User-Email" header field with an
explanation of the reason for the rejection.

Please do not allow a user to submit CD database entries that
have completely unfilled contents (i.e., blank information in the
disc artist/title as well as the track titles, or filled with
useless default information like "track 1", "track 2", etc.).
While the current CD database server checks and rejects submissions
that have a blank DTITLE line, it doesn't (and can't feasibly) check
the track titles effectively, nor can it check any of these fields
if they are filled with a default string.  If it were, it would
have to be hacked to know about the default strings of every possible
client.

Thus, please design your client with this in mind.  This is a somewhat
tricky thing to do, as some CDs contain blank tracks with no titles
and you need to allow for that.  An example minimum requirement
that a CD player client should meet is listed below:

1. Don't allow the "send" or "submit" feature to be activated if
   the CD database information form is not edited at all.
2. Check that the disc artist/title contains something (that the user
   typed in).
3. Check that all of the tracks have a title filled in by the user.
   (some (but not all!) may be blank, but not the default string).
	
Before you release your software, please be sure that it produces
submissions that adhere to the CDDB file format, and that the frame
offset, disc length, and disc ID information are correctly computed.
For testing, please make your software send submissions with the
"Submit-Mode" HTTP header field set to "test".

<a name="testsubmission"></a>CDDB submissions sent in test mode will be sanity-checked by the freedb server
and pass/fail confirmation sent back to the submitter, but will not actually
be deposited in the CD database. Please DO NOT send submisions in "submit"
mode until you have tested your program with several different CD's.