Hitbase

Plug-In Interface

Dieses 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
2. Beschreibung der Funktionen
3. Installieren des Hitbase Plug-Ins
4. Beispiel Plug-In (flower.hpi)

Anlegen eines Hitbase Plug-Ins

1. Starten Sie Microsoft Visual C++ 5.0.
2. Wählen Sie im Menü "File" den Befehl "Neu...".
3. Wählen Sie "MFC AppWizard (dll)". Geben Sie dem Plug-In einen Namen und tragen Sie ihn in das Feld "project name" ein. Klicken Sie auf OK.
4. Im nächsten Fenster wählen Sie "Regular DLL using shared MFC DLL", klicken Sie auf "Finish" und OK.

Sie haben nun das Grundgerüst zur Erstellung eines Hitbase Plug-Ins angelegt. Im folgenden müssen Sie nun alle Funktionen des Interfaces implementieren. Im folgenden Abschnitt werden diese Funktionen beschrieben.

Beschreibung der Funktionen

Alle 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-Ins

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

flower.zip (10 KB)