fill /acme

1 files changed, 243 insertions, 0 deletions

diff --git a/acme/bin/source/acd/access b/acme/bin/source/acd/access
new file mode 100644
index 000000000..9a34399e0
--- /dev/null
+++ b/acme/bin/source/acd/access
@@ -0,0 +1,243 @@
+TWO FORMS OF ACCESS TO THE FREEDB

+---------------------------------

+

+In the following document we will refer to CDDB instead of freedb, since 

+from a technical point of view, freedb is a CDDB-Server as it uses the 

+CDDB-protocol.

+

+If you are interested in incorporating the use of freedb in your

+software, there are two forms of access that you may consider.

+

+1. <a href="#local">Local access</a>

+

+   In this mode your software simply attempts to open local files on

+   the computer to access the CDDB.

+

+2. <a href="#remote">Remote access</a>

+

+   In this mode the software must connect to a freedb server on the

+   network to access the CDDB.  There is a CDDB server protocol that

+   the software (also known as the "client") must use to converse with

+   the server.

+

+You may choose to support either one, or both of these modes.

+

+

+CDDB DISCID

+-----------

+

+Both forms of CDDB access requires that the software computes a "disc

+ID" which is an identifier that is used to access the CDDB.  The disc

+ID is a 8-digit hexadecimal (base-16) number, computed using data from

+a CD's Table-of-Contents (TOC) in MSF (Minute Second Frame) form.  The

+algorithm is listed below in the <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=6">DISCID Howto</a>.

+

+It is crucial that your software compute the disc ID correctly.  If it

+does not generate the disc ID, it will not be compatible with the

+CDDB.  Moreover, if your software submits CDDB entries with bad disc

+IDs to the freedb archives, it could compromise the integrity of the

+freedb.

+

+If you have access to a UNIX platform that xmcd supports, we suggest 

+installing xmcd, and then test the disc ID code in your software by

+comparing the disc ID generated by xmcd with that of your software,

+for as large a number of CDs as possible.

+

+

+<a name="local"></a>LOCAL CDDB ACCESS

+-----------------

+

+There are two forms of the CDDB archive available, the standard form

+and the alternate form.  Both forms are available for download from 

+various servers. You can always find an actual list of mirrors on the 

+freedb-homepage at <a href="http://freedb.freedb.org">http://freedb.freedb.org</a>.

+The standard form of the CDDB archive is released to the public as 

+a UNIX tar(1)-format archive, compressed with gzip.  The alternate 

+form  archive is in the .zip format that is popular on the Windows 

+platform.

+

+Standard Form:

+--------------

+

+Each CD entry is a separate file in the xmcd CDDB.  These files are

+organized in several directories, each directory is a category of

+music.  Currently the "official" categories are listed as follows:

+

+	blues

+	classical

+	country

+	data

+	folk

+	jazz

+	misc

+	newage

+	reggae

+	rock

+	soundtrack

+

+The individual CDDB files have a file name that is the 8-digit disc

+ID. For example, under the blues directory there may be the following

+files:

+

+	0511c012

+	060e7314

+	0c01e902

+	0f0c3112

+	...

+	fa0f6f10

+	fb0f8814

+	fd0e6013

+

+To access the CDDB entry associated with a CD, your software simply

+opens the appropriate file and reads the information.

+

+The content of each of these files is in a format described in the 

+<a href="http://freedb.freedb.org/software/old/DBFORMAT">database-format specification</a>.

+

+Different pressings of a particular CD title may contain differences

+in timings that can cause the computed disc ID to be different.

+The CDDB allows this by having multiple file names be links to

+the same file.  The links are implemented as actual filesystem links

+(see the ln(1) command) on UNIX systems.  For example, the following

+files in the rock directory are all links to the same file, and

+refer to the CD "Pink Floyd / The Division Bell".:

+

+	850f740b

+	850f950b

+	850f970b

+	860f960b

+	890f970b

+

+Xmcd and the CD database server use this form of the CDDB archive.  The

+benefit of the standard form of the CDDB archive is very fast access,

+and ease of add/delete/edit operations on entries.

+

+Alternate Form:

+---------------

+

+Due to limitations in the FAT file system used on Windows 9x and 

+Windows ME, it is unfeasible to use the standard format CDDB archive 

+due to the large number of files.  This is because such a filesystem 

+operates on fixed-size clusters and even a small file (and most CDDB

+files are 1KB or less) would consume the space of a full cluster

+(Depending upon disk size, a cluster can range from 4KB to 32KB in 

+size).  Thus, a tremendous amount of disk space would be wasted on

+these systems if the CDDB archive is used in its standard form.

+

+An alternate form of the CDDB archives was created for use by software

+that must operate on a system with the FAT limitations.

+

+The alterate form still use the separate category directories as the

+standard form, but concatenates many files into a smaller number of

+files under each category.  The first two digits of the CDDB file names

+is used as a key for concatenation, each file is allowed to grow to

+approximately 64KB in size before a new file is started.  The file name

+indicates what range of the digits are included in that file.  For

+example, under the blues category we may have the following files:

+

+	01to36

+	37to55

+	56to71

+	...

+	b2tod7

+	d8toff

+

+The 01to36 file contains all CDDB entries with disc ID 01xxxxxx,

+02xxxxxx, 03xxxxxx and so on, up to 36xxxxxx.

+

+Each entry in the concatenated file begins with the keyword

+

+#FILENAME=xxxxxxxx

+

+where discid is the 8-digit hexadecimal disc ID of that entry.  Your

+software must search through the appropriate file to locate the desired

+entry.  The CDDB entry is in the format described in Appendix B below.

+

+The alternate form avoids the problem of inefficient disk space

+utilization on FAT-based filesystems, but is slower to access than the

+standard form, and it is much more cumbersome to perform add/delete/edit

+operations on a CDDB entry.

+

+

+<a name="remote"></a>REMOTE CDDB ACCESS

+------------------

+

+Your software must be able to communicate with a remote CD server

+system via TCP/IP or HTTP.  

+There are a number of public freedb servers operating

+on the Internet.  The <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=9">current list of public servers</a> is listed on the

+freedb web page at:

+

+    http://freedb.freedb.org.

+	

+It may also be obtained programmatically via the CDDB protocol "sites" 

+command.

+

+TCP/IP access:

+

+All current freedb servers answer at TCP port 888.  There may be future

+sites that deviate from this convention, however.

+

+HTTP access:

+

+The freedb-servers can be accessed via the cddb.cgi. This is resides at the

+following path: /~cddb/cddb.cgi 

+Thus, the URL for accessing the server at freedb.freedb.org is:

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

+

+You should make the freedb server host (or hosts) and port numbers

+user-configurable in your software.  Do not hard-wire the list of

+CD database servers into your code.  The list of active servers changes

+over time.

+

+The CDDB server protocol is described in the <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=28">CDDB-protocol documentation</a>.

+

+The CDDB entry returned from the server via a "cddb read" command is in

+the format described <a href="http://freedb.freedb.org/software/old/DBFORMAT">database-format specification</a>.

+

+You may experiment with the freedb server by connecting to port 888 of

+the server host via the "telnet" program, and then typing the cddb

+protocol commands by hand.  For example:

+

+	telnet freedb.freedb.org 888

+

+connects you to the freedb server at freedb.freedb.org.

+

+Some additional notes for accessing freedb over the Internet:

+

+Your application should always specify the highest documented protocol

+level. The highest level currently supported is "3". Lower protocol 

+levels will work, but are only provided for compatibility with older 

+CDDB applications. If you do not use the highest available protocol 

+level, certain important features will not be available to your 

+application.

+

+Make sure to use the proper arguments with the "hello" command. The user

+and hostname arguments should be that of the user's email address, not

+some fixed hard-coded value. The application name and version should be

+that of your application, not that of another existing application.

+

+We consider the use of the "cddb query" command mandatory for all CDDB

+clients. It is not valid to issue a "cddb read" command without issuing

+a prior "cddb query" and receiving a good response, as it may yield incorrect

+results. In addition, it is clients should support close matches

+(aka "fuzzy" matches, or response code 211).

+

+The proper way to handle multiple fuzzy matches is to present the

+entire list of matches to the user and to let the user choose between them.

+Matches are listed in the order of best fit for the user's disc, so they

+should be presented to the user in the order they are listed by the server.

+

+The suggested algorithm for obtaining the list of server sites is

+as follows.  The application should offer to get the list from

+freedb.freedb.org with the "sites" command the first time the user runs 

+the program. Additionally the application should provide the user with 

+some method of downloading the list on-demand.

+

+We do strongly suggest that you provide your users with the capability of

+choosing freedb server sites as described above. However, for some 

+applications this may not be feasible. If you do not wish to offer this 

+functionality, you may safely hard-code "freedb.freedb.org" in your 

+application as the sole freedb site to access. This will deprive your users

+of the option to choose a site near their locale for optimal response, but

+that is your choice.