This document describes how you can use the cddb.library in your own
programs.

add cddb.library support:
-------------------------

To  use  the  cddb.library  in your program, you only need to call the
function CDDB_Get() as follows:


with AmigaOberon:
err := cddb.GetCDDB (ADR(cdi),
        cddb.aDiscID, ADR(discID),
        cddb.aCateg,  ADR(categ),
        cddb.aArtist, ADR(artist),
        cddb.aDTitle, ADR(dTitle),
        cddb.aTTitles,ADR(tTitles),
        Utility.done);

or with C:
err = CDDB_GetTags(&cdi,
	CDDB_aDiscID, &discID,
	CDDB_aCateg,  &categ,
	CDDB_aArtist, &artist,
	CDDB_aDTitle, &dTitle,
	CDDB_aTTitles,&tTitles,
	TAG_DONE);

[I  will  use  AmigaOberon  notation  at first place and C notation in
brackets in the following text!]

the  variable  'cdi'  must  be  'filled'  before  manually:

'cdi.msf' (C: cdi_MSF) with the start -minutes, -seconds and -frames
          of each track.
          Index 0 contains the values (msf) for the first track.

'cdi.tracks' (C: cdi.cdi_Tracks) holds the number of the tracks

'cdi.time'  (C: cdi.cdi_Time) holdes the length of the CD in seconds

'cdi.discID' (C: cdi.cdi_DiscID) holds the discID of the CD

To calculate the DiscID you can use the function CDDB.CalcDiscID() or
with C CDDB_CalcDiscID().
There  you  have  to  submit the CDInfo structure.  Only the number of
tracks  (cdi.tracks,  C:   cdi.cdi_Tracks)  and  the  msf structure of
CDInfo is needed.

If   'err'  contains  0  after  the  call  (CDDB.errNoError  =  0,  C:
CDDB_NOERROR),  'cdi.discID'  (C:   cdi.cdi_DiscID)  holds the scanned
DiscID  (else  0),  'categ'  the  category,  'artist'  the name of the
artist/singer/group,  'dTitle' the CD-Title and 'tTitles' contains the
titles  of  each  track in an array.  This is an array of ptrs, so you
have to allocate memory for each ptr before!

'categ'  is  set to "offline", if the data (CD title etc.) are already
on your disc and there wasn't specified a category.


How does GetCDDB(), C: CDDB_GetTags() works:
---------------------------------------------

First  it  will  be  checked  whether the data for this CD are already
available  on  your disc (CDDB:Read_DiscIDs/).  If not, it will try to
connect  to  freedb.org and get the data from there.  If yes, then the
data  will  be  loaded  from  disc.   There is a tag 'aForceOnline' to
connect  to  freedb.org  even  if  the data are already stored on your
disc.

How do you use the cddb.library, step by step:
----------------------------------------------

- read the TOC of the CD
- initialize the CDInfo structure as follows:

  'cdi.msf' (C: cdi_MSF) with the start -minutes, -seconds and -frames
          of each track.
          Index 0 contains the values (msf) for the first track.

  'cdi.tracks' (C: cdi.cdi_Tracks) holds the number of the tracks

  'cdi.time'  (C: cdi.cdi_Time) holdes the length of the CD in seconds

  'cdi.discID' (C: cdi.cdi_DiscID) holds the discID of the CD
  You can use CDDB.CalcDiscID() for this, if it fails it will be set
  to 0.

- now you have to initialize the track titles 'tTitles'
  its an array of CDDB.maxTracks (C: CDDB_MAXTRACKS) of STRPTR, which
  should be at least CDDB.maxLenTTitle (C: CDDB_MAXLENTTITLE) bytes.
  And for this STRPTR you have to allocate memory.

- now you can call CDDB.GetCDDB() (C: CDDB_GetTags()) like this:

  with AmigaOberon:
  err := cddb.GetCDDB (ADR(cdi),
        CDDB_aDiscID, ADR(discID),
        CDDB_aCateg,  ADR(categ),
        CDDB_aArtist, ADR(artist),
        CDDB_aDTitle, ADR(dTitle),
        CDDB_aTTitles,ADR(tTitles),
        utility.done);

  or with C:
  err = CDDB_GetTags(&cdi,
          CDDB_aDiscID, &discID,
          CDDB_aCateg,  &categ,
          CDDB_aArtist, &artist,
          CDDB_aDTitle, &dTitle,
          CDDB_aTTitles,&tTitles,
	  TAG_DONE);

  'cdi'     the pre-initialized CDInfo structure, see above

  'discID'  a LONGINT (32bit) variable,
            it holds the scanned discID (received from freedb.org)

  'artist'  a STRING (min size is CDDB.maxLenArtist chars)
            this holds the name of the artist/group

  'categ'   a STRING (min size is CDDB.maxLenCateg chars)
            it holds the category of the cd

  'dTitle'  a STRING (min size is CDDB.maxLenDTitle chars)
            the name of the cd

  'tTitles' an array of (earlier allocated) STRPTRs
            (with the length of CDDB.maxLenTTitle chars)
            which holds each tracktitle


  You can use the StatusHook (CDDB.aStatusHook), to display the
  current status.

  For example:

  AmigaOberon:
  PROCEDURE CDDBStatusFunc (hook: u.HookPtr; null: e.APTR; msg: cddb.pStatusHookPtr): e.APTR;  (* a0/a2/a1 *)
  BEGIN
       d.PrintF ("**CDDB: %s\n", msg.str); RETURN 0
  END CDDBStatusFunc;


Requirements for storing the data on your disc:
-----------------------------------------------

There has to exists a the following directory tree:

The assign "CDDB:" has to have these subdirectories

  New_DiscIDs    -> not yet known discs will be stored here

  Read_DiscIDs   -> the successfully received data from the Internet
                    are placed in this directory

  CDText_DiscIDs -> yet not used by cddb.library, only by CDDBGUI


Thus simply type these lines into a shell:
  MakeDir Work:CDDB
  MakeDir Work:CDDB/New_DiscIDs
  MakeDir Work:CDDB/Read_DiscIDs
  Assign CDDB: Work:CDDB/