Plugin Information
From
This page will contain any information related to writing your own plugins.
Contents |
Core Message System
The core is the central message router where all the communication between plugins happens. It is also responsible for accepting transmitted events, and repeating it out to all subscribed plugins. Core has its own set of features as well.
IPC Message
Messages sent between plugins and the core are known as IPC Messages or Inter-Process Communication Messages. The name is not entirely accurate, as all plugins reside within the same process, but the structure is easily ported to allow for networked or even between process communication.
IPCMessages are how plugins communicate with each other, as well as the Core. Message format is as follows
target:class method !arg1! !arg2! ... !argN!
- target - the name of the plugin that the message needs to be sent to.
- class - the subsection or class of the plugin the message pertains to
- method - a specific function the message is supposed to perform within the class.
- argN - These are variables or arguments that are passed to the target for the method. Arguments must be enclosed in exclamation points (!) and must follow the same naming rules as class and method names.
Valid characters for use in the class and method are 0-9 a-z A-Z (No spaces). You can also use the characters @#$%^&*_- but it is greatly discouraged. Example: "MediaLibrary:media play !1!". MediaLibrary is the target plugin, media is the class, and play is the method. This method has a single argument, which is the index of the song to be played, and is surrounded by ! characters. (TODO: This NEEDS to change, since ! is a valid file name in some operating systems)
Using Messages
Plugin have to subclass an BaseInterface. This provides a few virtual functions that can be overridden to allow passing messages between a plugin, and the core.
passCoreMessage(String,IPCMessage)
This is a function that is called from within a plugin, to pass a message to the core.
passPluginMessage(String,IPCMessage)
This function has to be overridden within a plugin to allow for the plugin to accept messages from the core and other plugins.
Events
Events are messages that are sent by plugins to the core, and core retransmits these events to any plugin that subscribes to it. Events are text named, and should generally follow the format: event:pluginname_eventname. Example: event:mediaengine_mediastatechange. Events are case sensitive, and can contain arguments just as normal messages.
Throwing An Event
Events can be thrown by plugins as an IPCMessage in the format
core:event throw !eventname! !arg0! ... !argN!
. Events can have as many arguments (argN) as needed. (Up to a couple hundred)
This event will be passed to any plugins which have subscribed to receive the event.
Subscribing To An Event
To subscribe to an event, a plugin should pass an IPCMessage to the core as follows:
core:event subscribe !eventname!
The plugin will then receive any event eventname that has been thrown
