fill /acme

1 files changed, 220 insertions, 0 deletions

diff --git a/acme/bin/source/acd/submit b/acme/bin/source/acd/submit
new file mode 100644
index 000000000..49aaf1662
--- /dev/null
+++ b/acme/bin/source/acd/submit
@@ -0,0 +1,220 @@
+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.