Writing plugins
From Mms-wiki
This document will guide you through writing plugins for the next major release of mmsv2. The new plugin architecture has made it very easy to extend mms with whatever you want it to do.
There are five different plugins types:
- Input
- Output
- Features
- Audio player
- Movie player
- Printer
Please be sure to read the plugin first before reading about the specific plugin types as this will contain crucial information about writing plugins.
Contents |
[edit] Plugin
Common for all plugins is that you need to create your own directory in the correct place (a correct place for a feature plugin is inside the feature directory) and create the following 3 files: name.hpp, name.cpp and name_plugin.cpp. name.[ch]pp will contain the class for the new plugin. It will always have to inherit from some other class.
Please don't be shy to use the other plugins of the same type as examples.
[edit] Input
Input plugins live in the plugins/input directory. Currently there are 3 input plugins: keyboard, evdev and lirc.
You should start by creating a class which inherits from InputDevice (you can find this class in input.hpp) or from Remote if you are writing a new remote plugin (like lirc). You need to implement the virtual functions if you inherit from Remote:
- virtual void suspend() = 0;
- virtual void wake_up() = 0;
- virtual bool init() = 0;
- virtual void run() = 0;
and the extra functions:
- virtual void generate_search_top() = 0;
- virtual void generate_search_input(std::string& str, Input input) = 0;
- virtual void search_top() = 0;
- virtual void search_input(std::string& str, Input input, int& offset, GenSearchBaseFunc *func) = 0;
if you are writing a whole new input device type. You can look in keyboard and remote for examples of how to define these.
Furthermore it would be a good idea to provide example input configuration files for a device. These examples are placed in cfg/input/[input_plugin_name].
[edit] Output
Output plugins live in the plugins/output directory. Currently there are 3 output plugins: sdl, vgagl and the mpeg triplings dxr3, dvb and mpegout.
To write a new output plugin you will need to inherit from RenderDevice (placed in plugins/output/render_device.hpp). You will need to implement the following functions to create a new output plugin:
- virtual void redraw() = 0;
- virtual void init() = 0;
- virtual void deinit() = 0;
- virtual void run() = 0;
[edit] Features
Feature plugins live in the plugins/feature directory. Currently there are 4 major feature plugins: Audio, Movie, Pictures and EPG.
To write a new plugin you will need to inherit from Module. (placed in plugins/feature/module.hpp). You will need to implement the following functions to create a new feature plugin:
- virtual Options *get_opts() = 0;
- virtual bool init();
- virtual void startup_updater() = 0;
- virtual void begin_external() {};
- virtual void end_external() {};
- virtual std::string mainloop() = 0;
The {begin, end}_external functions must only be implemented if an external program might use the same ressources as the plugin is currently using. Such as audio using the audio device that the movie player also will need. So when an external command is called (using the run::my_system) all feature plugins begin_external functions will be called and after returning end_external will be called.
The get_opts should return the Options for the feature plugin. The options should be inherited from Options (options.hpp). This will also take care of building the global options.
init() is called when the plugin is loaded and startup_updater is called the first time mms is started. The startup_updater is used for added things to the global updater queue. The updater queue is a way to run things at certain points in time such as automaticly updating the epg TV.xml file when mms is idle.
mainloop is the primary point of entry from the startmenu. Although one can define as many entry points as one wants.
The name_plugin.cpp file for feature plugin are much more exciting than for other modules. It is in this file that the different entry points are defined and what code should be excecuted before and after the entry points.
To define special keys one just needs to create a special input file in cfg/input/[input_plugin]/plugin with the special keys. Then one can parse this input file by calling parse_keys([plugin], [version]). This should create a new keyboard mapping with all the new keys defined together with all the default keys. One can change to this new input mode using set_map().
Features should define their own configuration information in a [plugin]_config_parameters file. Then the plugin should define their own configuration file using a [plugin]_config.hpp file which should take care of creating a [Plugin]Config class with all the configuration options.
For drawing stuff to the screen mms provides several graphics primitives: picture, text and rectangles. Please look in the other plugins on how to draw things to the screen and how to synchonize between the input and output.
The procedure for registering with the global search functionality is still to early to be clearly defined. But this is a feature that feature plugins will be able to use to provide global searching in all modules.
Registering console options in a plugin is still not defined.
[edit] Audio Player
Audio player plugins live in the plugins/audio/players directory. Currently there are 3 audio player plugins: alsaplayer, xine and gstreamer.
To write a new audio player plugin you will need to inherit from AudioPlayer (placed in plugins/audio_player.hpp). You will need to implement the following functions to create a new audio player plugin:
- virtual int is_playing() = 0;
- virtual int is_buffering() = 0;
- virtual int is_mute() = 0;
- virtual void gather_info() = 0;
- virtual void addfile(const Simplefile &file) = 0;
- virtual void play() = 0;
- virtual void stop_player() = 0;
- virtual void pause() = 0;
- virtual void ff() = 0;
- virtual void fb() = 0;
- virtual int getpos()=0;
- virtual void setpos(int p)=0;
- virtual void mute() = 0;
- virtual void volup() = 0;
- virtual void voldown() = 0;
- virtual int getvol()=0;
- virtual void update_cdrom(const std::string& cdrom) = 0;
- virtual void collect_info(const std::string& filename) = 0;
- virtual void release_device() = 0;
- virtual void restore_device() = 0;
Most of these are pretty self-explainatory. addfile should add the file to the player and begin playing. Please be aware that one will need to set two states (pause and playing) on the audio state object.
[edit] Movie Player
Movie player plugins live in the plugins/movie/players directory. Currently there are 3 movie player plugins: mplayer, xine, dxr3player.
To write a new movie player plugin you will need to inherit from MoviePlayer (placed in plugins/movie_player.hpp). You will need to implement the following functions based on the features of the movie player to create a new movie player plugin:
- virtual void play_movie(const std::string& paths) = 0;
- virtual void play_disc(const std::string& play_cmd) = 0;
- virtual void play_vcd(const std::string& device) = 0;
- virtual void play_dvd(const std::string& device) = 0;
One registers the movie players capabilities by calling the inherited Movie Players constructor with different values.
[edit] Printer Plugin
This is still too early to write anything conclusive about this plugin type.
