CDArchive Version 1.1
(31.01.2002)

Eine Klassenbibliothek (Active Template Library) zum Empfangen und Senden von CD-Daten.
(C) 1999-2002 Big 3 Software, Gebr. Schmitz GbR 

Inhaltsverzeichnis

Einleitung
Versionsgeschichte
Klassenbibliothek
Fehlercodes
Beispiel
Copyrighthinweise und Nutzungsbedingungen

Einleitung

Das CD-Archiv wurde Anfang 1999 entwickelt. Es handelt sich hierbei um ein ehrgeiziges und neues Projekt mit dem Ziel, ein großes Online CD-Archiv aufzubauen. Dieses CD-Archiv sollte für jedermann zugänglich sein.

Im Laufe der Zeit entwickelte sich ein CD-Archiv, welches täglich mehr CDs enthielt. Zur Zeit (Stand August 2001) befinden sich ca. 47000 CDs in der Datenbank. und täglich kommen weitere CDs hinzu.

Mit dieser offenen Programmierschnittstelle ist es nun möglich, von einem Programm aus auf diese Datenbank zuzugreifen. Hiermit haben Entwickler nunmehr die Möglichkeit, in Ihre eigenen Programm einfach auf eine große Anzahl von CD-Informationen zuzugreifen.

Versionsgeschichte

Klassenbibliothek

Hier erhalten Sie einen Überblick über die Schnittstellen dieser Klassenbibliothek. Damit Sie diese Klassenbibliothek benutzen können, muss sie im System registriert werden. Benutzen Sie hierzu den Befehl "regsvr32 cdarchive.dll" oder registrieren Sie die DLL über ein Setup-Programm (z.B.: Installshield). Falls Sie die DLL aus einem Programm heraus registrieren möchten, starten Sie die Funktion DllRegisterServer() aus der cdarchive.dll.

ICDArchive - Bietet Methoden zum Senden und Empfangen von CD-Informationen.

ICDData - Beinhaltet alle Informationen der CD und der einzelnen Tracks

ICDArchive

Hier erhalten Sie einen ausführlichen Überblick über alle Methoden und Strukturen der CDArchive Klassenbibliothek.

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

ICDArchive::Open

long Open([in] String sServer, [in] String sProxy, [in] long lProxyPort, [in] long lFlags);

Rückgabewert:

Liefert TRUE zurück, wenn die Verbindung zum angegebenen Server erfolgreich hergestellt wurde. Tritt ein Fehler auf, wird FALSE zurückgeliefert. Die genaue Fehlerursache kann durch Aufruf von GetLastError() und GetLastErrorMessage() ermittelt werden.

Parameter:

sServer

sProxy

lProxyPort

lFlags

Bemerkungen:

Stellt eine Verbindung zum angegebenen CD-Archiv Server her. Die Verbindung muss mit der Methode Close() geschlossen werden, wenn sie nicht mehr benötigt wird.

ICDArchive::Close

BOOL Close();

Rückgabewert:

Liefert TRUE zurück, wenn die Verbindung zum angegebenen Server erfolgreich geschlossen wurde. Tritt ein Fehler auf, wird FALSE zurückgeliefert. Die genaue Fehlerursache kann durch Aufruf von GetLastError() und GetLastErrorMessage() ermittelt werden.

Parameter:

-

Bemerkungen:

Schließt die aktive Verbindung zu einem CD-Archiv Server.

ICDArchive::IsOpened

BOOL IsOpened();

Rückgabewert:

Liefert TRUE zurück, wenn eine Verbindung zum einem CD-Archiv Server hergestellt wurde (also aktiv ist); ansonsten FALSE.

Parameter:

-

Bemerkungen:

Überprüft, ob eine Verbindung zu einem CD-Archiv Server besteht.

ICDArchive::SetUser

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

Rückgabewert:

-

Parameter:

sUser

sPassword

Bemerkungen:

Diese Methode muss aufgerufen werden, bevor die Methoden ReceiveCD() oder SendCD() ausgeführt werden. Benutzen Sie hierzu die Daten, die Sie für die Verbindung auf den CD-Archiv Server erhalten haben. Der Benutzername und das Password werden erst dann überprüft, wenn Sie eine der Funktionen ReceiveCD() oder SendCD() aufrufen. Sie erhalten dann eine entsprechende Fehlermeldung.

Falls Sie noch kein Benutzerkonto besitzen, füllen Sie bitte das Anmeldeformular auf dem CD-Archiv Server (www.cdarchiv.de) aus. Sie erhalten dann kostenlos ein Benutzerkonto, welches Sie für die Benutzung des CD-Archiv Servers benötigen..

ICDArchive::ReceiveCD

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

Rückgabewert:

Liefert CDARCHIV_CD_FOUND zurück, wenn die CD gefunden wurde oder CDARCHIV_CD_NOT_FOUND, wenn sie nicht gefunden wurde. Falls ein Fehler auftritt, wird CDARCHIV_ERROR zurückgeliefert. Die genaue Fehlerursache kann durch Aufruf von GetLastError() und GetLastErrorMessage() ermittelt werden.

Parameter:

sIdentity

CDData

Bemerkungen:

Sucht die CD mit der angegebenen eindeutigen Nummer (ID) im aktuell geöffneten CD-Archiv. Vorher muss die Methode SetUser() abgerufen worden sein.

ICDArchive::SendCD

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

Rückgabewert:

Parameter:

CDData

bUpdateExisting

Bemerkungen:

Überträgt eine CD mit den angegebenen CD-Daten in das CD-Archiv.

ICDArchive::Info

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

Rückgabewert:

Liefert TRUE zurück, wenn die Informationen erfolgreich ausgelesen wurden. Falls ein Fehler auftritt, wird FALSE zurückgeliefert. Die genaue Fehlerursache kann durch Aufruf von GetLastError() und GetLastErrorMessage() ermittelt werden.

Parameter:

lNumberOfCDs

dtLastModified

Bemerkungen:

Liefert Informationen über das aktuelle CD-Archiv zurück.

ICDArchive::GetLastError

long GetLastError();

Rückgabewert:

Liefert den zuletzt aufgetretenen Fehler zurück. Eine genaue Fehlerauflistung finden Sie im Kapitel Fehlercodes.

Parameter:

-

Bemerkungen:

-

ICDArchive::GetLastErrorMessage

String GetLastErrorMessage();

Rückgabewert:

Liefert den zuletzt aufgetretenen Fehler im Klartext zurück. Eine genaue Fehlerauflistung finden Sie im Kapitel Fehlercodes.

Parameter:

-

Bemerkungen:

Beachten Sie bitte, dass nicht für jede Fehlermeldung eine erläuternde Beschreibung zurückgeliefert wird. In diesem Falle wird ein leerer String zurückgeliefert.

ICDData

Diese Klasse beinhaltet alle Informationen zu einer CD.

Fehlercodes

In diesem Abschnitt sind die Fehlercodes und -meldungen beschrieben, die beim Aufruf einer CDArchiv-Funktion auftreten können. Diese werden durch den Aufruf von GetLastError() zurückgeliefert.

* Sie sollten immer den Fehlercode abfragen und nur in Ausnahmefällen die Fehlernummer direkt. Es ist möglich, dass die einzelnen Fehlercodes in einer zukünftigen Version andere Werte haben. Die Fehlercodes sind in der mitgelieferten Header-Datei CDArchivDefines.h definiert. Diese können Sie unter Visual C++ direkt einbinden.

Beispiel

Das folgende Microsoft VC++-Beispiel stellt eine Verbindung zum CD-Archiv Server her und gibt die Anzahl der CDs und das letzte Änderungsdatum aus.

void Test(LPCTSTR sServer)
{
   ICDArchive CDArchiv;
   CDArchiv.CreateDispatch("CDArchive.CDArchive.1");
   long lRet;

   lRet = CDArchiv.Open(m_sServerName, NULL, 0, 0);
   if (!lRet)
       return;          // Fehler

   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;         // Fehler aufgetreten

   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);
}

Auf dem CD-Archiv Server finden Sie in der "Developer"-Sektion ein umfangreiches Beispielprogramm, welches die CDArchive Klassenbibliothek benutzt. Wir empfehlen Ihnen, dieses Beispielprogramm in Ruhe anzuschauen, um einen kompletten Überblick über das CDArchive und die Benutzung dieser Bibliothek zu bekommen.

Copyrighthinweise und Nutzungsbedingungen

Wir erheben keinerlei Gebühren für die Benutzung unseres CD-Archivs und Sie müssen keinen Vertrag unterzeichnen oder sonstige Verpflichtungen eingehen. Wir versprechen Ihnen außerdem, dass dies auch in Zukunft so bleiben wird!

Falls Sie Entwickler eines CD-Spielers oder eines anderen Programms sind und auf unser CD-Archiv zugreifen möchten, können Sie dies gerne tun. Die einzige Voraussetzung ist, dass Sie uns dies miteilen. Benutzen Sie hierzu das Anmeldeformular auf dem CD-Archiv Server. Sie erhalten dann einen Benutzernamen und ein Kennwort, um auf die CD-Datenbank zugreifen zu können.
Außerdem möchten wir die Programmierer bitten, irgendwo im Programm (am besten in der About-Box) einen kleinen Hinweis auf unser CD-Archiv zu geben. Wie gesagt, dies ist keine Pflicht, wir würden uns aber sehr darüber freuen. Wir haben mir der Pflege und Erweiterung des CD-Archivs eine Menge Arbeit, und ich denke, dass ein kleiner Hinweis und/oder eine URL in Ihrem Programm wohl nicht zu viel verlangt ist, oder? :-)

Für ganz Eilige hier ein kurzer Text, der einfach mit "Copy&Paste" übernommen werden kann:

Das CD-Archiv ist ein kostenloser Dienst von Big 3 Software, Gebr. Schmitz GbR.
Weitere Informationen zum CD-Archiv erhalten Sie unter www.cdarchiv.de.