CDArchive Version 1.1
(31/Jan/2002)

A class library for receiving and sending of CD-data (www.cdarchiv.de).
(C) 1999-2006 Big 3 Software, Gebr. Schmitz GbR.


Directory:

Introduction
Version history
Class library
Error codes
Examples
Copyright and terms of practical use


Introduction:

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.


Version history:

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

 


Class library

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.

ICDArchive - Contains methods for sending or receiving CD information

ICDData - Contains all information about the CD and the tracks

 


ICDArchive

All methods and structures of the CDArchiv class library:

    CCDArchive()
    Open()
    Close()
    IsOpened()
    SetUser()
    ReceiveCD()
    SendCD()
    Info()
    GetLastError()
    GetLastErrorMessage()


ICDArchive::Open

long Open([in] String sServer, [in] String sProxy, [in] int iProxyPort, [in] long dwFlags);

Return value:

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().

Parameter:

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.

Remark:

Establishes a connection to the CDArchiv server. This connection has to be closed with Close(), if it's not needed any longer. 


ICDArchive::Close

long Close();

Return value:

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().

Parameter:

-

Remark:

Closes the active connection to a CDArchiv-Server.


ICDArchive::IsOpened

BOOL IsOpened();

Return value:

Returns TRUE if a connection to the CDArchiv server is open (active); otherwise FALSE.

Parameter:

-

Remark:

Checks if there is an existing connection to the CDArchiv server..


ICDArchive::SetUser

void SetUser([in] String sUser, [in] String sPassword);

Return value:

-

Parameter:

szUser

Username for the connection to the CDArchiv server.

szPassword

Password for the connection to the CDArchiv server.

Remark:

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.


ICDArchive::ReceiveCD

long ReceiveCD([in] String sIdentity, [out] ICDData CDData);

Return value:

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().

Parameter:

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. 

Remark:

Searches the CDArchiv for the CD with its unique number. You have to call SetUser() before.


ICDArchive::SendCD

long SendCD([in] ICDData CDData, [in] BOOL bUpdateExisting);

Return value:

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().

Parameter:

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.

Remark:

Transfers a CD with its data into the CDArchiv. You have to call SetUser() before.


ICDArchive::Info

long Info([out] long lNumberOfCDs, [out] DATE dtLastModified);

Return value:

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().

Parameter:

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.

Remark:

Delivers information about the current CDArchiv.


ICDArchive::GetLastError

int GetLastError();

Return value:

Returns the error which occurred last. You can find a detailed error-listing in the chapter "error-codes".

Parameter:

-

Remark:

-


ICDArchive::GetLastErrorMessage

CString GetLastErrorMessage();

Return value:

Returns the error which occurred last in clear text. You can find a detailed error-listing in the chapter "error-codes".

Parameter:

-

Remark:

Please note that there won't be an explanation for every error message. In this case an empty string will return.

 


ICDData

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

 


Error codes

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.


Examples

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.

 


Copyright and conditions of use

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.