A class library for receiving and sending of CD-data (www.cdarchiv.de).
(C) 1999-2006 Big 3 Software, Gebr. Schmitz GbR.
Introduction
Version history
Class library
Error codes
Examples
Copyright and terms of practical use
The CDArchiv was developed early 1999. The aim of this new project was to create an extensive online CDArchiv, accessible for everyone.
There are currently about 178.000 CDs in the database (as of July 2006).
New CDs are added on a daily basis. An open interface to send to and receive from the archive is now available. With this tool, developers have the chance to get a large number of CD-information quite easily.
Datum | Version | Änderungen |
31.01.2002 | 1.1 | - New field "Copyright" in the ICDData
class. - New field "Recording Year" for CDs and Tracks in the ICDData class. - Compiled with Microsoft Visual C++ 7.0 (.Net). |
27.08.2001 | 1.01 | - The last parameter of the Open() method was
a DWORD
(unsigned long), which causes some problems in Visual Basic. The
parameter was changed to a normal long data type. - Fixed: IsOpened() always returned TRUE - The return value of ReceiveCD() is now correctly documented. |
25.08.2001 | 1.0 | - Initial release. - Some small bug fixes and interface changes. |
22.08.2001 | 0.9 Beta 2 | - The CDArchive class library is now an Active Template Library (ATL). Threrby it is now possible to use the library from every programming language that is COM/OLE compatible. |
08.07.2001 | 0.9 Beta 1 | - the first public version is released for testing |
Here you get a detailed view of all methods and structures of the CDArchiv class library. To use this class library you have to register it to the system. Use "regsvr32 cdarchive.dll" or register the DLL with an installation program (e.g. InstallShield). You can also register the DLL in your application by calling the DllRegisterServer() function from the cdarchive.dll.
All methods and structures of the CDArchiv class library:
CCDArchive()
Open()
Close()
IsOpened()
SetUser()
ReceiveCD()
SendCD()
Info()
GetLastError()
GetLastErrorMessage()
Returns TRUE, if the connection to the server was successful. FALSE if an error occurred. The exact cause of the error can be determined by calling GetLastError() and GetLastErrorMessage().
szServer
The URL of the CDArchiv server (e.g. "www.cdarchiv.de"). |
szProxy
The URL of a proxy-server, which is necessary for a HTTP-connection. If no proxy-server is needed, this parameter can be NULL or "" (empty String). |
iProxyPort
Port of the proxy-server. Only necessary, if a proxy-server was specified (see szProxy). This parameter will be ignored otherwise. |
dwFlags
Reserved for future extensions. Must be 0. |
Establishes a connection to the CDArchiv server. This connection has to be closed with Close(), if it's not needed any longer.
Returns TRUE, if the connection to the server was closed successfully. Returns FALSE if an error occurred. The exact cause of the error can be determined by calling GetLastError() and GetLastErrorMessage().
-
Closes the active connection to a CDArchiv-Server.
Returns TRUE if a connection to the CDArchiv server is open (active); otherwise FALSE.
-
Checks if there is an existing connection to the CDArchiv server..
-
szUser
Username for the connection to the CDArchiv server. |
szPassword
Password for the connection to the CDArchiv server. |
This method has to be called, before ReceiveCD() or SendCD() are executed. The data you got for the connection to the CDArchiv server has to be used for this. Username and password will be verified not until you call the functions ReceiveCD() or SendCD(). You will get the respective error message then.
If you don't own an user account yet, please fill in the registration form at the CDArchiv server (www.cdarchiv.de). Then - for free- you will get the user account you need to work with the CDArchiv.
Returns CDARCHIV_CD_FOUND if the CD is found, or CDARCHIV_CD_NOT_FOUND if the CD was nof found. CDARCHIV_ERROR will indicate an error. The exact cause of the error can be determined by calling GetLastError() and GetLastErrorMessage().
sIdentity
The unique number (ID) of the inserted CD. This value can be easily determined by calling the certain MCI-function (Microsoft Control Interface) (See our example for this as well.) |
CDData
If the CD was found in the archive, this class is filled with the CD data. See the description of the ICCData class as well. |
Searches the CDArchiv for the CD with its unique number. You have to call SetUser() before.
Return value | Meaning |
CDARCHIV_UPLOAD_RESULT_OK | The CD was transferred successfully into the CDArchiv. |
CDARCHIV_UPLOAD_RESULT_CD_EXISTS | The CD already exists. Call the method again and change the parameter bUpdateExisting into TRUE. |
CDARCHIV_ERROR_UPLOAD_ERROR | An error occurred while transferring the CD. The exact cause of the error can be determined by calling GetLastError() and GetLastErrorMessage(). |
CDData
CD-data which should be transferred into the CDArchiv. Please note that there are some mandatory fields to fill in. |
bUpdateExisting
Set this parameter to TRUE if you want to overwrite an already existing CD with new (respectively corrected) information. If bUpdateExisting is FALSE, the CD will be transferred only if it isn't existing already. |
Transfers a CD with its data into the CDArchiv. You have to call SetUser() before.
Returns TRUE, if the information were read successfully. FALSE will show if an error occurred. The exact cause of the error can be determined by calling GetLastError() and GetLastErrorMessage().
nNumberOfCDs
Contains the number of CDs which are in the CDArchiv at the moment. |
sLastModified
Contains date and time of the last change done in the CDArchiv. |
Delivers information about the current CDArchiv.
Returns the error which occurred last. You can find a detailed error-listing in the chapter "error-codes".
-
-
Returns the error which occurred last in clear text. You can find a detailed error-listing in the chapter "error-codes".
-
Please note that there won't be an explanation for every error message. In this case an empty string will return.
This class contains the cd and track information.
Get method | Set method | Description |
String GetIdentity() | void SetIdentity([in] String sIdentity) | The identity (ID) of the cd. |
String GetArtist() | void SetArtist([in] String sArtist) | The artist of the cd. |
String GetTitle() | void SetTitle([in] String sTitle) | The title of the cd. |
BOOL GetSampler() | void SetSampler([in] BOOL bSampler) | TRUE, if the cd is a sampler (different artists for every track), otherwise FALSE. |
long GetTotalLength() | void SetTotalLength([in] long lTotalLength) | The total length of the cd in milliseconds. |
long GetNumberOfTracks() | void SetNumberOfTracks([in] long lNumberOfTracks) | The number of tracks on the cd. |
String GetCategory() | void SetCategory([in] String sCategory) | The category (e.g. "Rock/Pop") of the cd. |
String GetMedia() | void SetMedia([in] String sMedia) | The media type of the cd (e.g. "CD", "CD-Single", "DVD", etc.) |
String GetComment() | void SetComment([in] String sComment) | An additional comment field for the cd. |
String GetTrackArtist([in] long lTrack) | void SetTrackArtist([in] long lTrack, [in] String sArtist) | The artist of the given track (starting with 0). |
String GetTrackTitle([in] long lTrack) | void SetTrackTitle([in] long lTrack, [in] String sTitle) | The title of the given track (starting with 0). |
long GetTrackLength([in] long lTrack) | void SetTrackLength([in] long lTrack, [in] long lLength) | The length of the given track (starting with 0) in milliseconds. |
long GetTrackBPM([in] long lTrack) | void SetTrackBPM([in] long lTrack, [in] long lBPM) | The beats per minute (BPM) of the given track (starting with 0). |
String GetTrackComment([in] long lTrack) | void SetTrackComment([in] long lTrack, [in] String sComment) | An additional comment field of the given track (starting with 0). |
String GetTrackLyrics([in] long lTrack) | void SetTrackLyrics([in] long lTrack, [in] String sLyrics) | The lyrics of the given track (starting with 0). |
In this chapter error-codes are described, which can occur while calling a CDArchiv function. They're returned by GetLastError().
Error code | Error number* | Remark |
CDARCHIV_ERROR_OK | 0 | No error. Everything's ok. |
CDARCHIV_ERROR_NO_SESSION | 1 | Internet session isn't available or an error occurred while
the internet session was set up. Possible cause: An old wininet.dll is installed on the system. |
CDARCHIV_ERROR_NO_CONNECTION | 2 | An error occurred while connecting to the CDArchiv server. Possible cause: there's no internet connection, a wrong proxy was named, there's no CDArchiv existing on the chosen server or the server is down temporarily |
DARCHIV_ERROR_NOT_CONNECTED | 3 | // You are not connected to a CDArchiv server |
CDARCHIV_ERROR_UNKNOWN_TAG | 4 | // Unknown tag found |
CDARCHIV_ERROR_REQUEST_ERROR | 5 | // Request error. Internal error (server down?). // Contact Big 3 Software for details. |
CDARCHIV_ERROR_NO_IDENTITY | 6 | // CD does not have an identity (upload not possible) |
CDARCHIV_ERROR_UPLOAD_ERROR | 7 | // General update error (server down?). Internal error. // Contact Big 3 Software for details. |
CDARCHIV_ERROR_VERIFY_IDENTITY | 100 | // Identity field is empty |
CDARCHIV_ERROR_VERIFY_ARTIST | 101 | // Artist field is empty |
CDARCHIV_ERROR_VERIFY_TITLE | 102 | // Title field is empty |
CDARCHIV_ERROR_VERIFY_TOTALLENGTH | 103 | // Total length have to be > 10000 ms |
CDARCHIV_ERROR_VERIFY_TRACKTITLE | 104 | // One of the track titles is empty |
* Better use the error code always. Use the error number only by way of exception, because the error codes could have different values in a future version.
The following example establishes a connection to the CDArchiv server and shows the number of CDs and the last date of change.
void Test(LPCTSTR sServer) { ICDArchive CDArchiv; CDArchiv.CreateDispatch("CDArchive.CDArchive.1"); long lRet; lRet = CDArchiv.Open(m_sServerName, NULL, 0, 0); if (!lRet) return; // Error long lNumberOfCDs; DATE dtLastModified; lRet = CDArchiv.Info(&lNumberOfCDs, &dtLastModified); if (!lRet) { CString str; str.Format("Error: %d\n\n%s", CDArchiv.GetLastError(), CDArchiv.GetLastErrorMessage()); AfxMessageBox(str); return; } lRet = CDArchiv.Close(); if (!lRet) return; // Error CString str; COleDateTime dtMod(dtLastModified); CString sLastModified = dtMod.Format("%c"); str.Format("CDArchiv successfully connected!\n\nNumber of CDs: %d\nLast modified: %s", lNumberOfCDs, sLastModified); AfxMessageBox(str); }
You can find an extensive example program on the CDArchiv server in the "developer" section, which uses the CDArchiv class library. We suggest you to study this program thoroughly, to get a complete view of the CDArchiv and the use of this library.
The use of this CDArchiv is free. We charge absolutely no fee, you don't need to subscribe a contract and you are not under any obligation to us. We furthermore promise that we won't change this in the future!
If you are developer of a CD-player or any other program and want to use our CDArchiv, you're welcome! The only condition for you is to tell us. Please use the registration form at the CDArchiv server. You will get an username and a password, to get access to the CD-data bank.
Additionally we want to ask you for one thing: if you're a developer, please give a small hint to our CDArchiv somewhere in your program (best in the about-box). Of course this is no duty, but we would be very happy about it. Keeping up and widening the data is a lot of work, and we think that a small hint and/or an URL in your program is not an unreasonable demand, is it? :o)
For the people in a hurry here a text, which can be taken over by "Copy&Paste":
CDArchiv.de is a free service by Big 3 Software, Gebr. Schmitz GbR. You'll find further information to the CDArchiv at www.cdarchiv.de.