MfcCDDB v1.31

Welcome to MfcCDDB, a collection of freeware MFC classes to support access to the Compact Disc DataBases on the Internet.

This document assumes you are already familiar with the CDDB protocol, if this is not the case then I would strongly advise you to read the CDDB howto document which you can download from the CDDB web site at http://www.freedb.org. An important point to note is that you will need to get your application verified with CDDB before you can release your product even when you are using MFCCDDB to connect to CDDB. Again check on the CDDB web site for more details.

Features

• Simple and clean C++ interface.
• The interface provided is synchronous which provides an easier programming model than using asynchronous sockets.
• Supports v6 CDDB protocol level. The class internally handles all the details of the UTF8 character set used in v6.
• A configurable timeout for the connection can be set through the class API.
• Supports access through HTTP proxy servers in addition to basic authentication.
• Supports access to the remote CDDB database as well as local (disk) access.
• Supports using "MCI" as well as the low level Win32 API "DeviceIoControl" call to read track details.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

Usage

• As of v1.31, the classes are designed for VC 2005 or later. They will not compile on earlier releases of VC.
• To use the class in your code simply include Mfccddb.cpp/h and SocMFC.cpp.h in your project and #include Mfccddb.h in which ever of your modules needs to make calls to the classes. You also need to copy all the IDS_MFCCDDB_* strings from the samples apps "Mfccddb.rc" rc file to your applications rc file (Use drag and drop in the Visual C++ resource editor to speed this up!).
• SocMFC.cpp/h are not included in the Mfccddb zip download. You will need to download separately these separately from www.naughter.com/w3mfc.html.
• Your code will need to include MFC either statically or dynamically.
• You will need to have a functioning Winsock stack installed and correctly initialised prior to calling any functions in CPJNSMTPConnection. Depending on your application, this will involve calling either WSAStartup or AfxSocketInit at start-up of your application.
• The main functions of the CCDDB class can and will throw MFC style "CDDBException" exceptions. Client code should be prepared to catch these.
• To see the class in action, have a look at the sample code in InitInstance in the module "app.cpp".

History

V1.0 (11 May 1999)

• Initial public release.

V1.1 (20 May 1999)

• Added support for MOTD (Message of the Day).
• Added support for Submitting an album to CDDB.
• Fixed a number of places where calling the TRACE function was causing an access violation
• Fixed a bug in GetErrorMessage which was causing SDK errors to return the string "The operation completed successfully".

V1.11 (14 July 1999)

• Fixed two potential GPF's in the CCDDB::ReadResponse function.
• Minor Update to the documentation.

V1.12 (29 November 1999)

• Fixed a number of bugs when compiled with VC 6.0.

V1.13 (17 January 2000)

• Fixed a number of compiler errors which seem to have crept into MfcCDDB.H v1.12.

V1.14 (23 January 2000)

• The code has now been fully tested with the open source alternative to CDDB namely www.freedb.org. CDDB has become more commercialized of late, since its introduction of a binary SDK with closed validation and new licensing rules. I also believe that CDDB will stop access sometime in 2000 to its databases via non CDDB originated code. Therefore I would suggest that developers using MfcCDDB should provide users with a configuration dialog to allow the CDDB server to be specified, that way you will not have irate customers ringing you when CDDB stops allowing access to it. You can use this open source server instead of the CDDB one in the MfcCDDB code by using "freedb.freedb.org" instead of "cddb.cddb.com" in the call to CCDDB::Sites and by specifying CDDB protocol version 3 in the function SetCDDBProtocolVersion. This is required because as of January 2000 freedb only supports CDDB protocol version 3.
• Fixed a bug in the app.cpp code to the sample Submit call which was causing it to fail.

V1.15 (13 February 2000)

• Now fully supports access when behind a HTTP proxy.
• Also now includes support for proxy authentication.

V1.16 (7 May 2000)

• Fixed a problem in GetUserName and GetHostName with embedded spaces

V1.17 (17 May 2000)

• Now handles CDDB records which have more than one DTITLE line.

V1.18 (30 May 2000)

• Now prevents creation of empty extended track tags (EXTT=).

V1.19 (5 September 2000)

• Modified CCDDB::GetTrackPositions to fail when the CD does not contain any audio tracks

V1.20 (9 August 2001)

• Fixed a bug where the first track title was not being parsed correctly. Thanks to Jared Allen for spotting this.

V1.21 (7 October 2001)

• Major update to bring code into line with freedb standard. As mentioned in previous updates you can no longer use MFCCDDB with the commerical CDDB web site at Gracenote (formerly CDDB). Instead now the code can only be used with the open source alternative of freedb. Updates include:
• Updated copyright information
• Fixed calculation the extra disc length parameter, which must be specified in the query string.
• Fixed bug where discid for submissions was having any leading 0's stripped.
• Updated m_sProductVersion as it was out of date.
• Changed default server in Sites method to "freedb.freedb.org"
• Removed comment line which says "Copyright ... CDDB Inc" from Submit method
• Updated links in documentation to be www.freedb.org
• Fixed a bug in ReadResponse when an error occurs reading from the socket
• Reworked the ReadResponse method to be more inline with my W3MFC socket class
• Updated the sample app to display the last command response when a function fails
• framework now works with version 5 of the CDDB protocol. This gives two extra fields in the CDDB record class namely Year and Genre.
• Complete rewrite of the ParseRecordBody to improve readibilty of the function. This means that the code now correctly supports all text record values which span multiple lines
• Made m_ExtendedData member of CCDDBRecord a CString instead of a string array
• Fixed a bug in CCDDB::ParseKeywordLine
• Fixed bug when separating artist and title from DTITLE lines
• Fixed an infinite recursion bug in ReplaceSubString

V1.22 (8 October 2001)

• Minor update following feedback from freedb.

V1.23 (2 February 2002)

• Fixed a minor parsing bug in CCDDB::GetNextLine. Thanks to Thomas Lang for this fix.

V1.24 (24 June 2002)

• Now fully supports local access to database. The standard and alternate form are both fully supported.
• Optimized #include of 2 files in mfccddb.cpp

V1.25 (3 August 2003)

• Fixed a bug when the MCI device was not being closed if the inserted CD did not contain an Audio CD. Thanks to Christian Inkster for reporting this problem.

V1.26 (3 November 2003)

• Simplified the code in CCDDB::ReadResponse. Thanks to Clarke Brunt for reporting this issue.

V1.27 (20 August 2004)

• General tidy up of the GetUserName and GetHostName functions.

V1.28 (29 June 2005)

• Updated copyright details.
• Updated comments regarding how to include headers into your pre compiled header
• Reviewed all TRACE statements for correctness
• Updates to the GetUserName and GetHostName functions to exclude high ascii characters. Thanks to Stefan Becker for providing the fix for this bug.
• Removed unreferrenced variable warning in CCDDB::FormSubmitLine.
• Fixed a number of level 4 warnings when code is compiled in Visual Studio .NET 2003
• Fixed various warnings when code is compiled with /Wp64 compiler setting in Visual Studio .NET 2003. Please note that to achieve this, the code now requires a recentish Platform SDK to be installed and configured if the code is compiled on Visual C++ 6.

V1.29 (1 January 2007)

• Updated copyright details.
• Addition of a MFCCDDB_EXT_CLASS preprocessor macro to allow the classes to be more easily added to an extension dll
• Updated the code to clean compile in VC 2005
• Updated documentation to use the same style as the web site
• Default timeout is now 60 seconds for release builds and 90 seconds for debug builds
• Reviewed all CString::Format calls for correctness
• Optimized CCDDBSite constructor code
• Optimized CCDDBQueryResult constructor code
• Optimized CCDDBTrackPosition constructor code
• Optimized CCDDBRecord constructor code
• Optimized CCDDB constructor code
• Removed unused CCDDB destructor
• Fixed Unicode issue in CCDDB::GetCDROMDrives
• Updated usage of CString::TrimLeft and CString::TrimRight in the code
• Replaced usage of CCDDB::ReplaceSubString with CString::Replace
• Hostname can now be customized via a SetHostName method
• m_sLastCommandResponse is now not reset when a response is successfully parsed
• UserName can now be customized via a SetUserName method
• CCDDBSite::Parse now does not fail if protocol is not "http"
• Reworked the classes to be exception based along the lines of the author's CPJNSMTPConnection class. This should improve the robustness of client application code. Please note that because of this redesign, you should re-examine all client code to make sure it catches the new exceptions thrown from the classes as appropriate
• Fixed a bug in CCDDB::SplitSemiColonLine where 1 character length values would not be parsed correctly
• Added a constructor to the class CCDDBStatus
• Fixed a bug in CCDDB::ParseCommentLine where 1 character length values would not be parsed correctly
• Fixed a bug in CCDDB::ReadResponse where it had problems parsing the body of the response for query and submit requests if the body arrives in a second packet from the network
• CCDDB::ParseRecordBodyFromFile now allows other processes to read the file which it is currently attempting to parse
• Optimized code in CCDDB::Read(const CString& sDirectory... which operates on the passed in dwDiscID parameter
• Optimized code in CCDDB::ParseRecordBodyFromFile to handle parsing the non-standard (Windows) format of CDDB record format

V1.30 (12 January 2008)

• Updated copyright details.
• Updated sample app code to remove VC 6 style classwizard comments
• Updated the sample app to clean compile on VC 2008
• CCDDBException::GetErrorMessage now uses the FORMAT_MESSAGE_IGNORE_INSERTS flag. For more information please see Raymond Chen's blog at http://blogs.msdn.com/oldnewthing/archive/2007/11/28/6564257.aspx. Thanks to Alexey Kuznetsov for reporting this issue.
• CCDDBException::GetErrorMessage now uses Checked::tcsncpy_s if compiled using VC 2005 or later.

V1.31 (31 August 2008)

• Code now compiles cleanly using Code Analysis (/analyze)
• Updated code to compile correctly using _ATL_CSTRING_EXPLICIT_CONSTRUCTORS define
• The code now only supports VC 2005 or later.
• Added support for parsing CCDDBSite::m_sProtocol
• Code now uses ATL's support for base64 encoding
• The code now uses the author's CWSocket to encapsulate socket functionality
• Fixed a bug in the calculation of the total track length in CCDDB::ComputeDiscID. Thanks to Tom van Dijck for reporting this bug.
• General tidy up of all the parsing code in the classes
• The classes now supports v6 Protocol level (if the code is compiled for Unicode)
• GetTrackPositions has been renamed to GetTrackPositionsUsingMCI.
• Addition of a GetTrackPositionsUsingDeviceIoControl using the API DeviceIoControl and the IOCTL code of IOCTL_CDROM_READ_TOC to get the track positions. This method works on all versions of Windows based on the NT Kernel (i.e. NT, 2000, XP, 2003, Vista and 2008). It should also work for multi-session CD's i.e. CD's which have data sessions as well as an audio session.
• ComputeDiscID has been renamed to ComputeDiscIDUsingMCI.
• Addition of a ComputeDiscIDUsingDeviceIoControl method.

API Reference

The API consists of the following classes and their methods and variables

CCDDBSite

CCDDBSite::CCDDBSite
CCDDBSite::operator=
CCDDBSite::m_sSite
CCDDBSite::m_nPort
CCDDBSite::m_sAddress
CCDDBSite::m_bNorthing
CCDDBSite::m_nLatitudeMinutes
CCDDBSite::m_bEasting
CCDDBSite::m_nLongitudeMinutes
CCDDBSite::m_sDescription

CCDDBQueryResult

CCDDBQueryResult::CCDDBQueryResult
CCDDBQueryResult::operator=
CCDDBQueryResult::m_sCategory
CCDDBQueryResult::m_dwDiscID
CCDDBQueryResult::m_sArtist
CCDDBQueryResult::m_sTitle

CCDDBRecord

CCDDBRecord::m_TrackOffsets
CCDDBRecord::m_nDiskLength
CCDDBRecord::m_nDatabaseRevision
CCDDBRecord::m_sClientName
CCDDBRecord::m_sClientVersion
CCDDBRecord::m_sClientComments
CCDDBRecord::m_dwDiscID
CCDDBRecord::m_sArtist
CCDDBRecord::m_sTitle
CCDDBRecord::m_TrackTitles
CCDDBRecord::m_ExtendedData
CCDDBRecord::m_ExtendedTrackData
CCDDBRecord::m_PlayOrder

CCDDBStatus

CCDDBStatus::m_nCurrentProtocol
CCDDBStatus::m_nMaxProtocol
CCDDBStatus::m_bGetsAllowed
CCDDBStatus::m_bUpdatesAllowed
CCDDBStatus::m_bPostingAllowed
CCDDBStatus::m_bQuotes
CCDDBStatus::m_nCurrentUsers
CCDDBStatus::m_nMaxUsers
CCDDBStatus::m_bStripExtended
CCDDBStatus::m_nDatabaseEntries
CCDDBStatus::m_Categories
CCDDBStatus::m_CategoryEntries
CCDDBStatus::m_PendingSites
CCDDBStatus::m_PendingEntries

CCDDBTrackPosition

CCDDBTrackPosition::operator=
CCDDBTrackPosition::m_nMinute
CCDDBTrackPosition::m_nSecond
CCDDBTrackPosition::m_nFrame

CCDDB::CCDDB
CCDDB::GetCDROMDrives
CCDDB::ComputeDiscID...
CCDDB::GetTrackPositions...
CCDDB::Sites
CCDDB::Categories
CDDB::SetCDDBProtocolVersion
CDDB::GetCDDBProtocolVersion
CCDDB::Status
CCDDB::Query
CCDDB::Read
CCDDB::Submit
CCDDB::MessageOfTheDay
CCDDB::SetTimeout
CCDDB::GetTimeout
CCDDB::GetLastCommandResponse
CCDDB::GetProductName
CCDDB::SetProductName
CCDDB::GetProductVersion
CCDDB::SetProductVersion
CCDDB::GetHelloCommand
CCDDB::SetProxyDetails
CCDDB::SetProxyHost
CCDDB::SetProxyPort
CCDDB::SetProxyUser
CCDDB::SetProxyPassword
CCDDB::GetProxyHost
CCDDB::GetProxyPort
CCDDB::GetProxyUser
CCDDB::GetProxyPassword

CCDDBSite::CCDDBSite

CCDDBSite(BOOL bRetrieve = TRUE);

Parameters

bRetrieve TRUE if the members of CDDBSite should be setup for retrieving data otherwise FALSE for submitting albums.

Remarks

Standard constructor for the class. This class represents the information for a single site as returned from the CDDB::Sites function. This class is also used when calling any of the other CCDDB functions which access a CDDB server.

CCDDBSite::operator=

CCDDBSite& operator=(const CCDDBSite& site);

Parameters

site This CCDDBSite instance to copy into this instance.

Remarks

Standard operator= for the CCDDBSite class.

CCDDBSite::m_sSite

Remarks

m_sSite is of type CString and contains the IP address or domain name of the CDDB HTTP server.

CCDDBSite::m_nPort

Remarks

m_nSite is of type int and contains the IP port number of the CDDB HTTP server. Normally this will be 80 which is the standard HTTP port number.

CCDDBSite::m_sAddress

Remarks

m_sAddress is of type CString and contains the URL which is requested when making the HTTP request. Normally this is either "~cddb/cddb.cgi" or "~cddb/submit.cgi".

CCDDBSite::m_bNorthing

Remarks

m_bNorthing is of type BOOL and is TRUE if the CDDB site is reported as being in the northern hemisphere or FALSE if in the southern hemisphere.

CCDDBSite::m_nLatitudeMinutes

Remarks

m_nLatitudeMinutes is of type int and contains the latitude of the CDDB site in minutes of degrees north or south of the equator.

CCDDBSite::m_bEasting

Remarks

m_bEasting is of type BOOL and is TRUE if the CDDB site is reported as being west of the Greenwich prime meridian or FALSE if west of it.

CCDDBSite::m_nLongitudeMinutes

Remarks

m_nLongitudeMinutes is of type int and contains the longitude of the CDDB site in minutes of degrees east or west of the prime meridian.

CCDDBSite::m_sDescription

Remarks

m_sDescription is of type CString and contains a simple description of the CDDB site e.g. "Random US Site".

CCDDBQueryResult::CCDDBQueryResult

CCDDBQueryResult();

Remarks

Standard constructor for the class. This class represents the information for a single site as returned from the CDDB::Query function.

CCDDBQueryResult::operator=

CCDDBQueryResult& operator=(const CCDDBQueryResult& result);

Parameters

result This CCDDBQueryResult instance to copy into this instance.

Remarks

Standard operator= for the CCDDBQueryResult class.

CCDDBQueryResult::m_sCategory

Remarks

m_sCategory is of type CString and contains the category of the album.

CCDDBQueryResult::m_dwDiscID

Remarks

m_dwDiscID is of type DWORD and contains the CDDB DISC-ID of the album.

CCDDBQueryResult::m_sArtist

Remarks

m_sArtist is of type CString and contains the Artist of the album.

CCDDBQueryResult::m_sTitle

Remarks

m_sTitle is of type CString and contains the title of the album.

CCDDBRecord

This class represents the information for a single album as returned from the CDDB::Read function.

CCDDBRecord::m_TrackOffsets

Remarks

m_TrackOffsets is of type CArray<int, int&> and contains the offset of each track (including the leadout track) in frames.

CCDDBRecord::m_nDiskLength

Remarks

m_nDiskLength is of type int and contains the number of seconds of the CD's play length.

CCDDBRecord::m_nDatabaseRevision

Remarks

m_nDatabaseRevision is of type int and contains the revision number of this album in the database. This is used internally by CDDB for database management. When you are allowing the user to modify a database entry, you should increment this number prior to submitting the modified entry to CDDB.

CCDDBRecord::m_sClientName

Remarks

m_sClientName is of type CString and contains the name of the client application which submitted this record to CDDB.

CCDDBRecord::m_sClientVersion

Remarks

m_sClientVersion is of type CString and contains the version number of the client application which submitted this record to CDDB. Please see the CDDB howto document for the format which should be used.

CCDDBRecord::m_sClientComments

Remarks

m_sClientComments is of type CString and contains optional comments which you want to include along with the ClientName and Client Version.

CCDDBRecord::m_dwDiscID

Remarks

m_dwDiscID is of type DWORD and contains the CDDB DISC-ID of the album.

CCDDBRecord::m_sArtist

Remarks

m_sArtist is of type CString and contains the Artist of the album.

CCDDBRecord::m_sTitle

Remarks

m_sTitle is of type CString and contains the title of the album.

CCDDBRecord::m_TrackTitles

Remarks

m_TrackTitles is of type CStringArray and contains the title of each track of the album.

CCDDBRecord::m_ExtendedData

Remarks

m_ExtendedData is of type CStringArray and contains the names of any extended data associated with this album. For example it could contain "Producer:Jimmy Page", "Executive Producer: Peter Grant" and "Year: 1976".

CCDDBRecord::m_ExtendedTrackData

Remarks

m_ExtendedTrackData is of type CStringArray and contains the extended data for each track on the album. For example this could contain the vocalists for each track. The array will come back with as many elements in the array as tracks on the album. If no data is present for any track then the string for that title will be a empty string.

CCDDBRecord::m_PlayOrder

Remarks

m_PlayOrder is of type CArray<int, int> and contains the customized play order for this album. Generally this is stripped when submitted to a non-local CDDB database. You might want to allow your application to store this locally as a user preference. You should also ensure that this information is stripped prior to submitting this record to a CDDB server.

CCDDBStatus

Remarks

This class represents the information as returned from the CDDB::Status function.

CCDDBStatus::m_nCurrentProtocol

Remarks

m_nCurrentProtocol is of type int and contains the server's current operating protocol level.

CCDDBStatus::m_nMaxProtocol

Remarks

m_nMaxProtocol is of type int and contains the server's maximum supported operating protocol level.

CCDDBStatus::m_bGetsAllowed

Remarks

m_bGetsAllowed is of type BOOL and is TRUE if the client is allowed to get log information otherwise FALSE.

CCDDBStatus::m_bUpdatesAllowed

Remarks

m_bUpdatesAllowed is of type BOOL and is TRUE if the client is allowed to initiate a database update otherwise FALSE.

CCDDBStatus::m_bPostingAllowed

Remarks

m_bPostingAllowed is of type BOOL and is TRUE if the client is allowed to post new entries to the database otherwise FALSE.

CCDDBStatus::m_bQuotes

Remarks

m_bQuotes is of type BOOL and is TRUE if quoted arguments are enabled otherwise FALSE.

CCDDBStatus::m_nCurrentUsers

Remarks

m_nCurrentUsers is of type int and is the number of users currently connected to the server.

CCDDBStatus::m_nMaxUsers

Remarks

m_nMaxUsers is of type int and is the maximum number of users that can connect to the server concurrently.

CCDDBStatus::m_bStripExtended

Remarks

m_bStripExtended is of type BOOL and is TRUE if extended data is stripped by the server before being presented to the user otherwise FALSE.

CCDDBStatus::m_nDatabaseEntries

Remarks

m_nDatabaseEntries is of type int and is the total number of entries in the database.

CCDDBStatus::m_Categories

Remarks

m_Categories is of type CStringArray and is the list of all the categories in the database.

CCDDBStatus::m_CategoryEntries

Remarks

m_CategoryEntries is of type CArray<int, int> and contains the number of entries for each category in the database. The elements at each offset correspond to the m_Categories array.

CCDDBStatus::m_PendingSites

Remarks

m_PendingSites is of type CStringArray and is the list of sites which are fed database entries from the current site.

CCDDBStatus::m_PendingEntries

Remarks

m_PendingEntries is of type CArray<int, int> and contains the number of pending entries to be sent to each site. The elements at each offset correspond to the m_PendingSites array.

CCDDBTrackPosition

Remarks

This class represents the absolute track position of a CD in MSF (Minute, Second, Frame) format. This class is used in the CCDDB::ComputeDiscID..., CCDDB::GetTrackPositions... & CCDDB::Query functions.

CCDDBTrackPosition::operator=

CCDDBTrackPosition& operator=(const CCDDBTrackPosition& position);

Parameters

position This CCDDBTrackPosition instance to copy into this instance.

Remarks

Standard operator= for the CCDDBTrackPosition class.

CCDDBTrackPosition::m_nMinute

Remarks

m_nMinute is of type int and contains the minutes component of a track's position.

CCDDBTrackPosition::m_nSecond

Remarks

m_nSecond is of type int and contains the seconds component of a track's position.

CCDDBTrackPosition::m_nFrame

Remarks

m_nFrame is of type int and contains the frame component of a track's position. A frame is defined as 1/75 of a second meaning that this value ranges from 0 - 74.

CCDDB::CCDDB

CCDDB();

Remarks

Standard constructor for the class. This class is the main CDDB support class and contains all the CDDB related functions. It also includes a number of simple wrapper functions for accessing CD-Audio discs through the Windows MCI programming interface.

CCDDB::GetCDROMDrives

void GetCDROMDrives(CStringArray& drives);

Parameters

drives Upon return this will contain the drive letters which correspond to CDROM drives.

Remarks

Upon return the "drives" array will contain all the drives on the current machine which are CDROM drives. Any of the values in the array can then be used in a call to CCDDB::ComputeDiscID.... The format returned is in the format of "x:" where x is the drive letter of the CDROM drive.

CCDDB::ComputeDiscID...

DWORD ComputeDiscIDUsingMCI(LPCTSTR pszDrive = NULL);

DWORD ComputeDiscIDUsingDeviceIoControl(LPCTSTR pszDrive);

DWORD ComputeDiscID(const CArray<CCDDBTrackPosition, CCDDBTrackPosition&>& tracks);

Return Value

The computed DISC-ID of the specified track positions.

Parameters

pszDrive The drive letter of the CDROM drive to compute the DISC-ID of the inserted CD.

tracks An array specifying an albums contents which the DISC-ID is to be computed for.

Remarks

Computes the DISC-ID of the inserted CD in the specified CDROM drive. If you specify NULL for the drive in the call to ComputeDiscIDUsingMCI, then the default CDROM drive will be used. The two overloaded "Using" versions internally use MCI and DeviceIoControl respectively to compute the track positions. Please note that the tracks parameter includes the lead-out track position also. The tracks parameter can be computed using the CCDDB::GetTrackPostions function

CCDDB::GetTrackPositions...

void GetTrackPositionsUsingMCI(CArray<CCDDBTrackPosition, CCDDBTrackPosition&>& tracks, LPCTSTR pszDrive = NULL);

void GetTrackPositionsUsingDeviceIoControl(CArray<CCDDBTrackPosition, CCDDBTrackPosition&>& tracks, LPCTSTR pszDrive);

Parameters

tracks Upon successful return this will contain the track positions of the album in the specified CDROM drive.

pszDrive The drive letter of the CDROM drive to get the track positions of.

Remarks

Upon return the "tracks" array will contain the track positions for the specified album in the "pszDrive" CDROM drive. If you specify NULL for the drive in the "UsingMCI" version, then the default MCI CDROM drive will be used. Please note that the tracks array will include the leadout track position as the last element in the array as well as the normal audio tracks. This means that the size of the array upon return will be 1 greater than the number of audio tracks on the album. This is required for the calculation of the DISC-ID as returned from the CCDDB::ComputeDiscId... functions.

CCDDB::Sites

void Sites(CArray<CCDDBSite, CCDDBSite&>& sites, const CString& sServer = _T("cddb.cddb.com"), const CString& sAddress = _T("/~cddb/cddb.cgi"), int nPort = 80);

void Sites(CArray<CCDDBSite, CCDDBSite&>& sites, const CCDDBSite& server);

Parameters

sites Upon successful return this will contain the list of CDDB servers as returned from the Sites command.

sServer The IP address or domain name of the CDDB HTTP server to use.

sAddress The HTTP request to make.

nPort The TCP/IP port number on which to make the connection.

server The server to use as specified through its parameters m_sSite, m_nPort and m_sAddress parameters.

Remarks

Issues the CDDB "Sites" command. For more information about this command, please consult the CDDB howto document. The first form of the function uses the default CDDB server at "cddb.cddb.com" to retrieve the site list, whereas the second form allows you to specify the server details through the "server" parameter.

CCDDB::SetCDDBProtocolVersion

void SetCDDBProtocolVersion(int nProtocolVersion);

Parameters

nProtocolVersion The CDDB protocol version to use.

Remarks

Sets the CDDB protocol version to use.

CCDDB::GetCDDBProtocolVersion

int GetCDDBProtocolVersion() const;

Return Value

The current CDDB protocol version by using by the code.

Remarks

This is the corollary function to SetCDDBProtocolVersion.

CCDDB::Categories

void Categories(const CCDDBSite& server, CStringArray& categories);

Parameters

server The server to use as specified through its parameters m_sSite, m_nPort and m_sAddress parameters.

categories Upon successful return this will contain the list of categories which this server's database contains.

Remarks

Issues the CDDB "lscat" command. This function returns the type of categories which this servers database contains. For more information about this command, please consult the CDDB howto document.

CCDDB::Status

void Status(const CCDDBSite& server, CCDDBStatus& status);

Parameters

server The server to use as specified through its parameters m_sSite, m_nPort and m_sAddress parameters.

status Upon successful return this will contain the CDDB servers information.

Remarks

Issues the CDDB "stat" command. This function returns information relating to a CDDB server such as number of albums in the database etc in the status parameter. For more information about this command, please consult the CDDB howto document. 

CCDDB::Query

void Query(const CCDDBSite& server, DWORD dwDiscID, const CArray<CCDDBTrackPosition, CCDDBTrackPosition&>& tracks, CArray<CCDDBQueryResult, CCDDBQueryResult&>& results);

Parameters

server The server to use as specified through its parameters m_sSite, m_nPort and m_sAddress parameters.

dwDiscID The DISC-ID of the inserted album.

tracks An array specifying an albums contents which the DISC-ID is to be computed for.

results Upon successful return this will contain an array of query result instances which represent the matching albums

Remarks

Issues the CDDB "query" command. This function queries the CDDB servers database about whether or not the specified album is present. If the album is not found, then the return value will be TRUE and there will be no entries in the "results" array. An exact match will have just one element in the array while an inexact match will result in multiple entries in the array. For more information about this command, please consult the CDDB howto document. 

CCDDB::Read

void Read(const CCDDBSite& server, DWORD dwDiscID, const CString& sCategory, CCDDBRecord& record);

Parameters

server The server to use as specified through its parameters m_sSite, m_nPort and m_sAddress parameters.

dwDiscID The DISC-ID of the album.

sCategory The CDDB category which the album belongs to.

record Upon successful return this will contain the album details in a CCDDBRecord instance.

Remarks

Issues the CDDB "read" command. This function queries the CDDB servers database about a specified album's details. Normally this would be used after a successful call to Query. For more information about this command, please consult the CDDB howto document. 

CCDDB::Submit

void Submit(const CCDDBSite& server, const CString& sCategory, const CString& sEmailAddress, CCDDBRecord& record, const CString& sRejectionNotice, BOOL bReallySubmit = TRUE);

Parameters

server The server to use as specified through its parameters m_sSite and m_nPort parameters.

sCategory The CDDB category which the album belongs to.

sEmailAddress The email address where any submission failure notices should be mailed to.

record Details of the album to be added to the CDDB database.

sRejectionNotice Arbitrary message to be included at the top of any rejection notice that may be sent to the submitting user

bReallySubmit Indicates whether the submission is a test submission or a real submission to the database.

Remarks

Submits an album for inclusion in the CDDB database. Any after the fact errors with the submission are reported through email to the email address "sEmailAddress". The CDDB protocol also includes a test mode specified by setting bReallySubmit to FALSE whereby a dummy run of the submission is made without actually adding the entry to the database. For more information about submitting albums, please consult the CDDB howto document. 

CCDDB::MessageOfTheDay

void MessageOfTheDay(CString& sMessage, const CString& sServer = _T("cddb.cddb.com"), const CString& sAddress = _T("/~cddb/cddb.cgi"), int nPort = 80);

void MessageOfTheDay(const CCDDBSite& server, CString& sMessage);

Parameters

sMessage Upon successful return, this will contain the "Message of the Day".

sServer The IP address or domain name of the CDDB HTTP server to use.

sAddress The HTTP request to make.

nPort The TCP/IP port number on which to make the connection.

server The server to use as specified through its parameters m_sSite, m_nPort and m_sAddress parameters.

Remarks

Issues the CDDB "motd" command. This function queries the CDDB servers database for a message of the day. In Windows terms this is similar to the Tip of the Day which some applications implement. For more information about this command, please consult the CDDB howto document. 

CCDDB::GetTimeout

DWORD GetTimeout() const;

Return Value

The timeout in milliseconds which the code will wait for responses from the CDDB server.

Remarks

Since CCDDB provides a synchronous API, a timeout mechanism is provided. By default the value is 2 seconds in release mode and 60 seconds in debug mode. The value is larger in debug mode so that the code does not time out when you are debugging it.

CCDDB::SetTimeout

void SetTimeout(DWORD dwTimeout) const;

Parameters

dwTimeout The new timeout value in milliseconds.

Remarks

Sets the timeout to use for connections to the CDDB server.

CCDDB::GetLastCommandResponse

CString GetLastCommandResponse() const;

Return Value

The last command response from the server as a CString.

Remarks

The CCDDB class can return additional text information along with most errors. This extended error information can be retrieved by using the GetLastCommandResponse function after an unsuccessful function call. GetLastCommandResponse can be called multiple times until another CCDDB function is called which issues a CDDB request.

CCDDB::GetProductName

CString GetProductName() const;

Return Value

The Product Name which the CCDDB class will use internally.

Remarks

When connections are being made to the CDDB server, part of the protocol requires the client program to identify itself. You will need to pick a name which has not been used by other CDDB enabled products. This function allows retrieval of the value as set by SetProductName. For more information about, please consult the CDDB howto document. By default the product name is set to the "MfcCDDB".

CCDDB::SetProductName

void GetProductName(const CString& sProductName);

Parameters

sProductName The Product Name which the CCDDB class will use internally.

CCDDB::GetProductVersion

CString GetProductVersion() const;

Return Value

The Product Version which the CCDDB class will use internally.

Remarks

As well as the product name being required when connecting to a CDDB server, a version number is also required. By default the version number is set to the version number of the MfcCDDB code. As mentioned in the howto document, this field has a very specific format which should be observed:

[leading text]version_number[release type][level]

Where:

    Leading text: is any string which does not include numbers.
    Version number and level: is any (possibly) decimal-separated list of
    positive numbers.
    Release type: is a string of the form:
    alpha, a, beta, b, patchlevel, patch, pl
    Level: is a positive number.

For example:

    release:2.35.1alpha7
    v4.0PL0
    2.4

CCDDB::SetProductVersion

void GetProductName(const CString& sProductVersion);

Parameters

sProductVersion The Product Version which the CCDDB class will use internally.

CCDDB::GetHelloCommand

virtual CString GetHelloCommand();

Return Value

The string to use for the "hello" command which the CCDDB class will use internally.

Remarks

As part of all the CDDB HTTP requests, the CDDB Hello command is encoded into the request as well. The command takes the following format:

hello=username+domainname+ProductName+ProductVersion

The default implementation of this function in CCDDB uses the username as returned from the SDK function "GetUserName", the local machines domain name as returned from "gethostname" and the strings as stored using the functions: SetProductName and GetProductVersion. You can derive your own class from CCDDB and override this function if you so desire. For more information about these details, please consult the CDDB howto document.

CCDDB::SetProxyDetails

void SetProxyDetails(const CString& sHost, int nPort, const CString& sUser, const CString& sPassword);

Parameters

sHost The host name or IP address of the proxy server to use.

nPort The port number on which to connect to the proxy.

sUser The user name to use for proxy authentication.

sPassword The password to use for proxy authentication.

Remarks

When you are situated behind a HTTP proxy server, you can use this to tell the CCDDB class, the proxy settings to use.

CCDDB::SetProxyHost

void SetProxyHost(const CString& sHost);

Parameters

sHost The host name or IP address of the proxy server to use.

Remarks

When you are situated behind a HTTP proxy server, you can use this to tell the CCDDB class, the proxy settings to use. Setting the host to an empty string will make the CCDDB class use a direct connection to the Internet.

CCDDB::SetProxyPort

void SetProxyPort(int nPort);

Parameters

nPort The port number on which to connect to the proxy.

CCDDB::SetProxyUser

void SetProxyUser(const CString& sUser);

Parameters

sUser The user name to use for proxy authentication.

Remarks

Setting the user to an empty string will make the CCDDB class use a proxy which does not require authentication.

CCDDB::SetProxyPassword

void SetProxyUser(const CString& sPassword);

Parameters

sPassword The password to use for proxy authentication.

CCDDB::GetProxyHost

CString GetProxyHost() const;

Return Value

The host name or IP address of the proxy which the CCDDB code is using. The string will be empty if the code makes a direct connection to the Internet.

CCDDB::GetProxyPort

int GetProxyPort() const;

Return Value

The port number of the proxy which the CCDDB code is using.

CCDDB::GetProxyUser

CString GetProxyUser() const;

Return Value

The name used for proxy authentication.

CCDDB::GetProxyPassword

CString GetProxyPassword() const;

Return Value

The password used for proxy authentication.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
31 August 2008