Infos Projekt Weiteres

Handbuch - Plugininterface (SDK)

Diese Seite beschreibt das Plugininterface des X10Receiver.NET v2. Um dieses nutzen zu können, müssen Sie in einer .NET-Sprache (z.B. C#) programmieren können. Außerdem sollten Sie mindestens wissen, was Schnittstellen, Delegaten und Vererbung sind.

Da Sie einen Eintrag in der Datenbank brauchen, um eigene Plugins auch benutzen zu können, kontaktieren Sie uns bitte, bevor Sie ein Plugin schreiben.

Plugins

Schnittstellen

Erstellen Sie einen Verweis auf die Datei X10Core.Management.dll. Im Namespace X10Receiver.Core.Interfaces finden Sie die benötigten Schnittstellen.

Ein Plugin informiert die Hauptanwendung darüber, welche Events/Actions/Handler vorhanden sind und gibt Instanzen letzterer Zurück, wenn diese angefragt werden. Außerdem lädt es gespeicherte Elemente. Ein Plugin implementiert mindestens eine der Schnittstellen IInputPlugin, IOutputPlugin und/oder IOutputHandlingPlugin. Alle GetNew...-Funktionen dürfen null zurückgeben, wenn der User den Vorgang abgebrochen hat oder ein Fehler aufgetreten ist.
Die Events/Actions/Handler selbst müssen Ihre entsprechende Aufgabe erledigen und sich selbst speichern können. Sie erben von Input/Output/OutputHandler.

Pluginmanagement

Plugins werden erst geladen, wenn Sie gebraucht werden. Plugins, die IOptionWindow implementieren, bekommen einen Eintrag zum Öffnen des Optionsfensters in der Hauptanwendung. Für Events/Actions/Handler, die IEditable implementieren, wird der Button "Bearbeiten" im Fenster "Definition" aktiviert.

FernbedienungsPlugins

FernbedienungsPlugins brauchen zusätzlich den Verweis auf X10Core.Remotes.dll und implementieren X10Receiver.Core.Remotes.Interfaces.IRemotePlugin. Sie verwalten Elemente/Fernbedienungen, die IRemoteExecuter implementieren. Der Parameter wiz von GetNewRemoteExecuter übergibt einen Wizard, der mit AddAndShowPage() dazu benutzt werden kann, zusätzliche Informationen aufzunehmen. Die übergebene RemoteID muss verwendet werden. Der Delegat delResult wird zur Übergabe des IRemoteExecuter verwendet. Wenn keine Wizard-Seite benötigt wird, kann er direkt aufgerufen werden.
IRemoteExecuter: Wenn die Hauptanwendung die Eigenschaft AlternativeExecuter setzt, muss der Executer alle empfangenen Tastendrucke an diesen Delegat weiterleiten und darf keine Ereignisse mehr auslösen. Dies dient z.B. der Aufnahme der Taste etc., ohne dass Definitionen ausgeführt werden. Die Eigenschaften DownExecuter, HoldExecuter und UpExecuter sind Listen von Zuordnungen von Fernbedienungstasten zu Multicastdelegaten. Wird die entsprechende Taste gedrückt/gehalten/losgelassen, löst der Executer den Delegat aus, wenn er vorhanden ist (Prüfung muss erfolgen). Außerdem sollte dieses Auslösen in einem Try-Catch-Block erfolgen und alle Fehler an X10Receiver.Core.ErrorManagement.HandleException() weitergeben. Die Delegaten der Executer zeigen auf die Execute()-Funktionen aller Definitionen, die die entsprechenden Tasten benötigen.

XML-Format für Definitionslisten

Den Save()-Funktionen von Events/Actions/Handlern wird ein System.Xml.XmlTextWriter übergeben. Die Description-Eigenschaft wurde zu diesem Zeitpunkt bereits als Attribut "Description" gespeichert. Das Plugin kann nun mittels xml.WriteAttributeString("MussManSpeichern", MussManSpeichern.ToString()) weitere Attribute abspeichern. Alle diese Attribute stehen dann in den Load...-Funktionen der Plugins wieder zur Verfügung.

XML-Format für RemoteExecuter

Die Fernbedienung werden in der Settings.xml gespeichert. Die Eigenschaft "RemoteID" wurde beim Aufruf von Save() bereits gespeichert, alles weitere verhält sich wie oben.

Weiteres

X10Receiver.Core.ABHandler

Der ABHandler vereinfacht die Implementierung von OutputHandlern, die nach dem Ja-Nein-Prinzip funktionieren (Programm läuft, oder eben nicht). In GetNewHandler() des Plugins kann der Parameter ABMode mit der Funktion X10Receiver.Core.UI.frmABHandler.GetABMode(descA, descB) ermittelt werden, wobei A und B die beiden möglichen Zustände als Satzanfänge darstellen: "Wenn das Programm X läuft" .... "führe die Actions 1 und 2 aus". descA und descB müssen lokalisiert sein! Ein ABHandler muss in seiner Save()-Funktion das Feld ABMode abspeichern und es in seinem Konstruktur setzen! Beim Rückgabewert von GetABValue() entspricht False dem Wert A, True entspricht B.

X10Receiver.Core.DefinitionManagement

... ermöglicht die Steuerung der aktuellen Definitionsliste. Während CurrentDefinitionList alle Definitionen der geladenen Liste enthält, sind in ActiveDefinitions auch alle zusätzlich geladenen Definitionen (meist der generelle Modus) zu finden.

X10Receiver.Core.ErrorManagement

Neue Threads können ihr Exception-Event an ErrorCatcher() binden. GetLongExString() gibt einen String zurück, wie er ins Logfile geschrieben werden sollte. LogError() schreibt die Exception nur ins Logfile (silent), HandleException zeigt zusätzlich einen Dialog an, der unter anderem die Möglichkeit bietet, das Logfile hochzuladen.

X10Receiver.Core.Functions

Da Programmnamen wie "Winamp" in allen Sprachen gleich sind, kann mit ShowAppNotFoundMsg("Winamp") die Meldung "Winamp wurde nicht gefunden" angezeigt werden, die dann automatisch lokalisiert wird. Einfache OutputPlugins brauchen so keinen Verweis auf X10Core.Localization.dll.

X10Receiver.Core.MessageReceiver

Da der X10Receiver.NET v2 im Normalfall komplett im Hintergrund läuft, stellt der MessageReceiver ein unsichtbares Fenster bereit, das allen Plugins dazu dient, WindowMessages zu empfangen (wenn nötig). Die ChangeTitle-Funktion bitte nicht benutzen. hWnd ist das Handle des Fensters, instance.Text gibt den Titel zurück (Im Normalfall "X10SMInput"), die Klasse ist "WindowsForms10.Window.8.app.0.378734a". Das MessageReceived-Event reicht alle empfangenen Nachrichten weiter. DoInvoke() kann benutzt werden, um auf den DispatcherThread der Hauptanwendung zuzugreifen.
Senden Sie WM_COPYDATA mit SetDefList=Dateiname.x10Rec um eine Definitionsliste zu laden oder mit Execute=Parameter um Program.MainAppEvent auszulösen an den MessageReceiver. Eine Nachricht mit Msg=1587, wParam=11 und lParam=11 zeigt das Hauptfenster an.

X10Receiver.Core.Paths

Stellt wichtige Pfade bereit. Im SettingsFolder werden auch die Definitionslisten gespeichert.

X10Receiver.Core.Program

Bitte diese Klasse nur lesend benutzen. MainAppCall(10) speichert die Einstellungen, 11 nur falls nötig, 12 lädt sie neu aus der Settingsdatei. Language und LanguageID geben Auskunft über die eingestellte Sprache, UpdatePoint über die Programmversion. AutoConfirmation legt fest, ob Actions automatisch ihre Description-Eigenschaft über die InfoAnzeige ausgeben sollen, wenn sie ausgeführt werden. AutoRecognize legt fest, ob Plugins automatisch (bei jedem Ausführen) das Programm neu erkennen sollen (was natürlich Ressourcen kostet). MainAppEvent gibt zum einen alle mit -execute:"parameter" übergebenen Kommandozeilenparameter an die Plugins weiter, kann über den MessageReceiver ausgelöst werden (s.o.). Außerdem können folgende Parameter übergeben werden: "programstart", wenn der Programmstart beendet ist, "programend" bevor das Programm beendet wird, "loaddeflist" wenn eine Definitionsliste geladen wird, "opendeflist" wenn eine Definitionsliste geöffnet wird und "closedeflist" wenn bevor die aktive Definitionsliste geschlossen wird.

X10Receiver.Core.Settings

Mit SetSetting() kann ein String gespeichert werden, mit GetSetting() bzw GetSettingWithDefault() kann er wieder abgerufen werden. Ersteres gibt einen leeren String zurück, wenn er noch nicht existiert, letzteres gibt den DefaultValue zurück und speichert ihn auch ab. MarkSettingsChanged() wird von SetSetting() automatisch aufgerufen.

X10Receiver.Core.Wizard

Seiten von Assistenten erben von WizardPage. Sie sollten ButtonPressed() überschreiben und entsprechend reagieren. Außerdem sollten sie LoadPage() überschreiben und über MyWizard.AvailableButtons festlegen, welche Buttons sie anbieten möchten. Wenn der Wizard größer als Ihre MaximumSize ist, wird die Seite zentriert dargestellt. Ist der Wizard kleiner als die MinimumSize, wird er automatisch vergrößert. Ist die Seite die erste im Assistenten, wird ihre DesiredSize übernommen.
Es gibt zwei Arten von Wizards. Die einen haben eine festgelegte Reihenfolge von Seiten, wobei deren Aufrufreihenfolge von einem Controller gesteuert wird. Alle Pages bekommen einen Verweis auf den Controller und benutzen dessen ShowNextPage() oder ShowPreviousPage(), wenn die entsprechende Taste über ButtonPressed() ausgelöst wird und sie bereit sind, die Seite zu verlassen.
Die andere Art fängt mit einer bestimmten Seite an, die über Wizard.ShowWizard(FirstPage, Title) übergeben wird. Sie ruft über ihre ButtonPressed-Funktion andere Seiten auf, die erst zu diesem Zeitpunkt dynamisch erstellt und mittels AddAndShowPage() angezeigt werden. Wenn die folgende Seite eine Zurück-Funktion anbietet, wäre es möglich, dass sie bereits vorhanden ist. Deshalb sollte vorher DeleteFollowingPages() aufgerufen werden.
In beiden Arten von Wizards wird der Wizard mit CloseWizard() geschlossen, wobei ein Ergebnis übergeben werden kann.

X10Receiver.Core.Management.Info

Dies ist die Infoanzeige. Die Show()-Methoden zeigen Nachrichten an. Der Typeparameter bestimmt die Art der Nachricht. Nur wenn dieser Typ (oder alle übergebenen, mit OR verkettet) in den Einstellungen aktiviert ist, wird die Nachricht auch angezeigt. Der Standard für AutoHide ist True. DirectShow hat den Standard False, kann aber deaktiviert werden, um den Überblend-Effekt verschiedener Nachrichten zu deaktivieren (wenn viele Nachrichten schnell nacheinander angezeigt werden sollen). Dem Parameter IconFile kann entweder ein Dateiname übergeben werden. Die Datei muss dann im Resources-Ordner liegen und wird automatisch heruntergeladen, wenn sie nicht existiert. Alternativ kann ein voller Pfad übergeben werden. Mit IconCount kann die Anzahl der Icons geregelt werden (z.B. um mit Sternen ein Rating darzustellen). Die Icons werden nebeneinander dargestellt und bei dezimalen Werten auch vertikal zugeschnitten. IconsAreDisplayed gibt Auskunft darüber, ob die verwendete Infoanzeige überhaupt in der Lage ist, Icons anzuzeigen. Die entsprechenden Parameter werden ansonsten einfach ignoriert.

X10Receiver.Core.InputBox

Funktioniert wie die von VB6 bekannte InputBox und soll die Aufnahme von Informationen in den GetNew...-Funktionen vereinfachen.

X10Receiver.Core.Update

Neben Funktionen für das normale Update finden Sie hier die Möglichkeit, benötigte Dateien einfach nachzuladen. DownloadNeededFiles() bestimmt anhand eines Dateinamens oder einer Datei-ID alle benötigten Dateien (von denen die gewählte abhängig ist), entfernt diejenigen, die bereits existieren und lädt sie herunter. Die Einsortierung in die Ordner Resources, Plugins oder in den Programmordner werden automatisch vorgenommen. RequireFile() lädt nur eine einzelne Datei herunter, deren Name und Zielordner bekannt sein muss. Alle geben True zurück, wenn der Download erfolgreich war.

X10Receiver.Core.Remotes.clsRemotes

FindButtonInList() gibt die Definition aus einer Definitionsliste zurück, die ein Ereignis mit der angegebenen Fernbedienungstaste enthält. GetButtonToDefinitionMapper() ordnet alle Definitionen auf diese Art den entsprechenden Tasten in einem Dictionary zu. Mit LoadedRemotes.SetAlternativeExecuterToAll() lassen sich alle eingehenden Ereignisse abfangen, mit RemoveAlternativeExecuterFromAll() wird der Hook wieder entfernt.

X10Receiver.Localization

Dieser Namespace enthält mehrere statische Klassen, die übersetzte Strings bereithalten. Der Inhalt dieser Variablen ändert sich, wenn der User die Sprache ändert. Die Klasse Language informiert über die aktuell verwendete und alle verfügbaren Sprachen.