MfcCDDB v1.15

Download source files - 38 Kb

Introduction

Welcome to MfcCDDB, a collection of freeware MFC 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.

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,cddb.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

Usage

History

API Reference

Planned Enhancements

Contacting the Author

Features

• Simple and clean C++ interface.
• The interface provided is synchronous which provides an easier programming model than using asynchronous sockets.
• The code does not rely on the MFC socket classes. These classes have a number of shortcomings, one of which causes problems when they are used in NT services.
• The code can be used in a console application without any problems (Again this is not the case for the MFC socket classes).
• A configurable timeout for the connection can be set through the class API.

Usage

• To use the class in your code simply include mfccddb.cpp in your project and #include mfccddb.h in which ever of your modules needs to make calls to the classes.
• Your code will need to include MFC either statically or dynamically.
• You will need to have a functioning Winsock stack installed and correctly initialized prior to calling any functions in the CCDDB which access the CDDB servers. Depending on your application, this will involve calling either WSAStartup() or AfxSocketInit() at startup of your application.
• You will also need to have winsock.h or afxsock.h in your precompiled header. The code will work just as well in a GUI or console app. The code should also work in a multithreaded application, although it has not be explicitly tested in this scenario.
• To see the class in action, have a look at the code in InitInstance() in the module app.cpp.

History

V1.0 (11 May 1999)

• Initial public release.

V1.1 (20th 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 (14th July 1999)

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

V1.12 (29th November 1999)

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

V1.13 (17th January 2000)

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

V1.14 (23rd January 2000)

• The code has now been fully tested with the open source alternative to CDDB namely freedb.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 (13th February 2000)

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

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
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::GetLastError
CCDDB::GetErrorMessage
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".

CCDDBSite::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

BOOL ComputeDiscID(DWORD& dwDiscID, LPCTSTR pszDrive = NULL);
DWORD ComputeDiscID(const CArray<CCDDBTrackPosition, CCDDBTrackPosition&>& tracks);

Return Value:

1. TRUE if the CDDB DISC-ID was computed successfully otherwise FALSE.
2. The computed DISC-ID of the specified track positions.

Parameters:

• dwDiscID -- Upon successful return from the first form of the function, this will contain the DISC-ID of the inserted album.
• 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 then the default CDROM drive will be used. 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

BOOL GetTrackPositions(CArray<CCDDBTrackPosition, CCDDBTrackPosition&>& tracks, LPCTSTR pszDrive = NULL);

Return Value:
TRUE if the track positions were obtained successfully otherwise FALSE.

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, then the default 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() function.

CCDDB::Sites

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

Return Value:
TRUE if the sites command was issued successfully otherwise FALSE.

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 -- he 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. This is only required if you will be using the open source CDDB server freedb.freedb.org instead of the normal CDDB server cddb.cddb.com which as of January 2000 only supports CDDB protocol version 3. For further details see the history section for v1.14 or checkout their web site.

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

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

Return Value:
TRUE if the Categories command was issued successfully otherwise FALSE.

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

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

Return Value:
TRUE if the "Stat" command was issued successfully otherwise FALSE.

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

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

Return Value:
TRUE if the "query" command was issued successfully otherwise FALSE.

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

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

Return Value:
TRUE if the "read" command was issued successfully otherwise FALSE.

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.
• 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

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

Return Value:
TRUE if the record was successfully submitted to the CDDB server otherwise FALSE.

Parameters:

• server -- The server to use as specified through its parameters m_sSite, m_nPort and m_sAddress 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

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

Return Value:
TRUE if the message of the day was successfully retrieved otherwise FALSE.

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::GetLastError

DWORD GetLastError() const;

Return Value:
The last error generated by the CCDDB class as a DWORD.

Remarks:
Since the class uses MCI which has its own way of reporting errors different to the standard Win32 way, this method allows a uniform interface to the MCI and normal Win32 SDK last error in one function call.

CCDDB::GetErrorMessage

CString GetErrorMessage() const;

Return Value:
A string representation of the last error generated by the CCDDB class.

Remarks:
Returns a CString representation of the last error generated by the CCDDB class. Internally this function will call FormatMessage or mciGetErrorString as appropriate.

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 SetProductName(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:

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

For example:

release:2.35.1alpha7
v4.0PL0
2.4

CCDDB::SetProductVersion

void SetProductName(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.

Planned Enhancements

• Package the code up into an OCX, COM Interface or DLL to allow non MFC apps to use the code.
• Provide a better sample app. At the moment, it's very much a test program which tests all of the functions in the classes provided. An app I am considering is a program which will allow a number of CDDB requests to be queued while offline and when online or upon request, all the requests will be performed and the results exported to the Windows CD Player ini file.
• If you have any other suggested improvements, please let me know so that I can incorporate them into the next release.

Contacting the Author

PJ Naughter
Email: pjn@indigo.ie
Web: http://www.naughter.com
13th February 2000