Information Project Miscellaneous

User Manual - Plugin Interface (SDK)

This page describes the plugin interface of X10Receiver.NET v2. To be able to use the interface, you need to develop your plugin in a .NET language (C# for example). Furthermore, you should know about interfaces, delegates and inheritance.

As you will need an entry in our database to make your own plugin, please contact us before writing a plugin.



Set a reference to the file X10Core.Management.dll. In the namespace X10Receiver.Core.Interfaces you will find most of the necessary interfaces.

A plugin gives information to the main application about its events/actions/handlers and returns instances of those, if they are requested. Also, a plugin loads those elements. A plugin implements at least one of those interfaces: IInputplugin, IOutputplugin and/or IOutputHandlingPlugin. All GetNew...() functions may return null if the user cancelled the operation or if an error occured.
The events/actions/handlers themselves need to do their work and need to be able to save themselves. They inherit from Input/Output/OutputHandler.


Plugins are not loaded until they are needed. Plugins, that implement IOptionWindow, will get an item in the "Settings" tab of the main window. For events/actions/handlers that implement IEditable, the edit buttons in the window "Edit definition" will be enabled. The static class PluginManagement in X10Receiver.Core offers

Remote Control Plugins

Remote control plugins additionally need a reference to X10Core.Remotes.dll and need to implement X10Receiver.Core.Remotes.Interfaces.IRemotePlugin. These plugins manage items that implement IRemoteExecuter. The parameter wiz in GetNewRemoteExecuter passes a Wizard object, that can used to display additional pages to get more information from the user, by calling wiz.AddAndShowPage(). The RemoteID passed in GetNewRemoteExecuter has to be used for the new remote. The delegate delResult is used to pass the result to the main application. If no wizard page is needed, the delegate can be called immediately.
IRemoteExecuter: If the main application has set the property AlternativeExecuter, the remote executer has to pass all keypresses that it receives to this delegate and must not raise any events anymore. This is used to record keypresses without accidently executing definitions. The properties DownExecuter, HoldExecuter and UpExecuter are dictionaries that assign a multicast delegate to each button on the remote. If the corresponding button is pressed/held/released, the IRemoteExecuter raises the delegate, if it exists (you will need to check that first). Furthermore, this delegates should only be called form inside a try-catch-struct and all exceptions can be passed to X10Receiver.Core.ErrorManagement.HandleException(). The delegates usually point to the Execute() functions of all definitions, that need the button.

XML Format for Definition Lists

A System.Xml.XmlTextWrite is passed to all Save() functions of all events/actions/handlers. At this point, the Description property has already been saved as an attribute called "Description". The plugin can now save more attributes using xml.WriteAttributeString("Name", Value.ToString). All those attributes will be available in the Load... functions of the plugin by calling xml.GetAttribute("Name").

XML Format for Remote Executers/p>

Remote Executers are saved to the Settings.xml file. When Save() is called, the RemoteID has already been saved, all the rest equals the format for definition list.



The ABHandler class simplifies the implementation of output handlers, that work with the Yes-No principle (like "App is running" or "It's not"). In GetNewHandler(), the parameter ABMode can be determined with X10Receiver.Core.UI.frmABHandler.GetABMode(descA, descB), where descA and descB represent the two states of the handler as parts of a sentence like this: "If winamp.exe is running" ... and the main app will add ... " execute actions 1 and 2.". descA and descB need to be localized! An ABHandler needs to save the ABMode in the Save() function, read it from the XML file in its constructor and set it to the base class field. In GetABValue(), returning False equals A, returning True means B.


... enables you to view/edit the current definition list. While CurrentDefinitionList contains all definitions of the active definition list, ActiveDefinitions additionally contains definitions, that have been loaded later (mostly the general mode).


New threads can bind their Exception event to ErrorCatcher(). GetLongExString() returns a formatted string, that can be written to the log file. LogError() only prints the exception to the log file (silent), HandleException() also shows a dialog, that among other things offers the possibility to upload the log file.


As application names like "Winamp" are the same in all languages, a message like "Winamp was not found" can be displayed by calling ShowAppNotFoundMsg("Winamp"), where the message will be localized. This way, OutputPlugins do not need to reference X10Core.Localization.dll.


As X10Receiver.NET v2 is designed to run in background mode, the MesssageReceiver class provides an invisible window, that offers all plugins the possibility to receive window messages (if necessary). Please do not use the ChangeTitle() function. hWnd returns the handle of the window, instance.Text returns its title (this is usually "X10SMInput"), its class is "". The MessageReceived event passes all messages to the plugins. DoInvoke() can be used to access the dispatcher thread of the main application.
Send WM_COPYDATA with the parameter SetDefList=Filename.x10Rec to the MessageReceiver to load a definition list. Send Execute=Parameter to raise Program.MainAppEvent. A Message with Msg=1587, wParam=11 and lParam=11 shows the main window.


Provides the most important folder paths. Definition lists are saved in the SettingsFolder.


Please do only read from this class and do not set its properties to different values. MainAppCall(10) saves the settings, 11 does the same, but only if it's necessary, 12 reloads them from the file. Language and LanguageID return the current language, UpdatePoint contains the version number behind the point (v2.XXX). AutoConfirmation defines, whether actions shall automatically display their Description property through Info.Show() when they are executed. AutoRecognize defines, whether plugins shall automatically recognize the application they control every time they execute an action (which consumes CPU). MainAppEvent on the one hand passes all command line parameters (-execute:"parameter") to the plugins and can also be raised by the MessageReceiver (see above). Also, it can be raised with the following parameters: "programstart" when X10Receiver.NET is completely started, "programend" before it is closed, "loaddeflist" after a definition list was loaded, "opendeflist" after it was opened and "closedeflist" before it is closed.


SetSetting(), GetSetting() and GetSettingWithDefault() allow to save strings that are still available after the program was restarted. GetSetting() returns "" if the setting didn't exist, GetSettingWithDefault() returns the DefaultValue parameter and also saves it. MarkSettingsChanged() is always called by SetSetting().


Pages in wizards inherit from WizardPage. They should override ButtonPressed() and react when it is called. Also, they should override LoadPage() and set MyWizard.AvailableButtons to tell the wizard, which buttons they offer. If the wizard window is bigger than the page's MaximumSize, the page is displayed in the center. If the wizard window is smaller than the page's MinimumSize, the window will be resized. If the page is the first page of the wizard, the DesiredSize property will be considered.
There are two types of wizards. One type has a pre-defined order of pages and are controlled by a WizardController. All pages receive a reference to the controller in their constructor and use its ShowNextPage() or ShowPreviousPage() functions, if they have been passed the corresponding button through ButtonPressed() and if they are ready to leave.
The other type continues with a page, that is passed to Wizard.ShowWizard(FirstPage, Title). In its ButtonPressed() function, the page can open other pages, that are dynamically created at this point and displayed by calling AddAndShowPage(). If the following page offers a Back button, it is possible, that the following page already exists, so it makes sense to call DeleteFollowingPages() first.
In both cases, the wizard can be closed with CloseWizard() and a result can be passed.


This is the message part of the OSD. The Show() functions display messages. The paramter Type specifies the type of the message. Only if this type (or all of them, if you pass multiple OR-ed types) is activated in the "Settings" tab, the message will be displayed. The default value for AutoHide is True, for DirectShow it is False. Setting DirectShow to True disables the fading effect and is useful for displaying a large number of messages in a short time. You can pass a full path or a file name to the parameter IconFile. If you pass a file name, it will be searched in the Resource folder and, if it does not exist there, on the server. IconCount allows you to specify the number of icons to be displayed, you can also pass floating point numbers (this is useful to for example display a rating with stars). IconsAreDisplayed informs you, if the OSD plugin, that is in use, is able to display icons. If it's not, the parameters are ignored.


Works like the InputBox of Visual Basic 6 and is meant to simplify the information collection in the GetNew... functions.


Besides all functions for the normal updating process, this static class contains functions to load files from the server. You can pass either a file name or a file ID to DownloadNeededFiles() and the function will then load a list of all other files, that the one is dependant on and then downloads the files. The files are automatically stored to either the Program, Resource or Plugins folder. RequireFile() only downloads single files and needs to be passed the file name and the destination folder. All functions return True, if the download was successfully completed.


FindButtonInList() returns the first function from a definition list, that contains an event with the specified remote control button. GetButtonToDefinitionMapper() sorts all definition list to a dictionary with the remote buttons as the key. LoadedRemotes.SetAlternativeExecuterToAll() allows you to hook all remotes, RemoteAlternativeExecuterFromAll() remotes the hook.


This namespace contains several static classes, that contain localized strings. The content of these string variables changes, when the user changes the language. The class Language contains information about the currently used language and about all the others, too.