annotate cddb_howto.txt @ 12:2bcb84ead02e default tip

Use Tcl 8.2 Fix setting the album artist changes
author darius
date Thu, 18 Jul 2002 06:47:39 +0000
parents 5cead4da1db9
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1
5cead4da1db9 Initial import.
darius
parents:
diff changeset
2 USE OF CDDB SERVICE IN YOUR SOFTWARE
5cead4da1db9 Initial import.
darius
parents:
diff changeset
3 ------------------------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
4 Copyright (c) CDDB, Inc.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
5
5cead4da1db9 Initial import.
darius
parents:
diff changeset
6 @(#)cddb.howto 1.27 98/12/09
5cead4da1db9 Initial import.
darius
parents:
diff changeset
7
5cead4da1db9 Initial import.
darius
parents:
diff changeset
8
5cead4da1db9 Initial import.
darius
parents:
diff changeset
9
5cead4da1db9 Initial import.
darius
parents:
diff changeset
10 In this document:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
11
5cead4da1db9 Initial import.
darius
parents:
diff changeset
12 - WHAT IS THE CDDB
5cead4da1db9 Initial import.
darius
parents:
diff changeset
13 - CDDB USE RESTRICTIONS
5cead4da1db9 Initial import.
darius
parents:
diff changeset
14 - TWO FORMS OF ACCESS TO THE CDDB
5cead4da1db9 Initial import.
darius
parents:
diff changeset
15 - CDDB DISCID
5cead4da1db9 Initial import.
darius
parents:
diff changeset
16 - REMOTE CDDB ACCESS
5cead4da1db9 Initial import.
darius
parents:
diff changeset
17 - CDDB SUBMISSION
5cead4da1db9 Initial import.
darius
parents:
diff changeset
18 - QUESTIONS?
5cead4da1db9 Initial import.
darius
parents:
diff changeset
19 - APPENDIX A - CDDB DISCID ALGORITHM
5cead4da1db9 Initial import.
darius
parents:
diff changeset
20 - APPENDIX B - CDDB FILE FORMAT
5cead4da1db9 Initial import.
darius
parents:
diff changeset
21 - APPENDIX C - CDDB SERVER PROTOCOL
5cead4da1db9 Initial import.
darius
parents:
diff changeset
22 - APPENDIX D - OFFICIAL CDDB SOFTWARE DISTRIBUTION SITES
5cead4da1db9 Initial import.
darius
parents:
diff changeset
23
5cead4da1db9 Initial import.
darius
parents:
diff changeset
24
5cead4da1db9 Initial import.
darius
parents:
diff changeset
25
5cead4da1db9 Initial import.
darius
parents:
diff changeset
26 WHAT IS THE CDDB
5cead4da1db9 Initial import.
darius
parents:
diff changeset
27 ----------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
28
5cead4da1db9 Initial import.
darius
parents:
diff changeset
29 CDDB (CD database) is an information database containing artist, disc
5cead4da1db9 Initial import.
darius
parents:
diff changeset
30 title, track titles, and other information for digital audio compact
5cead4da1db9 Initial import.
darius
parents:
diff changeset
31 discs. Over time, this archive has grown to contain a substantial
5cead4da1db9 Initial import.
darius
parents:
diff changeset
32 collection of CD information and is continuing to grow at a rapid rate.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
33 This database can be accessed by applications via the CDDB server hosts
5cead4da1db9 Initial import.
darius
parents:
diff changeset
34 that have been set up on the Internet around the world.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
35
5cead4da1db9 Initial import.
darius
parents:
diff changeset
36 The CDDB data format and the CDDB servers are designed to be open, and
5cead4da1db9 Initial import.
darius
parents:
diff changeset
37 are used by many client applications requiring CD information. CDDB has
5cead4da1db9 Initial import.
darius
parents:
diff changeset
38 become the de facto standard for Internet access of compact disc
5cead4da1db9 Initial import.
darius
parents:
diff changeset
39 information.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
40
5cead4da1db9 Initial import.
darius
parents:
diff changeset
41
5cead4da1db9 Initial import.
darius
parents:
diff changeset
42 CDDB USE RESTRICTIONS
5cead4da1db9 Initial import.
darius
parents:
diff changeset
43 ---------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
44
5cead4da1db9 Initial import.
darius
parents:
diff changeset
45 Users of CDDB-capable freeware and shareware applications may use the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
46 public CDDB servers for free. Commercial uses of CDDB data and/or servers
5cead4da1db9 Initial import.
darius
parents:
diff changeset
47 are subject to negotiations with CDDB Inc. Please write to us at
5cead4da1db9 Initial import.
darius
parents:
diff changeset
48 licensing@cddb.com for more information.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
49
5cead4da1db9 Initial import.
darius
parents:
diff changeset
50 If you plan to use CDDB and/or the CDDB servers in your software, please
5cead4da1db9 Initial import.
darius
parents:
diff changeset
51 notify support@cddb.com of your intent. Also, we appreciate that you
5cead4da1db9 Initial import.
darius
parents:
diff changeset
52 keep us posted as to your development/test progress and release schedules.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
53 Before you release your CDDB application we must verify that it properly
5cead4da1db9 Initial import.
darius
parents:
diff changeset
54 implements the CDDB functionality. You must provide us with a copy of your
5cead4da1db9 Initial import.
darius
parents:
diff changeset
55 software for testing when it is ready. Please do not release your software
5cead4da1db9 Initial import.
darius
parents:
diff changeset
56 with CDDB functionality until it has been tested.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
57
5cead4da1db9 Initial import.
darius
parents:
diff changeset
58 You must explicitly give credit to CDDB, Inc. in your application, both in
5cead4da1db9 Initial import.
darius
parents:
diff changeset
59 all documentation that mentions the CDDB functionality in any way, and when
5cead4da1db9 Initial import.
darius
parents:
diff changeset
60 the product is operating. The exact details should be obtained from
5cead4da1db9 Initial import.
darius
parents:
diff changeset
61 licensing@cddb.com before you release your software.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
62
5cead4da1db9 Initial import.
darius
parents:
diff changeset
63
5cead4da1db9 Initial import.
darius
parents:
diff changeset
64
5cead4da1db9 Initial import.
darius
parents:
diff changeset
65 TWO FORMS OF ACCESS TO THE CDDB
5cead4da1db9 Initial import.
darius
parents:
diff changeset
66 -------------------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
67
5cead4da1db9 Initial import.
darius
parents:
diff changeset
68 If you are interested in incorporating the use of CDDB in your
5cead4da1db9 Initial import.
darius
parents:
diff changeset
69 software, there are two forms of access that you may consider.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
70
5cead4da1db9 Initial import.
darius
parents:
diff changeset
71 1. Local access
5cead4da1db9 Initial import.
darius
parents:
diff changeset
72
5cead4da1db9 Initial import.
darius
parents:
diff changeset
73 In this mode your software simply attempts to open local files on
5cead4da1db9 Initial import.
darius
parents:
diff changeset
74 the computer to access the CDDB.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
75
5cead4da1db9 Initial import.
darius
parents:
diff changeset
76 You may store the CD information in the CDDB-native format (See
5cead4da1db9 Initial import.
darius
parents:
diff changeset
77 Appendix B), or another format of your choice (for example, the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
78 Win95 cdplayer.ini format). Users appreciate a the ability to import
5cead4da1db9 Initial import.
darius
parents:
diff changeset
79 CDDB data from and export to a variety of formats.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
80
5cead4da1db9 Initial import.
darius
parents:
diff changeset
81 Note that the CDDB archive is not available for downloads, therefore
5cead4da1db9 Initial import.
darius
parents:
diff changeset
82 this mode is only useful to retrieve CD data that is entered by the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
83 user and saved to disk.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
84
5cead4da1db9 Initial import.
darius
parents:
diff changeset
85 2. Remote access
5cead4da1db9 Initial import.
darius
parents:
diff changeset
86
5cead4da1db9 Initial import.
darius
parents:
diff changeset
87 In this mode the software must connect to a CDDB server on the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
88 network to access the CDDB. There is a CDDB server protocol that
5cead4da1db9 Initial import.
darius
parents:
diff changeset
89 the software (also known as the "client") must use to converse with
5cead4da1db9 Initial import.
darius
parents:
diff changeset
90 the server.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
91
5cead4da1db9 Initial import.
darius
parents:
diff changeset
92 This mode allows the client application full access to the entire
5cead4da1db9 Initial import.
darius
parents:
diff changeset
93 CD database over the Internet. The data returned is in the CDDB
5cead4da1db9 Initial import.
darius
parents:
diff changeset
94 native file format as described in Appendix B.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
95
5cead4da1db9 Initial import.
darius
parents:
diff changeset
96 You may choose to support only remote access mode, or both remote and
5cead4da1db9 Initial import.
darius
parents:
diff changeset
97 local. We do not recommend a local-only application, since it is not
5cead4da1db9 Initial import.
darius
parents:
diff changeset
98 very useful.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
99
5cead4da1db9 Initial import.
darius
parents:
diff changeset
100
5cead4da1db9 Initial import.
darius
parents:
diff changeset
101 CDDB DISCID
5cead4da1db9 Initial import.
darius
parents:
diff changeset
102 -----------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
103
5cead4da1db9 Initial import.
darius
parents:
diff changeset
104 Both forms of CDDB access require that the software compute a "disc
5cead4da1db9 Initial import.
darius
parents:
diff changeset
105 ID" which is an identifier that is used to access the CDDB. The disc
5cead4da1db9 Initial import.
darius
parents:
diff changeset
106 ID is a 8-digit hexadecimal (base-16) number, computed using data from
5cead4da1db9 Initial import.
darius
parents:
diff changeset
107 a CD's Table-of-Contents (TOC) in MSF (Minute Second Frame) form. The
5cead4da1db9 Initial import.
darius
parents:
diff changeset
108 algorithm is listed below in Appendix A.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
109
5cead4da1db9 Initial import.
darius
parents:
diff changeset
110 It is crucial that your software compute the disc ID correctly. If it
5cead4da1db9 Initial import.
darius
parents:
diff changeset
111 does not generate the correct disc ID, it will not be compatible with CDDB.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
112 Moreover, if your software submits CDDB entries with bad disc IDs to the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
113 CDDB archives, it could compromise the integrity of the CDDB.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
114
5cead4da1db9 Initial import.
darius
parents:
diff changeset
115 We suggest installing one of the disc ID checker programs listed on the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
116 CDDB web page at http://www.cddb.com/downloads, and then testing the disc
5cead4da1db9 Initial import.
darius
parents:
diff changeset
117 ID code in your software by comparing the disc ID generated by the program
5cead4da1db9 Initial import.
darius
parents:
diff changeset
118 with that of your software for as large a number of CDs as possible. Bugs
5cead4da1db9 Initial import.
darius
parents:
diff changeset
119 in disc ID calculation can be subtle, and history shows that it sometimes
5cead4da1db9 Initial import.
darius
parents:
diff changeset
120 takes hundreds of discs to find problems.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
121
5cead4da1db9 Initial import.
darius
parents:
diff changeset
122
5cead4da1db9 Initial import.
darius
parents:
diff changeset
123 REMOTE CDDB ACCESS
5cead4da1db9 Initial import.
darius
parents:
diff changeset
124 ------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
125
5cead4da1db9 Initial import.
darius
parents:
diff changeset
126 In order to perform remote access of CDDB servers, your software must be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
127 able to communicate with a remote CD server system via HTTP. There are a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
128 number of public CDDB servers operating on the Internet. The current list
5cead4da1db9 Initial import.
darius
parents:
diff changeset
129 of public servers may be obtained programmatically via the CDDB protocol
5cead4da1db9 Initial import.
darius
parents:
diff changeset
130 "sites" command. The permanent server site, cddb.cddb.com has been
5cead4da1db9 Initial import.
darius
parents:
diff changeset
131 established in order to provide a reliable source of server site information
5cead4da1db9 Initial import.
darius
parents:
diff changeset
132 via the "sites" command. This address may be safely hard-wired into client
5cead4da1db9 Initial import.
darius
parents:
diff changeset
133 software for this purpose, as it is guaranteed to exist on a permanent basis.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
134 Furthermore, the "cddb.cgi" program is guaranteed to always reside at the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
135 following path: /~cddb/cddb.cgi
5cead4da1db9 Initial import.
darius
parents:
diff changeset
136
5cead4da1db9 Initial import.
darius
parents:
diff changeset
137 Thus, the URL for accessing the server at cddb.cddb.com is:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
138
5cead4da1db9 Initial import.
darius
parents:
diff changeset
139 http://cddb.cddb.com/~cddb/cddb.cgi
5cead4da1db9 Initial import.
darius
parents:
diff changeset
140
5cead4da1db9 Initial import.
darius
parents:
diff changeset
141 You should make the CDDB server host (or hosts) user-selectable in your
5cead4da1db9 Initial import.
darius
parents:
diff changeset
142 software. DO NOT hard-wire the list of CD database servers into your code.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
143 The list of active servers changes over time.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
144
5cead4da1db9 Initial import.
darius
parents:
diff changeset
145 The CDDB server protocol is described below in Appendix C.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
146
5cead4da1db9 Initial import.
darius
parents:
diff changeset
147 The CDDB entry returned from the server via a "cddb read" command is in
5cead4da1db9 Initial import.
darius
parents:
diff changeset
148 the format described in Appendix B below.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
149
5cead4da1db9 Initial import.
darius
parents:
diff changeset
150 Some additional notes for accessing CDDB over the Internet:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
151
5cead4da1db9 Initial import.
darius
parents:
diff changeset
152 Your application should always specify the highest documented protocol
5cead4da1db9 Initial import.
darius
parents:
diff changeset
153 level in the "proto=" field of the HTTP command. The highest level currently
5cead4da1db9 Initial import.
darius
parents:
diff changeset
154 specified is "4". Lower protocol levels will work, but are only provided
5cead4da1db9 Initial import.
darius
parents:
diff changeset
155 for compatibility with older CDDB applications. If you do not use the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
156 highest available protocol level, certain important features will not be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
157 available to your application.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
158
5cead4da1db9 Initial import.
darius
parents:
diff changeset
159 Make sure to use the proper arguments in the "hello=" command. The user
5cead4da1db9 Initial import.
darius
parents:
diff changeset
160 and hostname arguments should be that of the user's email address, not
5cead4da1db9 Initial import.
darius
parents:
diff changeset
161 some fixed hard-coded value. The application name and version should be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
162 that of your application, not that of another existing application.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
163
5cead4da1db9 Initial import.
darius
parents:
diff changeset
164 We consider the use of the "cddb query" command mandatory for all CDDB
5cead4da1db9 Initial import.
darius
parents:
diff changeset
165 clients. It is not valid to issue a "cddb read" command without issuing
5cead4da1db9 Initial import.
darius
parents:
diff changeset
166 a prior "cddb query" and receiving a good response, as it may yield incorrect
5cead4da1db9 Initial import.
darius
parents:
diff changeset
167 results. In addition, it is required that clients support close matches
5cead4da1db9 Initial import.
darius
parents:
diff changeset
168 (aka "fuzzy" matches, or response code 211) and multiple exact matches
5cead4da1db9 Initial import.
darius
parents:
diff changeset
169 (response code 210) in response to a query.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
170
5cead4da1db9 Initial import.
darius
parents:
diff changeset
171 The proper way to handle multiple exact/fuzzy matches is to present the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
172 entire list of matches to the user and to let the user choose between them.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
173 Matches are listed in the order of best fit for the user's disc, so they
5cead4da1db9 Initial import.
darius
parents:
diff changeset
174 should be presented to the user in the order they are listed by the server.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
175
5cead4da1db9 Initial import.
darius
parents:
diff changeset
176 The suggested algorithm for obtaining the list of server sites is
5cead4da1db9 Initial import.
darius
parents:
diff changeset
177 as follows. The application should attempt to get the list from
5cead4da1db9 Initial import.
darius
parents:
diff changeset
178 cddb.cddb.com with the "sites" command the first time the user runs the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
179 program. After the initial download of the site list, the application
5cead4da1db9 Initial import.
darius
parents:
diff changeset
180 should periodically attempt to download the site list, or at least
5cead4da1db9 Initial import.
darius
parents:
diff changeset
181 provide the user with some method of downloading the list on-demand.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
182 Should the user be unable to subsequently download the list of sites
5cead4da1db9 Initial import.
darius
parents:
diff changeset
183 due to temporary network perturbation, the application should attempt
5cead4da1db9 Initial import.
darius
parents:
diff changeset
184 to download the site list from one of the sites in its current list. All
5cead4da1db9 Initial import.
darius
parents:
diff changeset
185 of the official CDDB server sites will contain a valid list of servers,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
186 though cddb.cddb.com is the only site which is guaranteed to always exist.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
187
5cead4da1db9 Initial import.
darius
parents:
diff changeset
188 We do strongly suggest that you provide your users with the capability of
5cead4da1db9 Initial import.
darius
parents:
diff changeset
189 choosing CDDB server sites as described above. However, for some applications
5cead4da1db9 Initial import.
darius
parents:
diff changeset
190 this may not be feasible. If you do not wish to offer this functionality,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
191 you may safely hard-code "cddb.cddb.com" in your application as the sole
5cead4da1db9 Initial import.
darius
parents:
diff changeset
192 CDDB site to access. This will deprive your users of the option to choose
5cead4da1db9 Initial import.
darius
parents:
diff changeset
193 a site near their locale for optimal response, but that is your choice.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
194
5cead4da1db9 Initial import.
darius
parents:
diff changeset
195 PLEASE NOTE: older versions of the CDDB specification describe two methods
5cead4da1db9 Initial import.
darius
parents:
diff changeset
196 of accessing the CDDB servers: HTTP mode and CDDBP mode. CDDBP mode is
5cead4da1db9 Initial import.
darius
parents:
diff changeset
197 being deprecated in favor of HTTP mode, so new applications should be sure
5cead4da1db9 Initial import.
darius
parents:
diff changeset
198 to only implement the HTTP mode of access. All text describing CDDBP
5cead4da1db9 Initial import.
darius
parents:
diff changeset
199 mode has been removed from this document.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
200
5cead4da1db9 Initial import.
darius
parents:
diff changeset
201
5cead4da1db9 Initial import.
darius
parents:
diff changeset
202 CDDB SUBMISSION
5cead4da1db9 Initial import.
darius
parents:
diff changeset
203 ---------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
204
5cead4da1db9 Initial import.
darius
parents:
diff changeset
205 Your software may allow users to enter CDDB data and then submit it to the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
206 CDDB archives. The method of submission is to transmit the entry to the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
207 database through a CGI program at the following URL:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
208
5cead4da1db9 Initial import.
darius
parents:
diff changeset
209 http://hostname.cddb.com/~cddb/submit.cgi
5cead4da1db9 Initial import.
darius
parents:
diff changeset
210
5cead4da1db9 Initial import.
darius
parents:
diff changeset
211 where "hostname.cddb.com" is one of the hosts listed in the CDDB server
5cead4da1db9 Initial import.
darius
parents:
diff changeset
212 "sites" command, and also cddb.cddb.com.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
213
5cead4da1db9 Initial import.
darius
parents:
diff changeset
214 Submissions are made through the CGI program as follows. You must only use
5cead4da1db9 Initial import.
darius
parents:
diff changeset
215 the "POST" method of sending data; "GET" is not supported. There are several
5cead4da1db9 Initial import.
darius
parents:
diff changeset
216 HTTP "Entity-Header" fields that must be included in the data followed by a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
217 blank line, followed by the "Entity-Body" (a.k.a the CDDB entry) in the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
218 format described in Appendix B below. The required header fields are:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
219
5cead4da1db9 Initial import.
darius
parents:
diff changeset
220 Category: CDDB_category
5cead4da1db9 Initial import.
darius
parents:
diff changeset
221 Discid: CDDB_discid
5cead4da1db9 Initial import.
darius
parents:
diff changeset
222 User-Email: user@domain
5cead4da1db9 Initial import.
darius
parents:
diff changeset
223 Submit-Mode: test_or_submit
5cead4da1db9 Initial import.
darius
parents:
diff changeset
224 Content-Length: length_of_CDDB_entry
5cead4da1db9 Initial import.
darius
parents:
diff changeset
225
5cead4da1db9 Initial import.
darius
parents:
diff changeset
226 Where:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
227
5cead4da1db9 Initial import.
darius
parents:
diff changeset
228 - "CDDB_category" is one of the valid CDDB categories listed by the CDDB
5cead4da1db9 Initial import.
darius
parents:
diff changeset
229 server "cddb lscat" command. Invalid categories will result in the entry
5cead4da1db9 Initial import.
darius
parents:
diff changeset
230 being rejected.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
231
5cead4da1db9 Initial import.
darius
parents:
diff changeset
232 - "CDDB_discid" is the 8-digit hex CDDB disc ID of the entry as described in
5cead4da1db9 Initial import.
darius
parents:
diff changeset
233 the "CDDB Discid" section below. This must be the same disc ID that appears
5cead4da1db9 Initial import.
darius
parents:
diff changeset
234 in the "DISCID=" section of the entry being submitted. If not, the entry
5cead4da1db9 Initial import.
darius
parents:
diff changeset
235 will be rejected.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
236
5cead4da1db9 Initial import.
darius
parents:
diff changeset
237 - "user@domain" is the valid email address of the user submitting the entry.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
238 This is required in case a submission failure notice must be sent to the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
239 user.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
240
5cead4da1db9 Initial import.
darius
parents:
diff changeset
241 - "test_or_submit" is the word "test" or "submit" (without the surrounding
5cead4da1db9 Initial import.
darius
parents:
diff changeset
242 quotes) to indicate whether the submission is a test submission or a real
5cead4da1db9 Initial import.
darius
parents:
diff changeset
243 submission to the database, respectively. See below for an explanation of
5cead4da1db9 Initial import.
darius
parents:
diff changeset
244 test submissions.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
245
5cead4da1db9 Initial import.
darius
parents:
diff changeset
246 - "length_of_CDDB_entry" is the size in bytes of the CDDB entry being
5cead4da1db9 Initial import.
darius
parents:
diff changeset
247 submitted. This number does not include the length of the header or the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
248 blank line separating the HTTP header and the CDDB entry.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
249
5cead4da1db9 Initial import.
darius
parents:
diff changeset
250 There are several additional optional HTTP header fields that may also
5cead4da1db9 Initial import.
darius
parents:
diff changeset
251 be specified:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
252
5cead4da1db9 Initial import.
darius
parents:
diff changeset
253 Charset: character_set_of_CDDB_entry
5cead4da1db9 Initial import.
darius
parents:
diff changeset
254 X-Cddbd-Note: message for user
5cead4da1db9 Initial import.
darius
parents:
diff changeset
255
5cead4da1db9 Initial import.
darius
parents:
diff changeset
256 Where:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
257
5cead4da1db9 Initial import.
darius
parents:
diff changeset
258 - "character_set_of_CDDB_entry" is one of ISO-8859-1 or US-ASCII (lower case
5cead4da1db9 Initial import.
darius
parents:
diff changeset
259 may be used if desired). This specifies to the CDDB server which character
5cead4da1db9 Initial import.
darius
parents:
diff changeset
260 set the CDDB entry has been encoded in. If your application knows the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
261 user's character set, then you should specify it here. Only these two
5cead4da1db9 Initial import.
darius
parents:
diff changeset
262 character sets are supported currently. DO NOT specify the character set
5cead4da1db9 Initial import.
darius
parents:
diff changeset
263 if your application does not have any way of verifying the user's character
5cead4da1db9 Initial import.
darius
parents:
diff changeset
264 set (i.e. do not guess; it's better not to specify it at all).
5cead4da1db9 Initial import.
darius
parents:
diff changeset
265
5cead4da1db9 Initial import.
darius
parents:
diff changeset
266 - "message for user" is an arbitrary message to be included at the top of
5cead4da1db9 Initial import.
darius
parents:
diff changeset
267 any rejection notice that may be sent to the submitting user.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
268
5cead4da1db9 Initial import.
darius
parents:
diff changeset
269 An example submission showing the HTTP command, "Entity-Header" and "Entity-
5cead4da1db9 Initial import.
darius
parents:
diff changeset
270 Body" follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
271
5cead4da1db9 Initial import.
darius
parents:
diff changeset
272 POST /~cddb/submit.cgi HTTP/1.0
5cead4da1db9 Initial import.
darius
parents:
diff changeset
273 Category: rock
5cead4da1db9 Initial import.
darius
parents:
diff changeset
274 Discid: 2a09310a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
275 User-Email: joe@joeshost.joesdomain.com
5cead4da1db9 Initial import.
darius
parents:
diff changeset
276 Submit-Mode: submit
5cead4da1db9 Initial import.
darius
parents:
diff changeset
277 Charset: ISO-8859-1
5cead4da1db9 Initial import.
darius
parents:
diff changeset
278 X-Cddbd-Note: Problems with Super CD Player? Send email to support@supercd.com.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
279 Content-Length: 820
5cead4da1db9 Initial import.
darius
parents:
diff changeset
280
5cead4da1db9 Initial import.
darius
parents:
diff changeset
281 # xmcd
5cead4da1db9 Initial import.
darius
parents:
diff changeset
282 # Copyright (c) 1998 CDDB Inc.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
283 #
5cead4da1db9 Initial import.
darius
parents:
diff changeset
284 # Track frame offsets:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
285 [ data omitted in this example for brevity ]
5cead4da1db9 Initial import.
darius
parents:
diff changeset
286 PLAYORDER=
5cead4da1db9 Initial import.
darius
parents:
diff changeset
287
5cead4da1db9 Initial import.
darius
parents:
diff changeset
288 Note the blank line between the "Content-Length" header field and the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
289 "# xmcd" which marks the beginning of the CDDB entry.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
290
5cead4da1db9 Initial import.
darius
parents:
diff changeset
291 When your application submits an entry through the CGI program, it will
5cead4da1db9 Initial import.
darius
parents:
diff changeset
292 respond with a 3-digit response code indicating whether or not the entry has
5cead4da1db9 Initial import.
darius
parents:
diff changeset
293 been forwarded to the CDDB server for inclusion in the database, followed
5cead4da1db9 Initial import.
darius
parents:
diff changeset
294 by a textual description of the response code. For example:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
295
5cead4da1db9 Initial import.
darius
parents:
diff changeset
296 200 OK, submission has been sent.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
297 400 Internal error: failed to forward submission.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
298 500 Missing required header information.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
299
5cead4da1db9 Initial import.
darius
parents:
diff changeset
300 These are but a few of the possible responses. See the description of the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
301 CDDB server protocol in Appendix C for more information on handling response
5cead4da1db9 Initial import.
darius
parents:
diff changeset
302 codes.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
303
5cead4da1db9 Initial import.
darius
parents:
diff changeset
304 The body of the CDDB entry being submitted should be sent verbatim as
5cead4da1db9 Initial import.
darius
parents:
diff changeset
305 described in Appendix B. DO NOT encode the data in any way before transmitting
5cead4da1db9 Initial import.
darius
parents:
diff changeset
306 it; data must be sent as raw text. For example, Windows programmers should not
5cead4da1db9 Initial import.
darius
parents:
diff changeset
307 use the Windows URL encode function prior to calling the submit CGI program.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
308 Doing so may lead to corrupt data being sent and also possibly to rejected
5cead4da1db9 Initial import.
darius
parents:
diff changeset
309 submissions.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
310
5cead4da1db9 Initial import.
darius
parents:
diff changeset
311 You may implement a button or somesuch in your software's user interface
5cead4da1db9 Initial import.
darius
parents:
diff changeset
312 to initiate submissions. Rejected submissions are automatically returned
5cead4da1db9 Initial import.
darius
parents:
diff changeset
313 via email to the sender specified in the "User-Email" header field with an
5cead4da1db9 Initial import.
darius
parents:
diff changeset
314 explanation of the reason for the rejection.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
315
5cead4da1db9 Initial import.
darius
parents:
diff changeset
316 Please do not allow a user to submit CD database entries that have
5cead4da1db9 Initial import.
darius
parents:
diff changeset
317 completely unfilled contents (i.e., blank information in the disc
5cead4da1db9 Initial import.
darius
parents:
diff changeset
318 artist/title as well as the track titles). Please design your client
5cead4da1db9 Initial import.
darius
parents:
diff changeset
319 with this in mind. An example minimum requirement that a CD player client
5cead4da1db9 Initial import.
darius
parents:
diff changeset
320 should meet is listed below:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
321
5cead4da1db9 Initial import.
darius
parents:
diff changeset
322 1. Don't allow the "send" or "submit" feature to be activated if
5cead4da1db9 Initial import.
darius
parents:
diff changeset
323 the CD database information form is not edited at all.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
324 2. Check that the disc artist/title contains something (that the user
5cead4da1db9 Initial import.
darius
parents:
diff changeset
325 typed in).
5cead4da1db9 Initial import.
darius
parents:
diff changeset
326 3. Don't submit a default string if a field is not filled in
5cead4da1db9 Initial import.
darius
parents:
diff changeset
327 (e.g. If track 3 is not filled in, submit a blank "TTITLE3=" line.)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
328 If you must use a default string, please use "track N" where N
5cead4da1db9 Initial import.
darius
parents:
diff changeset
329 is the track number.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
330
5cead4da1db9 Initial import.
darius
parents:
diff changeset
331 Before you release your software, please be sure that it produces
5cead4da1db9 Initial import.
darius
parents:
diff changeset
332 submissions that adhere to the CDDB file format, and that the frame
5cead4da1db9 Initial import.
darius
parents:
diff changeset
333 offset, disc length, and disc ID information are correctly computed.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
334 For testing, please make your software send submissions with the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
335 "Submit-Mode" HTTP header field set to "test".
5cead4da1db9 Initial import.
darius
parents:
diff changeset
336
5cead4da1db9 Initial import.
darius
parents:
diff changeset
337 CDDB submissions sent in test mode will be sanity-checked by the CDDB server
5cead4da1db9 Initial import.
darius
parents:
diff changeset
338 and pass/fail confirmation sent back to the submitter, but will not actually
5cead4da1db9 Initial import.
darius
parents:
diff changeset
339 be deposited in the CD database. Please DO NOT send submisions in "submit"
5cead4da1db9 Initial import.
darius
parents:
diff changeset
340 mode until your application has been approved by the CDDB support group.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
341
5cead4da1db9 Initial import.
darius
parents:
diff changeset
342 When you feel your application is ready to support submissions, please contact
5cead4da1db9 Initial import.
darius
parents:
diff changeset
343 us at support@cddb.com. We will provide you with our qualification
5cead4da1db9 Initial import.
darius
parents:
diff changeset
344 procedure, which involves submitting a number of entries of different types.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
345 Once qualified, your application will be permitted to submit to the database.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
346
5cead4da1db9 Initial import.
darius
parents:
diff changeset
347
5cead4da1db9 Initial import.
darius
parents:
diff changeset
348 QUESTIONS?
5cead4da1db9 Initial import.
darius
parents:
diff changeset
349 ----------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
350
5cead4da1db9 Initial import.
darius
parents:
diff changeset
351 Please send any questions or comments to support@cddb.com.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
352
5cead4da1db9 Initial import.
darius
parents:
diff changeset
353 APPENDIX A - CDDB DISCID ALGORITHM
5cead4da1db9 Initial import.
darius
parents:
diff changeset
354 ----------------------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
355
5cead4da1db9 Initial import.
darius
parents:
diff changeset
356 The following is a C code example that illustrates how to generate the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
357 CDDB disc ID. Examples in other programming languages may be found on
5cead4da1db9 Initial import.
darius
parents:
diff changeset
358 the CDDB web site at http://www.cddb.com/downloads. A text description
5cead4da1db9 Initial import.
darius
parents:
diff changeset
359 of the algorithm follows, which should contain the necessary information
5cead4da1db9 Initial import.
darius
parents:
diff changeset
360 to code the algorithm in any programming language.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
361
5cead4da1db9 Initial import.
darius
parents:
diff changeset
362
5cead4da1db9 Initial import.
darius
parents:
diff changeset
363 struct toc {
5cead4da1db9 Initial import.
darius
parents:
diff changeset
364 int min;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
365 int sec;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
366 int frame;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
367 };
5cead4da1db9 Initial import.
darius
parents:
diff changeset
368
5cead4da1db9 Initial import.
darius
parents:
diff changeset
369 struct toc cdtoc[100];
5cead4da1db9 Initial import.
darius
parents:
diff changeset
370
5cead4da1db9 Initial import.
darius
parents:
diff changeset
371 int
5cead4da1db9 Initial import.
darius
parents:
diff changeset
372 read_cdtoc_from_drive(void)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
373 {
5cead4da1db9 Initial import.
darius
parents:
diff changeset
374 /* Do whatever is appropriate to read the TOC of the CD
5cead4da1db9 Initial import.
darius
parents:
diff changeset
375 * into the cdtoc[] structure array.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
376 */
5cead4da1db9 Initial import.
darius
parents:
diff changeset
377 return (tot_trks);
5cead4da1db9 Initial import.
darius
parents:
diff changeset
378 }
5cead4da1db9 Initial import.
darius
parents:
diff changeset
379
5cead4da1db9 Initial import.
darius
parents:
diff changeset
380 int
5cead4da1db9 Initial import.
darius
parents:
diff changeset
381 cddb_sum(int n)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
382 {
5cead4da1db9 Initial import.
darius
parents:
diff changeset
383 int ret;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
384
5cead4da1db9 Initial import.
darius
parents:
diff changeset
385 /* For backward compatibility this algorithm must not change */
5cead4da1db9 Initial import.
darius
parents:
diff changeset
386
5cead4da1db9 Initial import.
darius
parents:
diff changeset
387 ret = 0;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
388
5cead4da1db9 Initial import.
darius
parents:
diff changeset
389 while (n > 0) {
5cead4da1db9 Initial import.
darius
parents:
diff changeset
390 ret = ret + (n % 10);
5cead4da1db9 Initial import.
darius
parents:
diff changeset
391 n = n / 10;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
392 }
5cead4da1db9 Initial import.
darius
parents:
diff changeset
393
5cead4da1db9 Initial import.
darius
parents:
diff changeset
394 return (ret);
5cead4da1db9 Initial import.
darius
parents:
diff changeset
395 }
5cead4da1db9 Initial import.
darius
parents:
diff changeset
396
5cead4da1db9 Initial import.
darius
parents:
diff changeset
397 unsigned long
5cead4da1db9 Initial import.
darius
parents:
diff changeset
398 cddb_discid(int tot_trks)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
399 {
5cead4da1db9 Initial import.
darius
parents:
diff changeset
400 int i,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
401 t = 0,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
402 n = 0;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
403
5cead4da1db9 Initial import.
darius
parents:
diff changeset
404 /* For backward compatibility this algorithm must not change */
5cead4da1db9 Initial import.
darius
parents:
diff changeset
405
5cead4da1db9 Initial import.
darius
parents:
diff changeset
406 i = 0;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
407
5cead4da1db9 Initial import.
darius
parents:
diff changeset
408 while (i < tot_trks) {
5cead4da1db9 Initial import.
darius
parents:
diff changeset
409 n = n + cddb_sum((cdtoc[i].min * 60) + cdtoc[i].sec);
5cead4da1db9 Initial import.
darius
parents:
diff changeset
410 i++;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
411 }
5cead4da1db9 Initial import.
darius
parents:
diff changeset
412
5cead4da1db9 Initial import.
darius
parents:
diff changeset
413 t = ((cdtoc[tot_trks].min * 60) + cdtoc[tot_trks].sec) -
5cead4da1db9 Initial import.
darius
parents:
diff changeset
414 ((cdtoc[0].min * 60) + cdtoc[0].sec);
5cead4da1db9 Initial import.
darius
parents:
diff changeset
415
5cead4da1db9 Initial import.
darius
parents:
diff changeset
416 return ((n % 0xff) << 24 | t << 8 | tot_trks);
5cead4da1db9 Initial import.
darius
parents:
diff changeset
417 }
5cead4da1db9 Initial import.
darius
parents:
diff changeset
418
5cead4da1db9 Initial import.
darius
parents:
diff changeset
419 main()
5cead4da1db9 Initial import.
darius
parents:
diff changeset
420 {
5cead4da1db9 Initial import.
darius
parents:
diff changeset
421 int tot_trks;
5cead4da1db9 Initial import.
darius
parents:
diff changeset
422
5cead4da1db9 Initial import.
darius
parents:
diff changeset
423 tot_trks = read_cdtoc_from_drive();
5cead4da1db9 Initial import.
darius
parents:
diff changeset
424 printf("The discid is %08x", cddb_discid(tot_trks));
5cead4da1db9 Initial import.
darius
parents:
diff changeset
425 }
5cead4da1db9 Initial import.
darius
parents:
diff changeset
426
5cead4da1db9 Initial import.
darius
parents:
diff changeset
427
5cead4da1db9 Initial import.
darius
parents:
diff changeset
428 This code assumes that your compiler and architecture support 32-bit
5cead4da1db9 Initial import.
darius
parents:
diff changeset
429 integers.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
430
5cead4da1db9 Initial import.
darius
parents:
diff changeset
431 The cddb_discid function computes the discid based on the CD's TOC data
5cead4da1db9 Initial import.
darius
parents:
diff changeset
432 in MSF form. The frames are ignored for this purpose. The function is
5cead4da1db9 Initial import.
darius
parents:
diff changeset
433 passed a parameter of tot_trks (which is the total number of tracks on
5cead4da1db9 Initial import.
darius
parents:
diff changeset
434 the CD), and returns the discid integer number.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
435
5cead4da1db9 Initial import.
darius
parents:
diff changeset
436 It is assumed that cdtoc[] is an array of data structures (records)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
437 containing the fields min, sec and frame, which are the minute, second
5cead4da1db9 Initial import.
darius
parents:
diff changeset
438 and frame offsets (the starting location) of each track. This
5cead4da1db9 Initial import.
darius
parents:
diff changeset
439 information is read from the TOC of the CD. There are actually
5cead4da1db9 Initial import.
darius
parents:
diff changeset
440 tot_trks + 1 "active" elements in the array, the last one being the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
441 offset of the lead-out (also known as track 0xAA).
5cead4da1db9 Initial import.
darius
parents:
diff changeset
442
5cead4da1db9 Initial import.
darius
parents:
diff changeset
443 The function loops through each track in the TOC, and for each track
5cead4da1db9 Initial import.
darius
parents:
diff changeset
444 it takes the (M * 60) + S (total offset in seconds) of the track and
5cead4da1db9 Initial import.
darius
parents:
diff changeset
445 feeds it to cddb_sum() function, which simply adds the value of each digit
5cead4da1db9 Initial import.
darius
parents:
diff changeset
446 in the decimal string representation of the number. A running sum of this
5cead4da1db9 Initial import.
darius
parents:
diff changeset
447 result for each track is kept in the variable n.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
448
5cead4da1db9 Initial import.
darius
parents:
diff changeset
449 At the end of the loop:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
450 1. t is calculated by subtracting the (M * 60) + S offset of the lead-out
5cead4da1db9 Initial import.
darius
parents:
diff changeset
451 minus the (M * 60) + S offset of first track (yielding the length of
5cead4da1db9 Initial import.
darius
parents:
diff changeset
452 the disc in seconds).
5cead4da1db9 Initial import.
darius
parents:
diff changeset
453
5cead4da1db9 Initial import.
darius
parents:
diff changeset
454 2. The result of (n modulo FFh) is left-shifted by 24 bits.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
455
5cead4da1db9 Initial import.
darius
parents:
diff changeset
456 3. t is left shifted by 8.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
457
5cead4da1db9 Initial import.
darius
parents:
diff changeset
458 The bitwise-OR operation of result 2., 3. and the tot_trks number is
5cead4da1db9 Initial import.
darius
parents:
diff changeset
459 used as the discid.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
460
5cead4da1db9 Initial import.
darius
parents:
diff changeset
461 The discid is represented in hexadecimal form for the purpose of
5cead4da1db9 Initial import.
darius
parents:
diff changeset
462 xmcd cddb file names and the DISCID= field in the xmcd cddb file itself.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
463 If the hexadecimal string is less than 8 characters long, it is
5cead4da1db9 Initial import.
darius
parents:
diff changeset
464 zero-padded to 8 characters (i.e., 3a8f07 becomes 003a8f07). All
5cead4da1db9 Initial import.
darius
parents:
diff changeset
465 alpha characters in the string should be in lower case, where
5cead4da1db9 Initial import.
darius
parents:
diff changeset
466 applicable.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
467
5cead4da1db9 Initial import.
darius
parents:
diff changeset
468 Important note for clients using the MS-Windows MCI interface:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
469
5cead4da1db9 Initial import.
darius
parents:
diff changeset
470 The Windows MCI interface does not provide the MSF location of the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
471 lead-out. Thus, you must compute the lead-out location by taking the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
472 starting position of the last track and add the length of the last track
5cead4da1db9 Initial import.
darius
parents:
diff changeset
473 to it. However, the MCI interface returns the length of the last track
5cead4da1db9 Initial import.
darius
parents:
diff changeset
474 as ONE FRAME SHORT of the actual length found in the CD's TOC. In most
5cead4da1db9 Initial import.
darius
parents:
diff changeset
475 cases this does not affect the disc ID generated, because we truncate
5cead4da1db9 Initial import.
darius
parents:
diff changeset
476 the frame count when computing the disc ID anyway. However, if the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
477 lead-out track has an actual a frame count of 0, the computed quantity
5cead4da1db9 Initial import.
darius
parents:
diff changeset
478 (based on the MSF data returned from the MCI interface) would result in
5cead4da1db9 Initial import.
darius
parents:
diff changeset
479 the seconds being one short and the frame count be 74. For example,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
480 a CD with the last track at an offset of 48m 32s 12f and having a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
481 track length of 2m 50s 63f has a lead-out offset of 51m 23s 0f. Windows
5cead4da1db9 Initial import.
darius
parents:
diff changeset
482 MCI incorrectly reports the length as 2m 50s 62f, which would yield a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
483 lead-out offset of 51m 22s 74f, which causes the resulting truncated
5cead4da1db9 Initial import.
darius
parents:
diff changeset
484 disc length to be off by one second. This will cause an incorrect disc
5cead4da1db9 Initial import.
darius
parents:
diff changeset
485 ID to be generated. You should thus add one frame to the length of the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
486 last track when computing the location of the lead-out.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
487
5cead4da1db9 Initial import.
darius
parents:
diff changeset
488 The easiest way for Windows clients to compute the lead-out given information
5cead4da1db9 Initial import.
darius
parents:
diff changeset
489 in MSF format is like this:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
490
5cead4da1db9 Initial import.
darius
parents:
diff changeset
491 (offset_minutes * 60 * 75) + (offset_seconds * 75) + offset_frames +
5cead4da1db9 Initial import.
darius
parents:
diff changeset
492 (length_minutes * 60 * 75) + (length_seconds * 75) + length_frames + 1 = X
5cead4da1db9 Initial import.
darius
parents:
diff changeset
493
5cead4da1db9 Initial import.
darius
parents:
diff changeset
494 Where X is the offset of the lead-out in frames. To find the lead-out in
5cead4da1db9 Initial import.
darius
parents:
diff changeset
495 seconds, simply divide by 75 and discard the remainder.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
496
5cead4da1db9 Initial import.
darius
parents:
diff changeset
497
5cead4da1db9 Initial import.
darius
parents:
diff changeset
498 APPENDIX B - CDDB FILE FORMAT
5cead4da1db9 Initial import.
darius
parents:
diff changeset
499 -----------------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
500
5cead4da1db9 Initial import.
darius
parents:
diff changeset
501 Database entries must be in the ISO-8859-1 character set (the 8-bit ASCII
5cead4da1db9 Initial import.
darius
parents:
diff changeset
502 extension also known as "Latin alphabet #1" or ISO-Latin-1). Lines must
5cead4da1db9 Initial import.
darius
parents:
diff changeset
503 always be terminated by a newline/linefeed (ctrl-J, or 0Ah) character
5cead4da1db9 Initial import.
darius
parents:
diff changeset
504 or a carriage return character (ctrl-M, or 0Dh) followed by a newline/linefeed
5cead4da1db9 Initial import.
darius
parents:
diff changeset
505 character. All lines in a database entry must be less than or equal to 80
5cead4da1db9 Initial import.
darius
parents:
diff changeset
506 bytes in length, including the terminating character(s). Database entries
5cead4da1db9 Initial import.
darius
parents:
diff changeset
507 with lines that are longer will be considered invalid. There must be no
5cead4da1db9 Initial import.
darius
parents:
diff changeset
508 blank lines in a database entry.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
509
5cead4da1db9 Initial import.
darius
parents:
diff changeset
510 Lines that begin with # are comments. Comments should appear only at the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
511 top of the file before any keywords. Comments in the body of the file are
5cead4da1db9 Initial import.
darius
parents:
diff changeset
512 subject to removal when submitted for inclusion to the database. Comments
5cead4da1db9 Initial import.
darius
parents:
diff changeset
513 may consist only of characters in the set:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
514
5cead4da1db9 Initial import.
darius
parents:
diff changeset
515 { tab (09h); space (20h) through tilde (7Eh) inclusive }
5cead4da1db9 Initial import.
darius
parents:
diff changeset
516
5cead4da1db9 Initial import.
darius
parents:
diff changeset
517 Comments should be ignored by applications using the database file, with
5cead4da1db9 Initial import.
darius
parents:
diff changeset
518 several exceptions described below.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
519
5cead4da1db9 Initial import.
darius
parents:
diff changeset
520 The beginning of the first line in a database entry should consist of the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
521 string "# xmcd". This string identifies the file as an xmcd format CD
5cead4da1db9 Initial import.
darius
parents:
diff changeset
522 database file. More text can appear after the "xmcd", but is unnecessary.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
523
5cead4da1db9 Initial import.
darius
parents:
diff changeset
524 The comments should also contain the string "# Track frame offsets:" followed
5cead4da1db9 Initial import.
darius
parents:
diff changeset
525 by the list of track offsets (the # of frames from the beginning of the CD)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
526 obtained from the table of contents on the CD itself, with any amount of white
5cead4da1db9 Initial import.
darius
parents:
diff changeset
527 space between the "#" and the offset. There should be no other comments
5cead4da1db9 Initial import.
darius
parents:
diff changeset
528 interspersed between the list of track offsets. This list must follow the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
529 initial identifier string described above. Following the offset list should
5cead4da1db9 Initial import.
darius
parents:
diff changeset
530 be at least one blank comment.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
531
5cead4da1db9 Initial import.
darius
parents:
diff changeset
532 After the offset list, the following string should appear:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
533
5cead4da1db9 Initial import.
darius
parents:
diff changeset
534 "# Disc length: N seconds"
5cead4da1db9 Initial import.
darius
parents:
diff changeset
535
5cead4da1db9 Initial import.
darius
parents:
diff changeset
536 where the number of seconds in the CD's play length is substituted for "N".
5cead4da1db9 Initial import.
darius
parents:
diff changeset
537 The number of seconds should be computed by dividing the total number of
5cead4da1db9 Initial import.
darius
parents:
diff changeset
538 1/75th second frames in the CD by 75 and truncating any remainder. This number
5cead4da1db9 Initial import.
darius
parents:
diff changeset
539 should not be rounded.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
540
5cead4da1db9 Initial import.
darius
parents:
diff changeset
541 Note for Windows programmers:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
542
5cead4da1db9 Initial import.
darius
parents:
diff changeset
543 The disc length provided by the Windows MCI interface should not be used here.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
544 Instead, the lead-out (address of the N+1th track) should be used. Since the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
545 MCI interface does not provide the address of the lead-out, it should be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
546 computed by adding the length of the last track to the offset of the last
5cead4da1db9 Initial import.
darius
parents:
diff changeset
547 track and truncating (not rounding) any remaining fraction of a second. Note
5cead4da1db9 Initial import.
darius
parents:
diff changeset
548 that the MCI interface yields an incorrect track offset which must be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
549 corrected by adding one frame to the total frame count when performing the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
550 disc length computation. For more information, see Appendix A.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
551
5cead4da1db9 Initial import.
darius
parents:
diff changeset
552 After the disc length, the following string should appear:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
553
5cead4da1db9 Initial import.
darius
parents:
diff changeset
554 "# Revision: N"
5cead4da1db9 Initial import.
darius
parents:
diff changeset
555
5cead4da1db9 Initial import.
darius
parents:
diff changeset
556 where the database entry revision (decimal integer) is substituted for "N".
5cead4da1db9 Initial import.
darius
parents:
diff changeset
557
5cead4da1db9 Initial import.
darius
parents:
diff changeset
558 Files missing a revision are assumed to have a revision revision level of 0.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
559 The revision is used for database management when comparing two entries in
5cead4da1db9 Initial import.
darius
parents:
diff changeset
560 order to determine which is the most recent. Client programs which allow the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
561 user to modify a database entry should increment the revision when the user
5cead4da1db9 Initial import.
darius
parents:
diff changeset
562 submits a modified entry for inclusion in the database.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
563
5cead4da1db9 Initial import.
darius
parents:
diff changeset
564 After the revision, the following string should appear:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
565
5cead4da1db9 Initial import.
darius
parents:
diff changeset
566 "# Submitted via: client_name client_version optional_comments"
5cead4da1db9 Initial import.
darius
parents:
diff changeset
567
5cead4da1db9 Initial import.
darius
parents:
diff changeset
568 where the name of the client submitting the entry is substituted for
5cead4da1db9 Initial import.
darius
parents:
diff changeset
569 "client_name", the version of the client is substituted for "client_version",
5cead4da1db9 Initial import.
darius
parents:
diff changeset
570 and "optional_comments" is any sequence of legal characters. Clients which
5cead4da1db9 Initial import.
darius
parents:
diff changeset
571 allow users to modify database entries read from the database should update
5cead4da1db9 Initial import.
darius
parents:
diff changeset
572 this string with their own information before submitting.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
573
5cead4da1db9 Initial import.
darius
parents:
diff changeset
574 The "client_version" field has a very specific format which should be observed:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
575
5cead4da1db9 Initial import.
darius
parents:
diff changeset
576 [leading text]version_number[release type][level]
5cead4da1db9 Initial import.
darius
parents:
diff changeset
577
5cead4da1db9 Initial import.
darius
parents:
diff changeset
578 Where:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
579
5cead4da1db9 Initial import.
darius
parents:
diff changeset
580 Leading text: is any string which does not include numbers.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
581 Version number and level: is any (possibly) decimal-separated list of
5cead4da1db9 Initial import.
darius
parents:
diff changeset
582 positive numbers.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
583 Release type: is a string of the form:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
584 alpha, a, beta, b, patchlevel, patch, pl
5cead4da1db9 Initial import.
darius
parents:
diff changeset
585 Level: is a positive number.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
586
5cead4da1db9 Initial import.
darius
parents:
diff changeset
587 For example:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
588
5cead4da1db9 Initial import.
darius
parents:
diff changeset
589 release:2.35.1alpha7
5cead4da1db9 Initial import.
darius
parents:
diff changeset
590 v4.0PL0
5cead4da1db9 Initial import.
darius
parents:
diff changeset
591 2.4
5cead4da1db9 Initial import.
darius
parents:
diff changeset
592
5cead4da1db9 Initial import.
darius
parents:
diff changeset
593 The only required portion of the version field is the version number. The
5cead4da1db9 Initial import.
darius
parents:
diff changeset
594 other parts are optional, though it is strongly recommended that the release
5cead4da1db9 Initial import.
darius
parents:
diff changeset
595 type field be filled in if relevant. Strict version checking may be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
596 applied by software which evaluates the submitter revision, so it is wise
5cead4da1db9 Initial import.
darius
parents:
diff changeset
597 to make it clear when a release is beta, etc.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
598
5cead4da1db9 Initial import.
darius
parents:
diff changeset
599 Following the comments is the disc data. Each line of disc data consists
5cead4da1db9 Initial import.
darius
parents:
diff changeset
600 of the format "KEYWORD=data", where "KEYWORD" is a valid keyword as described
5cead4da1db9 Initial import.
darius
parents:
diff changeset
601 below and "data" is any string consisting of characters in the set:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
602
5cead4da1db9 Initial import.
darius
parents:
diff changeset
603 { space (20h) through tilde (7Eh) inclusive; no-break-space (A0h) through
5cead4da1db9 Initial import.
darius
parents:
diff changeset
604 y-umlaut (FFh) inclusive }
5cead4da1db9 Initial import.
darius
parents:
diff changeset
605
5cead4da1db9 Initial import.
darius
parents:
diff changeset
606 Newlines (0Ah), tabs (09h) and backslashes (2Fh) may be represented by the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
607 two-character sequences "\n", "\t" and "\\" respectively. Client programs must
5cead4da1db9 Initial import.
darius
parents:
diff changeset
608 translate these sequences to the appropriate characters when displaying
5cead4da1db9 Initial import.
darius
parents:
diff changeset
609 disc data.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
610
5cead4da1db9 Initial import.
darius
parents:
diff changeset
611 All of the applicable keywords must be present in the file. They must appear
5cead4da1db9 Initial import.
darius
parents:
diff changeset
612 in the file in the order shown below. Multiple occurrences of the same keyword
5cead4da1db9 Initial import.
darius
parents:
diff changeset
613 indicate that the data contained on those lines should be concatenated; this
5cead4da1db9 Initial import.
darius
parents:
diff changeset
614 applies to any of the textual fields. There is no practical limit to the size
5cead4da1db9 Initial import.
darius
parents:
diff changeset
615 of any of the textual fields or a database entry itself, though the CDDB server
5cead4da1db9 Initial import.
darius
parents:
diff changeset
616 software may place a restriction on especially large entries. Valid keywords
5cead4da1db9 Initial import.
darius
parents:
diff changeset
617 are as follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
618
5cead4da1db9 Initial import.
darius
parents:
diff changeset
619 DISCID: The data following this keyword should contain the 8-byte disc ID.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
620 indicated by the track offsets in the comment section. The algorithm
5cead4da1db9 Initial import.
darius
parents:
diff changeset
621 for generating the disc ID is explained in Appendix A.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
622
5cead4da1db9 Initial import.
darius
parents:
diff changeset
623 DTITLE: Technically, this may consist of any data, but by convention contains
5cead4da1db9 Initial import.
darius
parents:
diff changeset
624 the artist and disc title (in that order) separated by a "/" with a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
625 single space on either side to separate it from the text. If the "/"
5cead4da1db9 Initial import.
darius
parents:
diff changeset
626 is absent, it is implied that the artist and disc title are the same.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
627
5cead4da1db9 Initial import.
darius
parents:
diff changeset
628 TTITLEN:There must be one of these for each track in the CD. The track
5cead4da1db9 Initial import.
darius
parents:
diff changeset
629 number should be substituted for the "N", starting with 0. This field
5cead4da1db9 Initial import.
darius
parents:
diff changeset
630 should contain the title of the Nth track on the CD.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
631
5cead4da1db9 Initial import.
darius
parents:
diff changeset
632 EXTD: This field contains the "extended data" for the CD. This is intended
5cead4da1db9 Initial import.
darius
parents:
diff changeset
633 to be used as a place for interesting information related to the CD,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
634 such as credits, et cetera. If there is more than one of these lines
5cead4da1db9 Initial import.
darius
parents:
diff changeset
635 in the file, the data is concatenated. This allows for extended data
5cead4da1db9 Initial import.
darius
parents:
diff changeset
636 of arbitrary length.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
637
5cead4da1db9 Initial import.
darius
parents:
diff changeset
638 EXTTN: This field contains the "extended track data" for track "N". There
5cead4da1db9 Initial import.
darius
parents:
diff changeset
639 must be one of these for each track in the CD. The track number
5cead4da1db9 Initial import.
darius
parents:
diff changeset
640 should be substituted for the "N", starting with 0. This field is
5cead4da1db9 Initial import.
darius
parents:
diff changeset
641 intended to be used as a place for interesting information related to
5cead4da1db9 Initial import.
darius
parents:
diff changeset
642 the Nth track, such as the author and other credits, or lyrics. If
5cead4da1db9 Initial import.
darius
parents:
diff changeset
643 there is more than one of these lines in the file, the data is
5cead4da1db9 Initial import.
darius
parents:
diff changeset
644 concatenated. This allows for extended data of arbitrary length.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
645
5cead4da1db9 Initial import.
darius
parents:
diff changeset
646 PLAYORDER:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
647 This field contains a comma-separated list of track numbers which
5cead4da1db9 Initial import.
darius
parents:
diff changeset
648 represent a programmed track play order. This field is generally
5cead4da1db9 Initial import.
darius
parents:
diff changeset
649 stripped of data in non-local database entries. Applications that
5cead4da1db9 Initial import.
darius
parents:
diff changeset
650 submit entries for addition to the main database should strip this
5cead4da1db9 Initial import.
darius
parents:
diff changeset
651 keyword of data.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
652
5cead4da1db9 Initial import.
darius
parents:
diff changeset
653
5cead4da1db9 Initial import.
darius
parents:
diff changeset
654 An example database entry follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
655
5cead4da1db9 Initial import.
darius
parents:
diff changeset
656 # xmcd
5cead4da1db9 Initial import.
darius
parents:
diff changeset
657 # Copyright (C) 1993-1998 CDDB, Inc.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
658 #
5cead4da1db9 Initial import.
darius
parents:
diff changeset
659 # Track frame offsets:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
660 # 150
5cead4da1db9 Initial import.
darius
parents:
diff changeset
661 # 47275
5cead4da1db9 Initial import.
darius
parents:
diff changeset
662 # 76072
5cead4da1db9 Initial import.
darius
parents:
diff changeset
663 # 89507
5cead4da1db9 Initial import.
darius
parents:
diff changeset
664 # 117547
5cead4da1db9 Initial import.
darius
parents:
diff changeset
665 # 136377
5cead4da1db9 Initial import.
darius
parents:
diff changeset
666 # 157530
5cead4da1db9 Initial import.
darius
parents:
diff changeset
667 #
5cead4da1db9 Initial import.
darius
parents:
diff changeset
668 # Disc length: 2663 seconds
5cead4da1db9 Initial import.
darius
parents:
diff changeset
669 #
5cead4da1db9 Initial import.
darius
parents:
diff changeset
670 # Revision: 2
5cead4da1db9 Initial import.
darius
parents:
diff changeset
671 # Submitted via: xmcd 2.3beta PL0
5cead4da1db9 Initial import.
darius
parents:
diff changeset
672 #
5cead4da1db9 Initial import.
darius
parents:
diff changeset
673 DISCID=470a6507
5cead4da1db9 Initial import.
darius
parents:
diff changeset
674 DTITLE=Led Zeppelin / Presence
5cead4da1db9 Initial import.
darius
parents:
diff changeset
675 TTITLE0=Achilles' Last Stand
5cead4da1db9 Initial import.
darius
parents:
diff changeset
676 TTITLE1=For Your Life
5cead4da1db9 Initial import.
darius
parents:
diff changeset
677 TTITLE2=Royal Orleans
5cead4da1db9 Initial import.
darius
parents:
diff changeset
678 TTITLE3=Nobody's Fault But Mine
5cead4da1db9 Initial import.
darius
parents:
diff changeset
679 TTITLE4=Candy Store Rock
5cead4da1db9 Initial import.
darius
parents:
diff changeset
680 TTITLE5=Hots On For Nowhere
5cead4da1db9 Initial import.
darius
parents:
diff changeset
681 TTITLE6=Tea For One
5cead4da1db9 Initial import.
darius
parents:
diff changeset
682 EXTD=Producer: Jimmy Page\nExecutive Producer: Peter Gr
5cead4da1db9 Initial import.
darius
parents:
diff changeset
683 EXTD=ant\n\nUPC: 7567-90329-2\nLABEL: Atlantic Recordin
5cead4da1db9 Initial import.
darius
parents:
diff changeset
684 EXTD=g Corporation\nYEAR: 1976
5cead4da1db9 Initial import.
darius
parents:
diff changeset
685 EXTT0=Jimmy Page and Robert Plant
5cead4da1db9 Initial import.
darius
parents:
diff changeset
686 EXTT1=Jimmy Page and Robert Plant
5cead4da1db9 Initial import.
darius
parents:
diff changeset
687 EXTT2=John Bonham, John Paul Jones, Jimmy Page and\nRob
5cead4da1db9 Initial import.
darius
parents:
diff changeset
688 EXTT2=ert Plant
5cead4da1db9 Initial import.
darius
parents:
diff changeset
689 EXTT3=Jimmy Page and Robert Plant
5cead4da1db9 Initial import.
darius
parents:
diff changeset
690 EXTT4=Jimmy Page and Robert Plant
5cead4da1db9 Initial import.
darius
parents:
diff changeset
691 EXTT5=Jimmy Page and Robert Plant
5cead4da1db9 Initial import.
darius
parents:
diff changeset
692 EXTT6=Jimmy Page and Robert Plant
5cead4da1db9 Initial import.
darius
parents:
diff changeset
693 PLAYORDER=
5cead4da1db9 Initial import.
darius
parents:
diff changeset
694
5cead4da1db9 Initial import.
darius
parents:
diff changeset
695 Please note that the EXTD section above is split into three pieces. When
5cead4da1db9 Initial import.
darius
parents:
diff changeset
696 displayed to the user, it should appear like this:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
697
5cead4da1db9 Initial import.
darius
parents:
diff changeset
698 Producer: Jimmy Page
5cead4da1db9 Initial import.
darius
parents:
diff changeset
699 Executive Producer: Peter Grant
5cead4da1db9 Initial import.
darius
parents:
diff changeset
700
5cead4da1db9 Initial import.
darius
parents:
diff changeset
701 UPC: 7567-90329-2
5cead4da1db9 Initial import.
darius
parents:
diff changeset
702 LABEL: Atlantic Recording Corporation
5cead4da1db9 Initial import.
darius
parents:
diff changeset
703 YEAR: 1976
5cead4da1db9 Initial import.
darius
parents:
diff changeset
704
5cead4da1db9 Initial import.
darius
parents:
diff changeset
705
5cead4da1db9 Initial import.
darius
parents:
diff changeset
706 APPENDIX C - CDDB SERVER PROTOCOL
5cead4da1db9 Initial import.
darius
parents:
diff changeset
707 ---------------------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
708
5cead4da1db9 Initial import.
darius
parents:
diff changeset
709
5cead4da1db9 Initial import.
darius
parents:
diff changeset
710 CDDB Protocol
5cead4da1db9 Initial import.
darius
parents:
diff changeset
711 -------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
712
5cead4da1db9 Initial import.
darius
parents:
diff changeset
713
5cead4da1db9 Initial import.
darius
parents:
diff changeset
714 Notation:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
715 -> : client to server
5cead4da1db9 Initial import.
darius
parents:
diff changeset
716 <- : server to client
5cead4da1db9 Initial import.
darius
parents:
diff changeset
717
5cead4da1db9 Initial import.
darius
parents:
diff changeset
718 terminating marker: `.' character in the beginning of a line
5cead4da1db9 Initial import.
darius
parents:
diff changeset
719
5cead4da1db9 Initial import.
darius
parents:
diff changeset
720
5cead4da1db9 Initial import.
darius
parents:
diff changeset
721 Server response code (three digit code):
5cead4da1db9 Initial import.
darius
parents:
diff changeset
722
5cead4da1db9 Initial import.
darius
parents:
diff changeset
723 First digit:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
724 1xx Informative message
5cead4da1db9 Initial import.
darius
parents:
diff changeset
725 2xx Command OK
5cead4da1db9 Initial import.
darius
parents:
diff changeset
726 3xx Command OK so far, continue
5cead4da1db9 Initial import.
darius
parents:
diff changeset
727 4xx Command OK, but cannot be performed for some specified reasons
5cead4da1db9 Initial import.
darius
parents:
diff changeset
728 5xx Command unimplemented, incorrect, or program error
5cead4da1db9 Initial import.
darius
parents:
diff changeset
729
5cead4da1db9 Initial import.
darius
parents:
diff changeset
730 Second digit:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
731 x0x Ready for further commands
5cead4da1db9 Initial import.
darius
parents:
diff changeset
732 x1x More server-to-client output follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
733 x2x More client-to-server input follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
734 x3x Connection will close
5cead4da1db9 Initial import.
darius
parents:
diff changeset
735
5cead4da1db9 Initial import.
darius
parents:
diff changeset
736 Third digit:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
737 xx[0-9] Command-specific code
5cead4da1db9 Initial import.
darius
parents:
diff changeset
738
5cead4da1db9 Initial import.
darius
parents:
diff changeset
739 It is best if client applications treat response codes generically when
5cead4da1db9 Initial import.
darius
parents:
diff changeset
740 possible, rather than having hard-coded "expected" or known codes in the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
741 application. Here is the suggested method for generically handling error
5cead4da1db9 Initial import.
darius
parents:
diff changeset
742 codes:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
743
5cead4da1db9 Initial import.
darius
parents:
diff changeset
744 20x - OK, command successful. No action necessary.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
745 21x - OK, prepare to read data from the server. If unexpected you can
5cead4da1db9 Initial import.
darius
parents:
diff changeset
746 disconnect, but it's probably an error on the app's part so retrying
5cead4da1db9 Initial import.
darius
parents:
diff changeset
747 in that case is not indicated.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
748 22x - OK, prepare to give the server data. If unexpected, treat as above.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
749 23x - OK, connection closing at client's request.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
750
5cead4da1db9 Initial import.
darius
parents:
diff changeset
751 40x - Command failed due to server error or permission problem. Reconnecting
5cead4da1db9 Initial import.
darius
parents:
diff changeset
752 to a different server might help.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
753 41x - Command failed, as above. Information follows regarding the problem,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
754 so client should read it and perhaps display it. Reconnect as above.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
755 43x - Command failed, as 40x. Connection is dropped by the server. Reconnect
5cead4da1db9 Initial import.
darius
parents:
diff changeset
756 as 40x.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
757
5cead4da1db9 Initial import.
darius
parents:
diff changeset
758 50x - Command failed due to client error. Retrying in any fashion is probably
5cead4da1db9 Initial import.
darius
parents:
diff changeset
759 pointless, because a bug in the client is usually indicated.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
760 51x - As above, with explanatory information following.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
761 53x - Some sort of client error forced the server to disconnect. Connection is
5cead4da1db9 Initial import.
darius
parents:
diff changeset
762 dropped. Retry might help, because this code is often due to a timeout
5cead4da1db9 Initial import.
darius
parents:
diff changeset
763 condition or some other limit that gets reset upon reconnect.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
764
5cead4da1db9 Initial import.
darius
parents:
diff changeset
765 It is okay to ignore the 'x' portion of an error code, but if there are
5cead4da1db9 Initial import.
darius
parents:
diff changeset
766 specific ones that you want to react to, you can. Just don't preclude
5cead4da1db9 Initial import.
darius
parents:
diff changeset
767 reacting to general codes at any time. Any 2-level codes that don't appear
5cead4da1db9 Initial import.
darius
parents:
diff changeset
768 here, such as "42x" are either not possible or will not be seen by clients.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
769 You might want to have a general default case for these; consider them a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
770 server error indicating a serious problem.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
771
5cead4da1db9 Initial import.
darius
parents:
diff changeset
772
5cead4da1db9 Initial import.
darius
parents:
diff changeset
773 CDDB Protocol Level 1:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
774 ----------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
775
5cead4da1db9 Initial import.
darius
parents:
diff changeset
776 Initial client-server handshake:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
777 --------------------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
778 Note: This command is not used directly in HTTP mode. It is implied by
5cead4da1db9 Initial import.
darius
parents:
diff changeset
779 the "hello=" field in the HTTP query. See Addendum A below for more
5cead4da1db9 Initial import.
darius
parents:
diff changeset
780 information. It is described here only as a reference.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
781
5cead4da1db9 Initial import.
darius
parents:
diff changeset
782 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
783 -> cddb hello username hostname clientname version
5cead4da1db9 Initial import.
darius
parents:
diff changeset
784
5cead4da1db9 Initial import.
darius
parents:
diff changeset
785 username:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
786 Login name of user. Example: johndoe
5cead4da1db9 Initial import.
darius
parents:
diff changeset
787 hostname:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
788 Host name of client. Example: abc.fubar.com
5cead4da1db9 Initial import.
darius
parents:
diff changeset
789 clientname:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
790 The name of the connecting client. Example: xmcd, cda, EasyCD,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
791 et cetera. Do not use the name of another client which already
5cead4da1db9 Initial import.
darius
parents:
diff changeset
792 exists.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
793 version:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
794 Version number of client software. Example: v1.0PL0
5cead4da1db9 Initial import.
darius
parents:
diff changeset
795
5cead4da1db9 Initial import.
darius
parents:
diff changeset
796 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
797 <- code hello and welcome username@hostname running clientname version
5cead4da1db9 Initial import.
darius
parents:
diff changeset
798
5cead4da1db9 Initial import.
darius
parents:
diff changeset
799 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
800 200 Handshake successful
5cead4da1db9 Initial import.
darius
parents:
diff changeset
801 431 Handshake not successful, closing connection
5cead4da1db9 Initial import.
darius
parents:
diff changeset
802 402 Already shook hands
5cead4da1db9 Initial import.
darius
parents:
diff changeset
803
5cead4da1db9 Initial import.
darius
parents:
diff changeset
804
5cead4da1db9 Initial import.
darius
parents:
diff changeset
805 CDDB lscat:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
806 ----------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
807 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
808 -> cddb lscat
5cead4da1db9 Initial import.
darius
parents:
diff changeset
809
5cead4da1db9 Initial import.
darius
parents:
diff changeset
810 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
811 <- code Okay category list follows
5cead4da1db9 Initial import.
darius
parents:
diff changeset
812 <- category
5cead4da1db9 Initial import.
darius
parents:
diff changeset
813 <- category
5cead4da1db9 Initial import.
darius
parents:
diff changeset
814 <- (more categories...)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
815 <- .
5cead4da1db9 Initial import.
darius
parents:
diff changeset
816
5cead4da1db9 Initial import.
darius
parents:
diff changeset
817 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
818 210 Okay category list follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
819 category:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
820 CD category. Example: rock
5cead4da1db9 Initial import.
darius
parents:
diff changeset
821
5cead4da1db9 Initial import.
darius
parents:
diff changeset
822
5cead4da1db9 Initial import.
darius
parents:
diff changeset
823 CDDB query:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
824 -----------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
825 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
826 -> cddb query discid ntrks off1 off2 ... nsecs
5cead4da1db9 Initial import.
darius
parents:
diff changeset
827
5cead4da1db9 Initial import.
darius
parents:
diff changeset
828 discid:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
829 CD disc ID number. Example: f50a3b13
5cead4da1db9 Initial import.
darius
parents:
diff changeset
830 ntrks:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
831 Total number of tracks on CD.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
832 off1, off2, ...:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
833 Frame offset of the starting location of each track.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
834 nsecs:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
835 Total playing length of CD in seconds.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
836
5cead4da1db9 Initial import.
darius
parents:
diff changeset
837 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
838 <- code categ discid dtitle
5cead4da1db9 Initial import.
darius
parents:
diff changeset
839 or
5cead4da1db9 Initial import.
darius
parents:
diff changeset
840 <- code close matches found
5cead4da1db9 Initial import.
darius
parents:
diff changeset
841 <- categ discid dtitle
5cead4da1db9 Initial import.
darius
parents:
diff changeset
842 <- categ discid dtitle
5cead4da1db9 Initial import.
darius
parents:
diff changeset
843 <- (more matches...)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
844 <- .
5cead4da1db9 Initial import.
darius
parents:
diff changeset
845
5cead4da1db9 Initial import.
darius
parents:
diff changeset
846 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
847 200 Found exact match
5cead4da1db9 Initial import.
darius
parents:
diff changeset
848 211 Found inexact matches, list follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
849 202 No match found
5cead4da1db9 Initial import.
darius
parents:
diff changeset
850 403 Database entry is corrupt
5cead4da1db9 Initial import.
darius
parents:
diff changeset
851 409 No handshake
5cead4da1db9 Initial import.
darius
parents:
diff changeset
852 categ:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
853 CD category. Example: rock
5cead4da1db9 Initial import.
darius
parents:
diff changeset
854 discid:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
855 CD disc ID number of the found entry. Example: f50a3b13
5cead4da1db9 Initial import.
darius
parents:
diff changeset
856 dtitle:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
857 The Disc Artist and Disc Title (The DTITLE line). For example:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
858 Pink Floyd / The Dark Side of the Moon
5cead4da1db9 Initial import.
darius
parents:
diff changeset
859
5cead4da1db9 Initial import.
darius
parents:
diff changeset
860
5cead4da1db9 Initial import.
darius
parents:
diff changeset
861 CDDB read:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
862 ----------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
863 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
864 -> cddb read categ discid
5cead4da1db9 Initial import.
darius
parents:
diff changeset
865
5cead4da1db9 Initial import.
darius
parents:
diff changeset
866 categ:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
867 CD category. Example: rock
5cead4da1db9 Initial import.
darius
parents:
diff changeset
868 discid:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
869 CD disc ID number. Example: f50a3b13
5cead4da1db9 Initial import.
darius
parents:
diff changeset
870
5cead4da1db9 Initial import.
darius
parents:
diff changeset
871 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
872 <- code categ discid
5cead4da1db9 Initial import.
darius
parents:
diff changeset
873 <- # xmcd CD database file
5cead4da1db9 Initial import.
darius
parents:
diff changeset
874 <- # ...
5cead4da1db9 Initial import.
darius
parents:
diff changeset
875 <- (CDDB data...)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
876 <- .
5cead4da1db9 Initial import.
darius
parents:
diff changeset
877 or
5cead4da1db9 Initial import.
darius
parents:
diff changeset
878 <- code categ discid No such CD entry in database
5cead4da1db9 Initial import.
darius
parents:
diff changeset
879
5cead4da1db9 Initial import.
darius
parents:
diff changeset
880 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
881 210 OK, CDDB database entry follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
882 401 Specified CDDB entry not found.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
883 402 Server error.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
884 403 Database entry is corrupt.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
885 409 No handshake.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
886 417 Access limit exceeded, explanation follows (until marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
887 categ:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
888 CD category. Example: rock
5cead4da1db9 Initial import.
darius
parents:
diff changeset
889 discid:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
890 CD disc ID number. Example: f50a3b13
5cead4da1db9 Initial import.
darius
parents:
diff changeset
891
5cead4da1db9 Initial import.
darius
parents:
diff changeset
892
5cead4da1db9 Initial import.
darius
parents:
diff changeset
893 Help information:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
894 -----------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
895 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
896 -> help
5cead4da1db9 Initial import.
darius
parents:
diff changeset
897 or
5cead4da1db9 Initial import.
darius
parents:
diff changeset
898 -> help cmd
5cead4da1db9 Initial import.
darius
parents:
diff changeset
899
5cead4da1db9 Initial import.
darius
parents:
diff changeset
900 cmd:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
901 CDDB command. Example: quit
5cead4da1db9 Initial import.
darius
parents:
diff changeset
902
5cead4da1db9 Initial import.
darius
parents:
diff changeset
903 or
5cead4da1db9 Initial import.
darius
parents:
diff changeset
904
5cead4da1db9 Initial import.
darius
parents:
diff changeset
905 -> help cmd subcmd
5cead4da1db9 Initial import.
darius
parents:
diff changeset
906
5cead4da1db9 Initial import.
darius
parents:
diff changeset
907 cmd:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
908 CDDB command. Example: cddb
5cead4da1db9 Initial import.
darius
parents:
diff changeset
909 subcmd:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
910 CDDB command argument. Example: query
5cead4da1db9 Initial import.
darius
parents:
diff changeset
911
5cead4da1db9 Initial import.
darius
parents:
diff changeset
912 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
913 <- code Help information follows
5cead4da1db9 Initial import.
darius
parents:
diff changeset
914 <- (help data ...)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
915 <- .
5cead4da1db9 Initial import.
darius
parents:
diff changeset
916 or
5cead4da1db9 Initial import.
darius
parents:
diff changeset
917 <- code no help information available
5cead4da1db9 Initial import.
darius
parents:
diff changeset
918
5cead4da1db9 Initial import.
darius
parents:
diff changeset
919 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
920 210 OK, help information follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
921 401 No help information available
5cead4da1db9 Initial import.
darius
parents:
diff changeset
922
5cead4da1db9 Initial import.
darius
parents:
diff changeset
923
5cead4da1db9 Initial import.
darius
parents:
diff changeset
924 Message of the day:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
925 ------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
926 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
927 -> motd
5cead4da1db9 Initial import.
darius
parents:
diff changeset
928
5cead4da1db9 Initial import.
darius
parents:
diff changeset
929 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
930 <- code Last modified: date MOTD follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
931 <- (message text)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
932 <- .
5cead4da1db9 Initial import.
darius
parents:
diff changeset
933
5cead4da1db9 Initial import.
darius
parents:
diff changeset
934 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
935 210 Last modified: 05/31/96 06:31:14 MOTD follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
936 401 No message of the day available
5cead4da1db9 Initial import.
darius
parents:
diff changeset
937 date:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
938 The date the text of the message of the day was modified. The date
5cead4da1db9 Initial import.
darius
parents:
diff changeset
939 appears in the following format:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
940
5cead4da1db9 Initial import.
darius
parents:
diff changeset
941 05/31/96 06:31:14
5cead4da1db9 Initial import.
darius
parents:
diff changeset
942
5cead4da1db9 Initial import.
darius
parents:
diff changeset
943 This value may be used by client software as a message timestamp
5cead4da1db9 Initial import.
darius
parents:
diff changeset
944 for purposes of determining if it has already been displayed. This
5cead4da1db9 Initial import.
darius
parents:
diff changeset
945 format was chosen because it is more easily parsed than the standard
5cead4da1db9 Initial import.
darius
parents:
diff changeset
946 ctime() format.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
947
5cead4da1db9 Initial import.
darius
parents:
diff changeset
948
5cead4da1db9 Initial import.
darius
parents:
diff changeset
949 Server protocol level:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
950 ----------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
951 Note: This command is not used directly in HTTP mode. It is implied by
5cead4da1db9 Initial import.
darius
parents:
diff changeset
952 the "proto=" field in the HTTP query. See Addendum A below for more
5cead4da1db9 Initial import.
darius
parents:
diff changeset
953 information. It is described here only as a reference.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
954
5cead4da1db9 Initial import.
darius
parents:
diff changeset
955 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
956 -> proto [level]
5cead4da1db9 Initial import.
darius
parents:
diff changeset
957
5cead4da1db9 Initial import.
darius
parents:
diff changeset
958 level:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
959 The (numerical) protocol level to set the server to.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
960
5cead4da1db9 Initial import.
darius
parents:
diff changeset
961 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
962 <- code CDDB protocol level: current cur_level, supported supported_level
5cead4da1db9 Initial import.
darius
parents:
diff changeset
963 or
5cead4da1db9 Initial import.
darius
parents:
diff changeset
964 <- code OK, protocol version now: cur_level
5cead4da1db9 Initial import.
darius
parents:
diff changeset
965
5cead4da1db9 Initial import.
darius
parents:
diff changeset
966 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
967 200 CDDB protocol level: current cur_level, supported supp_level
5cead4da1db9 Initial import.
darius
parents:
diff changeset
968 201 OK, protocol version now: cur_level
5cead4da1db9 Initial import.
darius
parents:
diff changeset
969 501 Illegal protocol level.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
970 502 Protocol level already cur_level.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
971 cur_level:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
972 The current protocol level at which the server is running.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
973 supported_level:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
974 The maximum supported protocol level.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
975
5cead4da1db9 Initial import.
darius
parents:
diff changeset
976
5cead4da1db9 Initial import.
darius
parents:
diff changeset
977 Server sites:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
978 --------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
979 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
980 -> sites
5cead4da1db9 Initial import.
darius
parents:
diff changeset
981
5cead4da1db9 Initial import.
darius
parents:
diff changeset
982 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
983 <- code OK, site information follows (until terminating `.')
5cead4da1db9 Initial import.
darius
parents:
diff changeset
984 <- (data)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
985 <- .
5cead4da1db9 Initial import.
darius
parents:
diff changeset
986
5cead4da1db9 Initial import.
darius
parents:
diff changeset
987 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
988 210 Ok, site information follows
5cead4da1db9 Initial import.
darius
parents:
diff changeset
989 401 No site information available.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
990
5cead4da1db9 Initial import.
darius
parents:
diff changeset
991 The data format is as follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
992 site port latitude longitude description
5cead4da1db9 Initial import.
darius
parents:
diff changeset
993
5cead4da1db9 Initial import.
darius
parents:
diff changeset
994 The fields are as follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
995 site:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
996 The Internet address of the remote site.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
997 port:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
998 The port at which the server resides on that site.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
999 latitude:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1000 The latitude of the server site. The format is as follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1001 CDDD.MM
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1002 Where "C" is the compass direction (N, S), "DDD" is the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1003 degrees, and "MM" is the minutes.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1004 longitude:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1005 The longitude of the server site. Format is as above, except
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1006 the compass direction must be one of (E, W).
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1007 description:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1008 A short description of the geographical location of the site.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1009
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1010 Example:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1011 ca.us.cddb.com 888 N037.23 W122.01 Fremont, CA USA
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1012
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1013
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1014 Server status:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1015 --------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1016 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1017 -> stat
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1018
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1019 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1020 <- code OK, status information follows (until terminating `.')
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1021 <- (data)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1022 <- .
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1023
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1024 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1025 210 Ok, status information follows
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1026
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1027 The possible data is as follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1028 current proto: <current_level>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1029 An integer representing the server's current operating protocol
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1030 level.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1031 max proto: <max_level>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1032 The maximum supported protocol level.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1033 gets: <yes | no>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1034 Whether or not the client is allowed to get log information,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1035 according to the string "yes" or "no".
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1036 updates: <yes | no>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1037 Whether or not the client is allowed to initiate a database
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1038 update, according to the string "yes" or "no".
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1039 posting: <yes | no>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1040 Whether or not the client is allowed to post new entries,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1041 according to the string "yes" or "no".
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1042 quotes: <yes | no>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1043 Whether or not quoted arguments are enabled, according to
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1044 the string "yes" or "no".
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1045 current users: <num_users>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1046 The number of users currently connected to the server.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1047 max users: <num_max_users>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1048 The number of users that can concurrently connect to the server.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1049 strip ext: <yes | no>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1050 Whether or not extended data is stripped by the server before
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1051 presented to the user.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1052 Database entries: <num_db_entries>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1053 The total number of entries in the database.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1054 Database entries by category:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1055 This field is followed by a list of catgories and the number
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1056 of entries in that category. Each entry is of the following
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1057 format:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1058
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1059 <white space>catgory: <num_db_entries>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1060
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1061 The list of entries is terminated by the first line that does
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1062 not begin with white space.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1063
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1064 Pending file transmissions:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1065 This field is followed by a list of sites that are fed new
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1066 database entries at periodic intervals, and the number of
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1067 entries that have yet to be transmitted to that site.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1068 Each entry is of the following format:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1069
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1070 <white space>site: <num_db_entries>
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1071
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1072 The list of entries is terminated by the first line that does
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1073 not begin with white space.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1074
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1075 This list may grow as needed, so clients must expect possible
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1076 unrecognizable data. Also, additional fields may be added to
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1077 the currently existing lines, although no existing fields will
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1078 be removed or change position.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1079
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1080
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1081 Server version:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1082 ---------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1083 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1084 -> ver
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1085
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1086 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1087 <- code servername version copyright
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1088 or
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1089 <- code Version information follows
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1090
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1091 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1092 200 Version information.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1093 211 OK, version information follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1094 version:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1095 Server version. Example: v1.0PL0
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1096 copyright:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1097 Copyright string. Example: Copyright (c) 1996 Steve Scherf
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1098
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1099
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1100 Server users:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1101 -------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1102 Client command:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1103 -> whom
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1104
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1105 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1106 <- code User list follows
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1107
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1108 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1109 210 OK, user list follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1110 401 No user information available.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1111
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1112
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1113 Reserved errors:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1114 ----------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1115
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1116 The following error codes are reserved, and will never be returned as a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1117 response to a CDDB protocol command. They are intended to be used internally
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1118 by clients that have a need for generating pseudo-responses.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1119
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1120 600-699
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1121
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1122
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1123 CDDB Protocol Level 2:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1124 ----------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1125
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1126 In all respects, protocol level 2 is the same as level 1, with the exceptions
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1127 listed below.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1128
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1129 Arguments to commands may be surrounded by double quotes. All characters
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1130 within the quotes, including white space, are included in the argument. All
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1131 white space is replaced by the `_' (2Dh) character by the server. White space
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1132 is defined as ` ' (20h) and `^I' (control-I, or 09h).
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1133
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1134 Arguments containing quotes that should not be interpreted with the special
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1135 meaning described above should be escaped with a preceding backslash character,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1136 or '\' (5Ch). If an actual backslash appears in an argument, it should be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1137 escaped with a preceding backslash. In both cases, the preceding backslash
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1138 will be removed from the input before being interpreted.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1139
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1140
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1141 CDDB Protocol Level 3:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1142 ----------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1143
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1144 Protocol level 3 is the same as level 2, with the exception listed below.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1145
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1146 The output of the "sites" command has changed to meet the folowing description:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1147
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1148 The data format is as follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1149 site protocol port address latitude longitude description
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1150
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1151 The fields are as follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1152 site:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1153 The Internet address of the remote site.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1154 protocol:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1155 The transfer protocol used to access the site. Sites specified
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1156 as "cddbp" protocol sites are listed only for compatibility
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1157 with older clients. Newer clients should ignore these and
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1158 only pay attention to "http" sites.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1159 port:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1160 The port at which the server resides on that site.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1161 address:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1162 Any additional addressing information needed to access the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1163 server. For example, for HTTP protocol servers, this would be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1164 the path to the CDDB server CGI script. This field will be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1165 "-" if no additional addressing information is needed.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1166 latitude:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1167 The latitude of the server site. The format is as follows:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1168 CDDD.MM
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1169 Where "C" is the compass direction (N, S), "DDD" is the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1170 degrees, and "MM" is the minutes.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1171 longitude:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1172 The longitude of the server site. Format is as above, except
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1173 the compass direction must be one of (E, W).
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1174 description:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1175 A short description of the geographical location of the site.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1176
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1177 Example:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1178 ca.us.cddb.com cddbp 888 - N037.23 W122.01 Fremont, CA USA
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1179 ca.us.cddb.com http 80 /~cddb/cddb.cgi N037.23 W122.01 Fremont, CA USA
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1180
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1181 Note that a site may appear once for each type of protocol it supports for
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1182 accessing the server.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1183
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1184
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1185 CDDB Protocol Level 4:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1186 ----------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1187
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1188 Protocol level 4 is the same as level 3, with the exception listed below.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1189
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1190 The output of the "cddb query" command may result in multiple exact matches.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1191 A new response code, 210, has been added to indicate that more than one
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1192 exact match has been found.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1193
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1194 Server response:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1195 ----------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1196 <- code exact matches found
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1197 <- categ discid dtitle
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1198 <- categ discid dtitle
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1199 <- (more matches...)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1200 <- .
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1201
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1202 code:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1203 210 Found exact matches, list follows (until terminating marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1204 417 Database access limit exceeded, explanation follows (until marker)
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1205
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1206
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1207 Addendum A: CDDB Protocol Under HTTP:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1208 -------------------------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1209
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1210 Accessing a CDDB server CGI script is done by encapsulating the CDDB protocol
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1211 command in the HTTP protocol. The only limitation is that a single command
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1212 may be executed per connection, since HTTP is not truly interactive. For the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1213 server to be accessed in this way, it must reside on the target host at a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1214 known URL which is accessible by the host HTTP server. The client program
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1215 must connect to the HTTP server on the target host and issue an HTTP command
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1216 with the appropriate CDDB protocol command encapsulated within.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1217
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1218 Commands may be submitted to servers in CGI mode using either the "GET" or
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1219 "POST" HTTP commands. Both methods are supported, and there is no real
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1220 difference between how both are to be used other than the syntactical
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1221 difference between the two methods. The "POST" method may provide the ability
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1222 to issue longer commands, though, depending on the architecture of the HTTP
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1223 server on the remote system.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1224
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1225 The server command must be sent as part of the "Request-URI" in the case
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1226 of the "GET" method, and as the "Entity-Body" in the case of the "POST"
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1227 method. In both cases, the command must be of the following form:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1228
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1229 cmd=server+command&hello=joe+my.host.com+clientname+version&proto=1
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1230
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1231 Where the text following the "cmd=" represents the CDDB Protocol command to
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1232 be executed, the text following the "hello=" represents the arguments to
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1233 the "cddb hello" command that is implied by this operation, and the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1234 text following the "proto=" represents the argument to the "proto" command
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1235 that is implied by this operation.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1236
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1237 The "+" characters in the input represent spaces, and will be translated
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1238 by the server before performing the request. Special characters may be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1239 represented by the sequence "%XX" where "XX" is a two-digit hex number
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1240 corresponding to the ASCII (ISO-8859-1) sequence of that character. The
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1241 "&" characters denote separations between the command, hello and proto
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1242 arguments. Newlines and carriage returns must not appear anywhere in the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1243 string except at the end.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1244
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1245 For example, should user "joe" on system "my.host.com" be running CDclient
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1246 version 2.1, a read request for his currenly playing CD might look like this:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1247
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1248 cmd=cddb+read+rock+12345678&hello=joe+my.host.com+CDclient+2.1&proto=4
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1249
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1250 The server will perform the implied "proto" and "cddb hello" commands,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1251 and then perform the requested "cddb read" command.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1252
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1253 Server response to the command is encapsulated in the HTTP server response,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1254 and appears in the "Entity-Body". Note that the HTTP response "Entity-Header"
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1255 is not guaranteed to contain a "Content-Length" field, so clients should be
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1256 prepared to accept variable length input. The header will always contain a
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1257 Mime "Content-Type" field which describes the body of data as "text/plain".
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1258
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1259 Here is an example HTTP-mode request, including the necessary HTTP protocol:
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1260
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1261 GET /~cddb/cddb.cgi?cmd=help&hello=steve+cddb.com+CDclient+2.1&proto=4 HTTP/1.0
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1262
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1263 For more detailed information on HTTP and Mime, see RFC 1945 and RFC 1521,
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1264 as well as later amendments to those RFCs.
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1265
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1266
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1267 APPENDIX D - OFFICIAL CDDB SOFTWARE DISTRIBUTION SITES
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1268 ------------------------------------------------------
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1269
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1270 All CDDB-related software and other files are distributed via the
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1271 CDDB web page (under "Downloads"):
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1272
5cead4da1db9 Initial import.
darius
parents:
diff changeset
1273 http://www.cddb.com/