MfcCDDB v1.47

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

CDDB is an information database containing artist, disc title, track titles, and other information for digital audio compact discs. Over time, this archive has grown to contain a substantial collection of CD information and is continuing to grow at a rapid rate. This database can be accessed by applications via the CDDB server hosts that have been set up on the Internet around the world. The CDDB data format and the CDDB servers are designed to be open, and are used by many client applications requiring CD information. CDDB has become the de facto standard for Internet access of compact disc information. For more information please see https://gnudb.org.

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 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.39, the classes are designed for VC 2017 or later. They will not compile on earlier releases of VC.
• To use the class in your code simply include Mfccddb.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.
• The main functions of the CCDDB class can and will throw "CDDB::CException" 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.47 (17 August 2022)

• Reworked to use latest version of WinHTTPWrappers classes.

v1.46 (14 August 2022)

• Reworked network code to use author's WinHTTPWrappers classes instead of raw sockets to connect via HTTP to the CDDB servers.

v1.45 (28 May 2022)

• Updated copyright details.
• Updated the code to use C++ uniform initialization for all variable declarations.

v1.44 (28 December 2021)

• Updated copyright details.
• The code has now been tested with gnudb.gnudb.org now that freedb.org has been closed.
• Updated links in documentation to be gnudb.org.

v1.43 (12 April 2020)

• Updated copyright details.
• Fixed more Clang-Tidy static code analysis warnings in the code.

v1.42 (23 December 2019)

• Fixed various Clang-Tidy static code analysis warnings in the code.

v1.41 (29 September 2019)

• Fixed a number of compiler warnings when the code is compiled with VS 2019 Preview

v1.40 (6 June 2019)

• Updated copyright details.
• Updated the code to clean compile on VC 2019

v1.39 (2 January 2019)

• Updated copyright details.
• Fixed a number of C++ core guidelines compiler warnings. These changes mean that the code will now only compile on VC 2017 or later.
• Removed code which supported CWSOCKET_MFC_EXTENSIONS preprocessor define

v1.38 (26 December 2017)

• Updated the code to compile cleanly when _ATL_NO_AUTOMATIC_NAMESPACE is defined.

v1.37 (4 October 2017)

• Replaced NULL throughout the codebase with nullptr. This means that the minimum requirement for the framework is now VC 2010.
• Replaced CString::operator LPC*STR() calls throughout the codebase with CString::GetString calls.

v1.36 (20 May 2017)

• Updated copyright details.
• Updated the code to compile cleanly using /permissive-.

v1.35 (30 July 2016)

• Updated code to use new preprocessor define of CWSOCKET_MFC_EXTENSIONS instead of CWSOCKET_MFC_EXTENSTIONS

v1.34 (26 February 2016)

• Updated copyright details.
• Removed all the proxy connection methods as they cannot be easily supported / tested by the author.
• Updated the code to work with the latest version of the author's CWSocket classes. The CWSocket class requires VC 2008 at a minimum to compile now and this is the earliest supported version of VC for the MfcCDDB classes now.
• Updated the code to clean compile on VC 2010 - VC 2015
• Reworked ParseRecordBodyFromFile method to use ATL::CHeapPtr class.
• Reworked the MapFromProtocolString & MapToProtocolString methods internal implementation.
• All the classes have been moved to a C++ namespace called "CDDB"
• Renamed the "CCDDB" class to "CClient".
• Removed the Read(const String& sDirectory...) method as this requires a full copy of the freedb database on the local file system and this is now approaching 1 GB in size as of Q1 2016.
• Removed the ParseRecordBodyFromFile method.
• Reworked the classes to optionally compile without MFC. By default the class now use STL classes and idioms but if you define CWSOCKET_MFC_EXTENSTIONS the class will revert back to the MFC behaviour.
• Added SAL annotations to all the code.
• Changed ordering of parameters in GetTrackPositionsUsingMCI, GetTrackPositionsUsingDeviceIoControl, ParseRecordBodyHelper, ParseSiteBodyHelper, ParseQueryBodyHelper & Sites methods.
• ParseRecordBodyHelper, ParseSiteBodyHelper, ParseQueryBodyHelper and ParseStatusBody now calls SetLastError with ERROR_INVALID_DATA if they detects parsing errors

v1.33 (10 April 2010)

• Updated copyright details.
• CCDDB::ParseQueryBody now does not consider receiving a 202 response as an error

v1.32 (24 December 2009)

• Removed various preprocessor defines from top of MfcCDDB as they are available in standard VC headers.
• Fixed up a minor case sensitively issue with the various "MfcCDBD" files.
• Updated copyright details.
• Updated the sample app configuration settings to more modern default values.
• Fix a bug where the drive/device name created in GetTrackPositionsUsingDeviceIoControl was incorrectly created as "\\.\\[Drive Letter]:" instead of the correct format of "\\.\[Drive Letter]:". This could lead to this function call failing in certain circumstances. Thanks to "Jase" for reporting this issue.
• Updated the code in CCDDB::ReadResponse in line with the similar response parsing code in the CPJNPOP3Connection v1.47, This helps address an issue where the terminator could not be found if the response gets split across socket calls. This update also helps avoid excessive CPU utilization when we receive large responses. Thanks to Markus Hlacer, "Jase" and Alexey Rabets for reporting this issue.
• Eliminated use of old style CT2A / CA2T macros and replaced with CStringA/W.

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.

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.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.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 unreferenced 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.27 (20 August 2004)

• General tidy up of the GetUserName and GetHostName functions.

v1.26 (3 November 2003)

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

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.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.23 (2 February 2002)

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

v1.22 (8 October 2001)

• Minor update following feedback from freedb.

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.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.19 (5 September 2000)

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

v1.18 (30 May 2000)

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

v1.17 (17 May 2000)

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

v1.16 (7 May 2000)

• Fixed a problem in GetUserName and GetHostName with embedded spaces

v1.15 (13 February 2000)

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

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.13 (17 January 2000)

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

v1.12 (29 November 1999)

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

v1.11 (14 July 1999)

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

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.0 (11 May 1999)

• Initial public release.

API Reference

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

CSite

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

CQueryResult

CQueryResult::CQueryResult
CQueryResult::operator=
CQueryResult::m_sCategory
CQueryResult::m_dwDiscID
CQueryResult::m_sArtist
CQueryResult::m_sTitle

CRecord

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

CStatus

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

CTrackPosition

CTrackPosition::operator=
CTrackPosition::m_nMinute
CTrackPosition::m_nSecond
CTrackPosition::m_nFrame

CClient::CClient
CClient::GetCDROMDrives
CClient::ComputeDiscID...
CClient::GetTrackPositions...
CClient::Sites
CClient::Categories
CClient::SetCDDBProtocolVersion
CClient::GetCDDBProtocolVersion
CClient::Status
CClient::Query
CClient::Read
CClient::Submit
CClient::MessageOfTheDay
CClient::GetProductName
CClient::SetProductName
CClient::GetProductVersion
CClient::SetProductVersion
CClient::GetHelloCommand

CSite::CSite

CSite(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 CClient functions which access a CDDB server.

CSite::operator=

CSite& operator=(const CSite& site);

Parameters

site This CSite instance to copy into this instance.

Remarks

Standard operator= for the CSite class.

CSite::m_sSite

Remarks

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

CSite::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.

CSite::m_sAddress

Remarks

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

CSite::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.

CSite::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.

CSite::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.

CSite::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.

CSite::m_sDescription

Remarks

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

CQueryResult::CQueryResult

CQueryResult();

Remarks

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

CQueryResult::operator=

CQueryResult& operator=(const CQueryResult& result);

Parameters

result This CQueryResult instance to copy into this instance.

Remarks

Standard operator= for the CQueryResult class.

CQueryResult::m_sCategory

Remarks

m_sCategory is of type CDDB::String and contains the category of the album.

CQueryResult::m_dwDiscID

Remarks

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

CQueryResult::m_sArtist

Remarks

m_sArtist is of type CDDB::String and contains the Artist of the album.

CQueryResult::m_sTitle

Remarks

m_sTitle is of type CDDB::String and contains the title of the album.

CRecord

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

CRecord::m_TrackOffsets

Remarks

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

CRecord::m_nDiskLength

Remarks

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

CRecord::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.

CRecord::m_sClientName

Remarks

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

CRecord::m_sClientVersion

Remarks

m_sClientVersion is of type CDDB::String 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.

CRecord::m_sClientComments

Remarks

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

CRecord::m_dwDiscID

Remarks

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

CRecord::m_sArtist

Remarks

m_sArtist is of type CDDB::String and contains the Artist of the album.

CRecord::m_sTitle

Remarks

m_sTitle is of type CDDB::String and contains the title of the album.

CRecord::m_TrackTitles

Remarks

m_TrackTitles is of type CDDB::StringArray and contains the title of each track of the album.

CRecord::m_ExtendedData

Remarks

m_ExtendedData is of type CDDB::StringArray 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".

CRecord::m_ExtendedTrackData

Remarks

m_ExtendedTrackData is of type CDDB::StringArray 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.

CRecord::m_PlayOrder

Remarks

m_PlayOrder is of type CDDB::IntArray 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.

CStatus

Remarks

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

CStatus::m_nCurrentProtocol

Remarks

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

CStatus::m_nMaxProtocol

Remarks

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

CStatus::m_bGetsAllowed

Remarks

m_bGetsAllowed is of type bool and is true if the client is allowed to get log information otherwise false.

CStatus::m_bUpdatesAllowed

Remarks

m_bUpdatesAllowed is of type bool and is true if the client is allowed to initiate a database update otherwise false.

CStatus::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.

CStatus::m_bQuotes

Remarks

m_bQuotes is of type bool and is true if quoted arguments are enabled otherwise false.

CStatus::m_nCurrentUsers

Remarks

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

CStatus::m_nMaxUsers

Remarks

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

CStatus::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.

CStatus::m_nDatabaseEntries

Remarks

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

CStatus::m_Categories

Remarks

m_Categories is of type CDDB::StringArray and is the list of all the categories in the database.

CStatus::m_CategoryEntries

Remarks

m_CategoryEntries is of type CDDB::IntArray and contains the number of entries for each category in the database. The elements at each offset correspond to the m_Categories array.

CStatus::m_PendingSites

Remarks

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

CStatus::m_PendingEntries

Remarks

m_PendingEntries is of type CDDB::IntArray and contains the number of pending entries to be sent to each site. The elements at each offset correspond to the m_PendingSites array.

CTrackPosition

Remarks

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

CTrackPosition::operator=

CTrackPosition& operator=(const CTrackPosition& position);

Parameters

position This CTrackPosition instance to copy into this instance.

Remarks

Standard operator= for the CTrackPosition class.

CTrackPosition::m_nMinute

Remarks

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

CTrackPosition::m_nSecond

Remarks

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

CTrackPosition::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.

CClient::CClient

CClient();

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.

CClient::GetCDROMDrives

void GetCDROMDrives(StringArray& 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 CClient::ComputeDiscID.... The format returned is in the format of "x:" where x is the drive letter of the CDROM drive.

CClient::ComputeDiscID...

DWORD ComputeDiscIDUsingMCI(LPCTSTR pszDrive);

DWORD ComputeDiscIDUsingDeviceIoControl(LPCTSTR pszDrive);

DWORD ComputeDiscID(const TrackPositionArray& 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. 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 CClient::GetTrackPostions function

CClient::GetTrackPositions...

void GetTrackPositionsUsingMCI(LPCTSTR pszDrive, TrackPositionArray& tracks);

void GetTrackPositionsUsingDeviceIoControl(LPCTSTR pszDrive, TrackPositionArray& tracks);

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 CClient::ComputeDiscId... functions. Please note that the format of pszDrive should include a trailing colon e.g. "D:".

CClient::Sites

void Sites(SiteArray& sites, const String& sServer = _T("gnudb.gnudb.org"), const String& sAddress = _T("/~cddb/cddb.cgi"), int nPort = 80);

void Sites(const CSite& server, SiteArray& sites);

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 "gnudb.gnudb.org" to retrieve the site list, whereas the second form allows you to specify the server details through the "server" parameter.

CClient::SetCDDBProtocolVersion

void SetCDDBProtocolVersion(int nProtocolVersion);

Parameters

nProtocolVersion The CDDB protocol version to use.

Remarks

Sets the CDDB protocol version to use.

CClient::GetCDDBProtocolVersion

int GetCDDBProtocolVersion() const;

Return Value

The current CDDB protocol version by using by the code.

Remarks

This is the corollary function to SetCDDBProtocolVersion.

CClient::Categories

void Categories(const CSite& server, StringArray& 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.

CClient::Status

void Status(const CSite& server, CStatus& 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. 

CClient::Query

void Query(const CSite& server, DWORD dwDiscID, const TrackPositionArray& tracks, QueryResultArray& 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. 

CClient::Read

void Read(const CSite& server, DWORD dwDiscID, const String& sCategory, CRecord& 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 CRecord 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. 

CClient::Submit

void Submit(const CSite& server, const String& sCategory, const String& sEmailAddress, CRecord& record, const String& 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. 

CClient::MessageOfTheDay

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

void MessageOfTheDay(const CSite& server, String& 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. 

CClient::GetProductName

String GetProductName() const;

Return Value

The Product Name which the CClient 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".

CClient::SetProductName

void GetProductName(const String& sProductName);

Parameters

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

CClient::GetProductVersion

String GetProductVersion() const;

Return Value

The Product Version which the CClient 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

CClient::SetProductVersion

void GetProductName(const String& sProductVersion);

Parameters

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

CClient::GetHelloCommand

virtual String GetHelloCommand();

Return Value

The string to use for the "hello" command which the CClient 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 CClient 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 CClient and override this function if you so desire. For more information about these details, please consult the CDDB howto document.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
17 August 2022