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:

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

szProxy

iProxyPort

dwFlags

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

szPassword

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

CDData

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:

Parameter:

CDData

bUpdateExisting

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

sLastModified

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.

Error codes

In this chapter error-codes are described, which can occur while calling a CDArchiv function. They're returned by GetLastError().

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