Table of Contents
This chapter describes the driver API of v0.5.4 of LCDproc.
The API defines functions which drivers may implement to provide certain services. If a driver implements a function, the function will be detected by the server. For some optional functions the server core provides default implementations.
The API consists of functions to:
print data to the display,
set display properties (backlight, brightness, contrast, extra LEDs),
read input from an input device (may be the display), and
inform the server of the driver/display capabilities.
The API is best descibed by starting with the struct lcd_logical_driver which is defined in server/drivers/lcd.h.
Below is a commented version of lcd_logical_driver. Each function is described more detailed in the section called “Functions in Detail”.
typedef struct lcd_logical_driver { //////// Variables to be provided by the driver module // The driver loader will look for symbols with these names ! // pointer to a string describing the API version char *api_version; // Does this driver require to be in foreground ? int *stay_in_foreground; / Does this driver support multiple instances ? int *supports_multiple; // What should alternatively be prepended to the function names ? char **symbol_prefix; //////// Functions to be provided by the driver module //// Mandatory functions (necessary for all drivers) // initialize driver: returns >= 0 on success int (*init) (Driver *drvthis); // close driver void (*close) (Driver *drvthis); //// Essential output functions (necessary for output drivers) // get display width / height (in characters; 1-based) int (*width) (Driver *drvthis); int (*height) (Driver *drvthis); // clear screen void (*clear) (Driver *drvthis); // flush screen contents to LCD void (*flush) (Driver *drvthis); // write string s at position (x,y) void (*string) (Driver *drvthis, int x, int y, const char *str); // write char c at position (x,y) void (*chr) (Driver *drvthis, int x, int y, char c); //// essential input functions (necessary for input drivers) // get key from driver: returns a string denoting the key pressed const char *(*get_key) (Driver *drvthis); //// Extended output functions (optional; core provides alternatives) // draw a bar from pos (x,y) upward / to the right filling promille of len chars void (*vbar) (Driver *drvthis, int x, int y, int len, int promille, int options); void (*hbar) (Driver *drvthis, int x, int y, int len, int promille, int options); // display (big) number num at horizontal position x void (*num) (Driver *drvthis, int x, int num); // set heartbeat state; animate heartbeat void (*heartbeat) (Driver *drvthis, int state); // draw named icon at position (x,y) int (*icon) (Driver *drvthis, int x, int y, int icon); // set cursor type and move it to position (x,y) void (*cursor) (Driver *drvthis, int x, int y, int type); //// User-defined character functions // set special character / get free characters // - It is currently unclear how this system should work exactly // - The set_char function expects a simple block of data with 1 byte for each pixel-line. // (So that is 8 bytes for a 5x8 char) void (*set_char) (Driver *drvthis, int n, unsigned char *dat); int (*get_free_chars) (Driver *drvthis); // get width / height of a character cell (in pixels) // - necessary to provide info about cell size to clients // - if not defined, the core will provide alternatives returning default values int (*cellwidth) (Driver *drvthis); int (*cellheight) (Driver *drvthis); //// Hardware functions // get / set the display's contrast int (*get_contrast) (Driver *drvthis); void (*set_contrast) (Driver *drvthis, int promille); // get / set brightness for given backlight state int (*get_brightness) (Driver *drvthis, int state); void (*set_brightness) (Driver *drvthis, int state, int promille); // set backlight state void (*backlight) (Driver *drvthis, int state); // set output void (*output) (Driver *drvthis, int state); //// Informational functions // get a string describing the driver and it's features const char * (*get_info) (Driver *drvthis); //////// Variables in server core, available for drivers // name of the driver instance (name of the config file section) // - do not change from the driver; consider it read-only // - to be used to access the driver's own section in the config file char * name; // pointer to the driver instance's private data // - filled by the server by calling store_private_ptr() // - the driver should cast this to it's own private structure pointer void * private_data; //////// Functions in server core, available for drivers // store a pointer to the driver instance's private data int (*store_private_ptr) (struct lcd_logical_driver * driver, void * private_data); // Config file functions, cwprovided by the server // - see configfile.h on how to use these functions // - as sectionname, always use the driver name: drvthis->name short (*config_get_bool) (char * sectionname, char * keyname, int skip, short default_value); long int (*config_get_int) (char * sectionname, char * keyname, int skip, long int default_value); double (*config_get_float) (char * sectionname, char * keyname, int skip, double default_value); const char *(*config_get_string) (char * sectionname, char * keyname, int skip, const char * default_value); // Returns a string in server memory space. // Copy this string. int config_has_section (const char *sectionname); int config_has_key (const char *sectionname, const char *keyname); // error reporting function // - see drivers/report.h for details void (*report) ( const int level, const char *format, .../*args*/ ); // Display properties functions (for drivers that adapt to other loaded drivers) // - the return the size of another already loaded driver // - if no driver is loaded yet, the return values will be 0 int (*get_display_width) (); int (*get_display_height) (); } Driver;