TUTORIAL for cddb bundle.
-------------------------

1. Set up a cddb instance.

   Load the bundle, instanize it using general methods: alloc and init.
   By default, it will use cddbp://freedb.freedb.org:8880.
   If you are in the firewall, you might want to change it.
   
2. Set up the cddb server.
  
   cddb bundle doesn't read/write any user defaults.
   Use these two methods to access the cddb server.
   - (void) setDefaultSite: (NSString *) site;
   - (NSString *) defaultSite;
   Be sure the use standard URL in NSString.
   This NSString will be read into NSURL.
   Applications are responsible for store their own server information.

3. Connect to cddb server.

   Always use 

   if ([cddbInstance connect]) 
     {
       ...
       [cddbInstance disconnect];
     }

   even you are using http protocol to access cddb server.

4. Get the mirror server.

   After you connect to the cddb server, you can get a list of mirrors servers.

   NSArray *sites = [cddbInstance sites];

   The return value is an NSArray of NSDictionary.
   The keys of NSDictionary are "site", "port", "latitude",
   "longitude", "description", "protocol" and "address".
   "protocol" and "address" are supported only for level 2 and up.
   (The default level is 5).

   In order to build a standard NSString for NSURL from this information,
   you can use this format:
   If protocol is "http":
   @"%@://%@:%@%@", protocol, site, port, address
   If protocol is "cddbp":
   @"%@://%@:%@", protocol, site, port

5. Calculate discid.

   You can get the discid directly from CD information.
   First, you have to fill an NSArray of NSDictionary.
   Each CD track has length and offset in frames.
   Fill the NSDictionary with @"length" and @"offset" as keys.
   The objects should have intValue method (NSString or NSNumber).
   Fill the NSArray with these NSDictionary for each track.
   The number of objects in this NSArray is the number of tracks.

   Use [cddbInstance discidWithCDTracks: tracks
                                locally: YES];
   to get the discid in NSString.
   locally: YES will calculate discid locally in cddb bundle,
   Therefore, you don't need to connect to cddb server.
   locally: NO will ask the cddb server to calculate discid for you,
   which is only useful for debug of discid algorithm.

6. Get the category of CD.
  
   You need the category information in order to get the cddb entry.
   Use the same CD information above and this method:

   [cddbInstance queryWithCDTracks: tracks];

   Sometimes you will have multiple matches.
   Therefore, the return value is an NSArray of NSDictionary.
   Each object of NSArray is a match.
   The keys of each match are "category", "discid", "description".
   The objects are NSString.
   Use the "category" and "discid" to get the cddb entry later.

7. Get the entry of CD.

   Once you know the category and discid of the CD,
   you can use 

   [cddbInstance readWithCategory: category
                           discid: discid
                      postProcess: YES];
 
   to get the CD information.

   If postProcess: NO, the return value is a NSDictionary corresponding
   to the cddb format.
   The class of objects and keys are:
   NSString, "discid"
   NSString, "album"
   NSString, "year" (level 4 or up)
   NSString, "genre" (level 4 or up)
   NSArray, "titles" (title of each track)
   NSString, "extdata" (extra data about this album)
   NSArray, "exttitles" (extratitle of each track)

   Becuase the cddb format doesn't have an artist field,
   So the artist is either in album or titles fields.
   Use postProcess: YES to process the cddb format
   and give out the artist field and clean album/titles field.
   The class of objects and keys are:
   NSString, "discid"
   NSString, "album"
   NSString, "year"
   NSString, "genre"
   NSArray, "artists" <= This is new
   NSArray, "titles"
   NSString, 'extdata"
   NSArray, "exttitles"

8. How do I know it fails ?

   If the cddb bundle fails (no connection, no match, etc.),
   for return value is NSString or NSDictionary, it will return nil;
   for return value is NSArray, it will retun an emtpy NSArray (not nil).
