|
HitbasePlug-In InterfaceDieses Dokument beschreibt das Plug-In Interface von Hitbase. Sie haben hiermit die Möglichkeit, verschiedene Erweiterungen selbst zu schreiben und an Hitbase anzubinden. Hitbase Plug-Ins (später auch "hpi" genannt) sind Dynamic Link Libraries (DLLs), die bestimmte Funktionen und Methoden implementieren. Diese werden im folgenden beschrieben. Es folgt eine Schritt-für-Schritt Anleitung zum Erzeugen von Hitbase Plug-Ins. Prinzipiell können Sie Hitbase Plug-Ins in jeder Programmiersprache schreiben, die die Erzeugung von DLLs unterstützt. Die Beschreibung und Beispiele sind für Microsoft Visual C++ 5.0 ausgelegt. Es sollte jedoch einfach sein, diese auf andere Programmversionen bzw. Programmiersprachen anzupassen. Inhaltsverzeichnis 1. Anlegen eines Hitbase Plug-Ins
Anlegen eines Hitbase Plug-Ins1. Starten Sie Microsoft Visual C++ 5.0.
Beschreibung der FunktionenAlle Funktionen, die in diesem Abschnitt beschrieben sind, müssen in Ihrem Hitbase Plug-In implementiert werden (unter Umständen sind sie leer, aber sie müssen da sein!). BOOL hpiInit(HPI_INFO* phpiInit); Diese Funktion wird von Hitbase direkt nach dem Laden des Plug-Ins aufgerufen. Plug-Ins werden beim Programmstart von Hitbase geladen. Die HPI_INFO Struktur hat die folgende Form. Bitte beachten Sie, daß die Variable nInterfaceVersion von Hitbase gefüllt wird und nicht verändert werden sollte. struct HPI_INFO {
// Version number (major * 100 + minor) of Hitbase plug-in interface. // Hitbase fills this value so the plug-in can check, whether it supports // the current format. // Hitbase 98 supports only version 1.00 (= 100) // Hitbase displays a warning message when there is a version mismatch in // the major version number with the current version of Hitbase and the plug-in. int nInterfaceVersion; // Version number (major * 100 + minor) of plug-in module (e.g. 100 = 1.00) int nhpiVersion; // Version number of plug-in module (e.g. "0.9 Beta 1") char szhpiVersion[_MAX_HPISHORTNAME_LENGTH]; // Type of plug-in. For possible types see HPIT_... int nType; // Short name of plug-in (e.g. "Spectrum analyzer") char szShortName[_MAX_HPISHORTNAME_LENGTH]; // Full name of plug-in (e.g. "Big 3 Software real-time spectrum analyzer") char szFullName[_MAX_HPIFULLNAME_LENGTH]; // Name of library (e.g. "My own plug-ins" or "xyz Library") char szLibraryName[_MAX_HPIFULLNAME_LENGTH]; // Copyright notice (e.g. "1997 by Big 3 Software") char szCopyright[_MAX_HPIFULLNAME_LENGTH]; // URL of plug-in (e.g. "http://www.big3.de/plug-ins") char szURL[_MAX_HPIFULLNAME_LENGTH]; // Comment (e.g. "How do you like this plug-in? Please send comments or bug-reports to abc@def.com") char szComment[_MAX_COMMENT_LENGTH]; }; Plug-in types #define HPIT_SIGNAL 1 // Plug-in wants to handle normal cd-signal #define HPIT_FREQUENCY 2 // Plug-in wants to handle frequencies of cd-signal BOOL hpiStart(); Diese Funktion wird aufgerufen, bevor das Plug-In gestartet wird. Hier können Sie z.B. Ressourcen allokieren oder sonstige Initialisierungen durchführen.
BOOL hpiEnd(); Diese Funktion wird beim Schließen des Plug-In Fensters aufgerufen. Löschen Sie hier nicht mehr benötigte Ressource und geben Sie allokierten Speicher wieder frei.
BOOL hpiGetParamInfo(int nParam, HPI_PARAM_INFO* pParamInfo); Diese Funktion wird von Hitbase aufgerufen, um abzufragen, welche Parameter Ihr Plug-In benötigt. Sie können beliebig viele Parameter definieren. struct HPI_PARAM_INFO
{
int nType; // Parameter type (see HPIPT_...)
char szName[_MAX_PARAM_LENGTH]; // Name of parameter (field)
int nValue; // Used for HPIPT_INTEGER, HPIPT_BOOLEAN and HPIPT_COLOR
char szValue[_MAX_PARAM_LENGTH]; // Used for HPIPT_STRING
char szDescription[_MAX_COMMENT_LENGTH]; // Description for parameter
};
Benutzerdefinierte Parameter sollten bei HPIP_USER beginnen (also z.B. HPIP_USER+1, HPIP_USER+2, usw.) Folgende Parameter sind vordefiniert: #define HPIP_FREQUENCY 1 #define HPIP_BITSPERSAMPLE 2 #define HPIP_CHANNELS 3 #define HPIP_USER 10 Es gibt folgende Typen von Parametern: #define HPIPT_UNKNOWN 0 // Internal use only #define HPIPT_INTEGER 1 #define HPIPT_STRING 2 #define HPIPT_BOOLEAN 3 #define HPIPT_COLOR 4 BOOL hpiSetParamInfo(int nParam, HPI_PARAM_INFO* pParamInfo); Mit Hilfe dieser Funktion werden fest und benutzer-definierte Parameter gesetzt. Hierüber erhalten Sie z.B. die aktuell eingestellte Abstastfrequenz des CD-Signals von Hitbase. Siehe auch hpiGetParamInfo.
HBITMAP hpiGetBitmap(); Liefern Sie hier eine Bitmap zurück, die im Hitbase Menü neben Ihrem Plug-In erscheinen soll. Wenn Sie keine Bitmap wünschen, so liefern Sie NULL zurück. Die Bitmaps müssen eine Größe von 16x15 Pixel haben.
BOOL hpiDisplaySoundData(HWND hWnd, LPCTSTR pSoundData, DWORD dwCount); Mit dieser Funktion können Sie die Sounddaten in einer eigenen Form in das angegebene Fenster ausgeben. Die Sounddaten sind dabei abhängig von der gewählten Form des Plug-Ins. Der Parameter hWnd ist das Fenster in Hitbase, in welches Sie die Sounddaten ausgeben können. Die Parameter pSoundData enthält abhängig vom definierten Plug-In Typ die aktuellen Sounddaten. dwCount gibt an, wie viele Werte (Zeichen) der Parameter pSoundData enthält. Handelt es sich um ein Signal Plug-In, so enthält der Parameter pSoundData das aktuelle Signal. Die Auflösung ist abhängig von der eingestellten Equalizer-Qualität in Hitbase. Die aktuellen Werte können über die Funktion hpiSetParamInfo abgefragt werden. Handelt es sich um ein Frequenz Plug-In, so enthält der Parameter pSoundData die Anteile von bestimmten Frequenzen im aktuellen Signal. Auch hier ist die Auflösung abhängig von der eingestellten Equalizer-Qualität in Hitbase. Folgende Formel kann zur Bestimmung der Auflösung angewandt werden: Frequenzauflösung = Frequenz / dwCount / 2 Der aktuellen Wert der Frequenz kann über die Funktion hpiSetParamInfo abgefragt werden (nParam = HPIP_FREQUENCY).
Installieren des Hitbase Plug-InsHitbase Plug-Ins müssen die Erweiterung ".hpi" haben und in einem bestimmten Verzeichnis stehen. Kopieren Sie die erzeugte DLL in das Plug-In Verzeichnis von Hitbase, und ändern Sie die Erweiterung von ".dll" nach ".hpi". Starten Sie nun Hitbase und Ihr Plug-In sollte im Menü "Ansicht->Plug-Ins" erscheinen. Herzlichen Glückwunsch!
Beispiel Plug-In (flower.hpi)Hier finden Sie ein (gut) kommentiertes Beispiel Plug-In. Es handelt sich um das "Flower Power" Plug-In welches standardmäßig mit Hitbase ausgeliefert wird.
|