mfccddb.htm

MfcCDDB v1.11 A freeware MFC class to support access to CDDB servers Welcome to MfcCDDB, a collectio

<p><font face="Arial"><strong>Parameters</strong></font></p>

<p><font face="Arial"><em>server</em> The server to use as specified through its
parameters <strong><a href="#m_sSite">m_sSite</a>, <a href="#m_nPort">m_nPort</a></strong>
and<strong> <a href="#m_sAddress">m_sAddress</a></strong> parameters<strong>.</strong></font></p>

<p><font face="Arial"><em>dwDiscID</em> The DISC-ID of the album.</font></p>

<p><font face="Arial"><em>sCategory</em> The CDDB category which the album belongs to.</font></p>

<p><font face="Arial"><em>record</em> Upon successful return this will contain the album
details in a <strong><a href="#CCDDBRecord">CCDDBRecord</a></strong> instance.</font></p>

<p><strong><font face="Arial">Remarks</font></strong></p>

<p><font face="Arial">Issues the CDDB &quot;read&quot; 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.&nbsp; </font></p>

<p>&nbsp;</p>

<p><big><a name="Submit"></a><strong><font face="Arial">CCDDB::Submit</font></strong></big></p>

<p><font face="Arial"><strong>BOOL Submit(const CCDDBSite&amp;</strong> <em>server</em>, <strong>const
CString&amp; </strong><em>sCategory</em><strong>, const CString&amp; </strong><em>sEmailAddress</em><strong>,
CCDDBRecord&amp;</strong> <em>record</em><strong>, const CString&amp; </strong><em>sRejectionNotice,
</em><strong>BOOL </strong><em>bReallySubmit </em><strong>= TRUE);</strong></font></p>

<p class="rl"><strong><font face="Arial">Return Value</font></strong></p>

<p class="t"><font face="Arial">TRUE if the record was successfully submitted to the CDDB
server otherwise FALSE.</font></p>

<p><font face="Arial"><strong>Parameters</strong></font></p>

<p><font face="Arial"><em>server</em> The server to use as specified through its
parameters <strong><a href="#m_sSite">m_sSite</a> </strong>and <strong><a href="#m_nPort">m_nPort</a></strong>
parameters<strong>.</strong></font></p>

<p><font face="Arial"><em>sCategory</em> The CDDB category which the album belongs to.</font></p>

<p><font face="Arial"><em>sEmailAddress</em> The email address where any submission
failure notices should be mailed to.</font></p>

<p><font face="Arial"><em>record</em> Details of the album to be added to the CDDB
database.</font></p>

<p><font face="Arial"><em>sRejectionNotice</em> Arbitrary message to be included at the
top of any rejection notice that may be sent to the submitting user</font></p>

<p><font face="Arial"><em>bReallySubmit</em> Indicates whether the submission is a test
submission or a real submission to the database.</font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">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
&quot;sEmailAddress&quot;. 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.&nbsp; </font></p>

<p>&nbsp;</p>

<p><big><a name="MessageOfTheDay"></a><strong><font face="Arial">CCDDB::MessageOfTheDay</font></strong></big></p>

<p><font face="Arial"><strong>BOOL MessageOfTheDay(CString&amp; </strong><em>sMessage</em><strong>,
const CString&amp; </strong><em>sServe</em>r<strong> = _T(&quot;cddb.cddb.com&quot;),
const CString&amp; </strong><em>sAddress<strong> = </em>_T(&quot;/~cddb/cddb.cgi&quot;),
int </strong><em>nPort<strong> = </em>80);</strong></font></p>

<p><font face="Arial"><strong>BOOL MessageOfTheDay(const CCDDBSite&amp;</strong> <em>server</em>,
<strong>CString&amp; </strong><em>sMessage</em><strong>);</strong></font></p>

<p class="rl"><strong><font face="Arial">Return Value</font></strong></p>

<p class="t"><font face="Arial">TRUE if the message of the day was successfully retrieved
server otherwise FALSE.</font></p>

<p><font face="Arial"><strong>Parameters</strong></font></p>

<p><font face="Arial"><em>sMessage</em> Upon successful return, this will contain the
&quot;Message of the Day&quot;.</font></p>

<p><font face="Arial"><em>sServer</em> The IP address or domain name of the CDDB HTTP
server to use.</font></p>

<p><font face="Arial"><em>sAddress</em> The HTTP request to make.</font></p>

<p><font face="Arial"><em>nPort</em> The TCP/IP port number on which to make the
connection.</font></p>

<p><font face="Arial"><em>server</em> The server to use as specified through its
parameters <strong><a href="#m_sSite">m_sSite</a>, <a href="#m_nPort">m_nPort</a></strong>
and<strong> <a href="#m_sAddress">m_sAddress</a></strong> parameters<strong>.</strong></font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">Issues the CDDB &quot;motd&quot; 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.&nbsp; </font></p>

<p>&nbsp;</p>

<p><a name="GetTimeout"></a><big><strong><font face="Arial">CCDDB::GetTimeout</font></strong></big></p>

<p><strong><font face="Arial">DWORD GetTimeout() const;</font></strong></p>

<p class="rl"><strong><font face="Arial">Return Value</font></strong></p>

<p class="t"><font face="Arial">The timeout in milliseconds which the code will wait for
responses from the CDDB server.</font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">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.</font></p>

<p>&nbsp;</p>

<p><a name="SetTimeout"></a><big><strong><font face="Arial">CCDDB::SetTimeout</font></strong></big></p>

<p><font face="Arial"><strong>void SetTimeout(DWORD </strong><em>dwTimeout</em><strong>)
const;</strong></font></p>

<p><font face="Arial"><strong>Parameters</strong></font></p>

<p><font face="Arial"><em>dwTimeout</em> The new timeout value in milliseconds.</font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">Sets the timeout to use for connections to the CDDB server.</font></p>

<p>&nbsp;</p>

<p><a name="GetLastError"></a><big><strong><font face="Arial">CCDDB::GetLastError</font></strong></big></p>

<p><strong><font face="Arial">DWORD GetLastError() const;</font></strong></p>

<p class="rl"><strong><font face="Arial">Return Value</font></strong></p>

<p class="t"><font face="Arial">The last error generated by the CCDDB class as a DWORD.</font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">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.</font></p>

<p>&nbsp;</p>

<p><a name="GetErrorMessage"></a><big><strong><font face="Arial">CCDDB::GetErrorMessage</font></strong></big></p>

<p><strong><font face="Arial">CString GetErrorMessage() const;</font></strong></p>

<p class="rl"><strong><font face="Arial">Return Value</font></strong></p>

<p class="t"><font face="Arial">A string representation of the last error generated by the
CCDDB class.</font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">Returns a CString representation of the last error generated by the
CCDDB class. Internally this function will call FormatMessage or mciGetErrorString as
appropriate.</font></p>

<p>&nbsp;</p>

<p><a name="GetLastCommandResponse"></a><big><strong><font face="Arial">CCDDB::GetLastCommandResponse</font></strong></big></p>

<p><strong><font face="Arial">CString GetLastCommandResponse() const;</font></strong></p>

<p class="rl"><strong><font face="Arial">Return Value</font></strong></p>

<p class="t"><font face="Arial">The last command response from the server as a CString.</font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">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. </font></p>

<p>&nbsp;</p>

<p><a name="GetProductName"></a><big><strong><font face="Arial">CCDDB::GetProductName</font></strong></big></p>

<p><strong><font face="Arial">CString GetProductName() const;</font></strong></p>

<p class="rl"><strong><font face="Arial">Return Value</font></strong></p>

<p class="t"><font face="Arial">The Product Name which the CCDDB class will use
internally.</font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">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 <strong><a href="#SetProductName">SetProductName</a></strong>. For
more information about, please consult the CDDB howto document.&nbsp;</font></p>

<p>&nbsp;</p>

<p><a name="SetProductName"></a><big><strong><font face="Arial">CCDDB::SetProductName</font></strong></big></p>

<p><font face="Arial"><strong>void GetProductName(const CString&amp; </strong><em>sProductName</em><strong>);</strong></font></p>

<p class="rl"><strong><font face="Arial">Parameters</font></strong></p>

<p class="t"><font face="Arial"><em>sProductName</em> The Product Name which the CCDDB
class will use internally.</font></p>

<p>&nbsp;</p>

<p><a name="GetProductVersion"></a><big><strong><font face="Arial">CCDDB::GetProductVersion</font></strong></big></p>

<p><strong><font face="Arial">CString GetProductName() const;</font></strong></p>

<p class="rl"><strong><font face="Arial">Return Value</font></strong></p>

<p class="t"><font face="Arial">The Product Version which the CCDDB class will use
internally.</font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">As well as the product name being required when connecting to a CDDB
server, a version number is also required. As mentioned in the howto document,</font> <font
face="Arial">this field has a very specific format which should be observed:<br>
<br>
[leading text]version_number[release type][level]<br>
<br>
Where:<br>
<br>
&nbsp;&nbsp;&nbsp; Leading text: is any string which does not include numbers.<br>
&nbsp;&nbsp;&nbsp; Version number and level: is any (possibly) decimal-separated list of<br>
&nbsp;&nbsp;&nbsp; positive numbers.<br>
&nbsp;&nbsp;&nbsp; Release type: is a string of the form:<br>
&nbsp;&nbsp;&nbsp; alpha, a, beta, b, patchlevel, patch, pl<br>
&nbsp;&nbsp;&nbsp; Level: is a positive number.<br>
<br>
For example:<br>
<br>
&nbsp;&nbsp;&nbsp; release:2.35.1alpha7<br>
&nbsp;&nbsp;&nbsp; v4.0PL0<br>
&nbsp;&nbsp;&nbsp; 2.4</font></p>

<p>&nbsp;</p>

<p><a name="SetProductVersion"></a><big><strong><font face="Arial">CCDDB::SetProductVersion</font></strong></big></p>

<p><font face="Arial"><strong>void GetProductName(const CString&amp; </strong><em>sProductVersion</em><strong>);</strong></font></p>

<p class="rl"><strong><font face="Arial">Parameters</font></strong></p>

<p class="t"><font face="Arial"><em>sProductVersion</em> The Product Version which the
CCDDB class will use internally.</font></p>

<p>&nbsp;</p>

<p><a name="GetHelloCommand"></a><big><strong><font face="Arial">CCDDB::GetHelloCommand</font></strong></big></p>

<p><strong><font face="Arial">virtual CString GetHelloCommand();</font></strong></p>

<p class="rl"><strong><font face="Arial">Return Value</font></strong></p>

<p class="t"><font face="Arial">The string to use for the &quot;hello&quot; command which
the CCDDB class will use internally.</font></p>

<p><font face="Arial"><strong>Remarks</strong></font></p>

<p><font face="Arial">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:</font></p>

<p><font face="Arial">hello=username+domainname+ProductName+ProductVersion</font></p>

<p><font face="Arial">The default implementation of this function in CCDDB uses the
username as returned from the SDK function &quot;GetUserName&quot;, the local machines
domain name as returned from &quot;gethostname&quot; 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.</font></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><font face="Arial"><big><a name="Enhancements"></a></big><font color="#000000" size="4"><strong>PLANNED
ENHANCEMENTS</strong></font> </font>

<ul>
  <li><font face="Arial">Package the code up into an OCX, COM Interface or DLL to allow non
    MFC apps to use the code.</font></li>
  <li><font face="Arial">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.</font></li>
  <li><font color="#000000" size="3" face="Arial">If you have any other suggested
    improvements, please let me know so that I can incorporate them into the next release.</font></li>
</ul>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><font face="Arial"><a name="Contact"></a><font color="#000000" size="4"><strong>CONTACTING
THE AUTHOR</strong></font></font></p>

<p><font color="#000000" size="3" face="Arial">PJ Naughter<br>
Email: <a href="mailto:pjn@indigo..ie">[e-mail]</a><br>
Web: <a href="http://indigo.ie/~pjn">http://indigo.ie/~pjn</a><br>
14th July 1999</font></p>
</body>
</html>