Professional Documents
Culture Documents
á
Driver::Setup()
Driver::Shutdown()
Driver::Main()
Driver::SendData()
á
0
!
This document describes the process for creating new plugin drivers.
It assumes you are familiar with C++, class inheritance, and thread
programming.
/usr/local/src/player/examples/plugins/exampledriver/
$ make
$ player ./example.cfg
The driver block in the config file has an additional field @c plugin
specifying the path to the plugin, i.e.,:
driver
(
name "exampledriver"
plugin "exampledriver.so"
provides ["position:0"]
...
)
To create a new driver, you should create a new class for the driver,
which should inherit from the Driver class. This base class defines a
standard API, part of which the new driver must implement (other parts
it may choose to override). We now describe the salient aspects of
the Driver class.
This constructor will establish the buffers and queues that allow the
Player server to interface with the driver. The preamble for the
example driver, for example, looks like this:
This might be the serial port from which to read data, for example.
See the ConfigFile documentation for the various kinds of options that
can be read from the configuration file.
Note that the ordering is important here: we must shut down the driver
thread @b before we release the resources it is using; to this end,
Driver::StopThread() will tell the driver thread to quit, and wait
until it exits before returning.
Note that your driver must respond, one way or another, to each and
every request. Failing to respond to requests will cause client
programs to "hang" when talking to the driver.
Note that this function may be called multiple times: once for each
occurance of the driver name in the configuration file.
Each driver must register itself with the server using the
DriverTable::AddDriver(), providing the driver name and factory
function. Drivers must therefore define a registration function
as follows:
extern "C"
{
int player_driver_init(DriverTable* table)
{
ExampleDriver_Register(table);
return 0;
}
}
This function will be called when the shared object is loaded, before
any drivers are instantiated. The @c extern @c "C" block is used to
prevent C++ name mangling of the intialization function.
While the above method will probably work, it is recommended that you
use pkg-config to get the compile flags; i.e.,
$ g++ -Wall -g3 `pkg-config --cflags player` -c exampledriver.cc
$ g++ -shared -nostartfiles -o exampledriver.so exampledriver.o
@todo
- Add example of building plugin using libtool.
- Add "theory" from Architecture Chapter of the old manual.
*/
Y