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