Chapter 5. The LCDproc driver API

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:

The API is best described 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);

	// draw a progressbar covering lenght chars at pos (x,y) showing promille% progress
	void (*pbar)		(Driver *drvthis, int x, int y, int len, int promille);

	// 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);

	// 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;