236 lines
8.6 KiB
Plaintext
236 lines
8.6 KiB
Plaintext
DG: David GLAUDE as added a few comment for discussing this document.
|
|
|
|
This document describes the driver API of v0.5 of LCDproc.
|
|
At time of this writing, this version is not released and some things might
|
|
be changed.
|
|
|
|
The API consists of several functions to tell the driver that
|
|
certains actions should be performed, some data, and several functions
|
|
to retrieve configuration data from the server.
|
|
|
|
OVERVIEW OF OPERATION
|
|
|
|
The API is best descibed by starting with the struct lcd_logical_driver
|
|
which is defined in server/drivers/lcd.h.
|
|
|
|
The use of the API has changed from v0.4 to v0.5. The default functions that
|
|
the server put in the pointers in v0.4 do no longer exist. Instead empty
|
|
functions are the default. If a driver implements a function, the function
|
|
will be detected by the server. The driver should at least implement all
|
|
basic functions like driver_chr and driver_str itself.
|
|
|
|
Because the drivers are loadable, some kind of version checking should be done.
|
|
Therefor the server expects the correct version number to be returned from the
|
|
version function. For the v0.5 version this should be "0.5". If it is wrong,
|
|
the driver will not be loaded. This version number can be found in the define
|
|
API_VERSION.
|
|
|
|
#define drvthis struct lcd_logical_driver * driver
|
|
DG: This is very C++ and it is meaningfull in C++ to have
|
|
DG: DATA + FUNCTION in the "this" because we have polymorph
|
|
DG: and heritage. But in our case we only need private data
|
|
DG: in order to support multiple instances.
|
|
DG: Or do we want the driver to provide different function
|
|
DG: based on the detected hardware (or something like that)?
|
|
DG: Except for init and close, I don't see why we don't give
|
|
DG: the private data rather than drvthis???
|
|
DG: Please explain (again).
|
|
|
|
typedef struct lcd_logical_driver {
|
|
|
|
char * name; // Name of this driver. Filled by server.
|
|
|
|
// Basic functions
|
|
char *(*version); // OR CAN WE RETRIEVE A STRING FROM THE MODULE
|
|
int (*init) (drvthis, char *args);
|
|
void (*close) (drvthis);
|
|
int (*width) (drvthis);
|
|
int (*height) (drvthis);
|
|
void (*clear) (drvthis);
|
|
void (*flush) (drvthis);
|
|
void (*string) (drvthis, int x, int y, char *str);
|
|
void (*chr) (drvthis, int x, int y, char c);
|
|
|
|
// Extended functions
|
|
void (*vbar) (drvthis, int x, int y, int len, int promille, int pattern);
|
|
void (*hbar) (drvthis, int x, int y, int len, int promille, int pattern);
|
|
void (*num) (drvthis, int x, int num);
|
|
void (*heartbeat) (drvthis, int state);
|
|
char (*set_icon) (drvthis, int icon);
|
|
DG: I don't like this function...
|
|
DG: I would prefer the following definition (like chr)
|
|
DG: void (*set_icon) (drvthis, int x, int y, int icon);
|
|
|
|
// Hardware functions
|
|
int (*contrast) (drvthis, int contrast);
|
|
void (*backlight) (drvthis, int on);
|
|
void (*output) (drvthis, int on);
|
|
|
|
// Userdef characters, are those still supported ?
|
|
//void (*set_char) (drvthis, int n, char *dat);
|
|
//int (*cellwidth) (drvthis);
|
|
//int (*cellheight) (drvthis);
|
|
|
|
// Key functions
|
|
char *(*get_key) (drvthis);
|
|
// Returns a string. Server cannot modify
|
|
// this string.
|
|
|
|
// Config file functions, filled by server
|
|
// DO THESE NEED TO BE IN THIS STRUCTURE ?
|
|
// LOADABLE MODULES CAN CALL FUNCS IN THE MAIN MODULE ...
|
|
char (*config_get_bool) (char * sectionname, char * keyname,
|
|
int skip, char default_value);
|
|
int (*config_get_int) (char * sectionname, char * keyname,
|
|
int skip, int default_value);
|
|
double (*config_get_float) (char * sectionname, char * keyname,
|
|
int skip, double default_value);
|
|
char *(*config_get_string) (char * sectionname, char * keyname,
|
|
int skip, char * default);
|
|
// Returns a string in server memory space.
|
|
// Copy this string.
|
|
int config_has_section (char *sectionname);
|
|
int config_has_key (char *sectionname, char *keyname);
|
|
|
|
// Driver private data
|
|
int (*store_private_ptr) (void * private_data);
|
|
void * private_data; // Filled by server by calling store_private_ptr()
|
|
DG: I think it is the driver that should take care of using the right
|
|
DG: private data.
|
|
DG: The server need to remember two thing about a driver,
|
|
DG: 1) The drvthis wich contain what function to call and is a well define
|
|
DG: structure that we get at init time.
|
|
DG: drvthis should be the same for every instances of the driver.
|
|
DG: 2) private_data wich we remember and receave as a pointer to a black box
|
|
DG: and we give it back to the driver in EVERY call.
|
|
DG:
|
|
DG: Implicitly the driver knows about wich function is what...
|
|
DG: But the driver need to know only wich instance is currently "active".
|
|
DG:
|
|
DG: It does not change much, but we don't need store_private_ptr anymore.
|
|
|
|
// Driver should cast this to it's own
|
|
// private structure pointer
|
|
|
|
} lcd_logical_driver;
|
|
|
|
The flush_box and draw_frame functions have been removed for v0.5.
|
|
In the private structure will probably at least be:
|
|
|
|
typedef struct my_driver_private {
|
|
|
|
// Size in cells of the LCD
|
|
int width, height;
|
|
// Size of each LCD cell, in pixels
|
|
int cellwidth, cellheight;
|
|
// Frame buffer...
|
|
char *framebuf;
|
|
};
|
|
|
|
|
|
|
|
FUNCTIONS IN DETAIL
|
|
|
|
char *(*version);
|
|
// Return the API version string as the driver knows it.
|
|
|
|
int (*init) (drvthis, char *args);
|
|
// The init function
|
|
// Starts up the LCD, initializes all vars. Allocates private data space
|
|
// and stores the pointer by calling store_private_ptr();
|
|
// The init function should return the correct version number.
|
|
|
|
void (*close) (drvthis);
|
|
// Shuts down the connection with the LCD.
|
|
|
|
int (*width) (drvthis);
|
|
// Get the screen width.
|
|
|
|
int (*height) (drvthis);
|
|
// Get the screen height.
|
|
|
|
void (*clear) (drvthis);
|
|
// Clears the framebuffer
|
|
|
|
void (*flush) (drvthis);
|
|
// Flushes the framebuffer to the LCD.
|
|
|
|
void (*string) (drvthis, int x, int y, char *str);
|
|
// Places a string in the framebuffer
|
|
// All coordinates are 1-based, (1,1) is top left.
|
|
|
|
void (*chr) (drvthis, int x, int y, char c);
|
|
// Places a char in the framebuffer
|
|
|
|
void (*vbar) (drvthis, int x, int len);
|
|
// Draws a vertical bar at horizontal position x and with length len.
|
|
// init_vbar will be called once before this functions.
|
|
|
|
void (*hbar) (drvthis, int x, int y, int len);
|
|
// Draws a horizontal bar at position x,y and with length len.
|
|
// init_hbar will be called once before this functions.
|
|
|
|
void (*num) (drvthis, int x, int num);
|
|
// Displays a big number at position x.
|
|
|
|
void (*heartbeat) (drvthis, int state);
|
|
// Sets the heartbeat to the indicated state.
|
|
// 0=off 1=graph1 2=graph2
|
|
|
|
int (*contrast) (drvthis, int contrast);
|
|
// Sets the contrast to the given value.
|
|
// Many displays do not support software setting of contrast.
|
|
|
|
void (*backlight) (drvthis, int on);
|
|
// Sets the backlight to brightness 'on'.
|
|
// Often hardware can only support on and off, in that case any value
|
|
// of on>0 will switch the backlight on.
|
|
|
|
void (*output) (drvthis, int on);
|
|
// Sets the output value. Some displays/wirings have a general purpose
|
|
// output, which can be controlled by calling this function. See the
|
|
// 'output' command in the 'widget language'.
|
|
|
|
char *(*getkey) ();
|
|
// Checks if a key has been pressed on the device.
|
|
// Returns NULL for "no key pressed", or a string describing the pressd key.
|
|
// These characters should match the keypad-layout.
|
|
|
|
char (*config_get_bool) (char * sectionname, char * keyname,
|
|
int skip, char default_value);
|
|
// Call to server. Retrieve a bool from the config file.
|
|
// Sectionname should be the name of the driver (as in the struct).
|
|
// If the key cannot be found, the default value will be returned.
|
|
// skip should be 0 usually, but if you want to retrieve multiple
|
|
// identical keys, then increase skip to get every next value.
|
|
|
|
int (*config_get_int) (char * sectionname, char * keyname,
|
|
int skip, int default_value);
|
|
// Call to server. Retrieve an integer from the config file.
|
|
|
|
double (*config_get_float) (char * sectionname, char * keyname,
|
|
int skip, double default_value);
|
|
// Call to server. Retrieve a float from the config file.
|
|
|
|
char *(*config_get_string) (char * sectionname, char * keyname,
|
|
int skip, char * default);
|
|
// Call to server. Retrieve a string from the config file.
|
|
// Fill result with a pointer to some available space. You can fill it
|
|
// with a default value. If the key is found, it will be overwritten
|
|
// with the value from the key.
|
|
// Note that you should always first copy the the returned string.
|
|
// It is in the address space of the server, and will be freed at the
|
|
// next call.
|
|
|
|
int config_has_section (char *sectionname);
|
|
// Returns wether a section exists. Does not need to be called prior
|
|
// to a call to a config_get_* function.
|
|
|
|
int config_has_key (char *sectionname, char *keyname);
|
|
// Returns the number of times a key exists. Does not need to be called
|
|
// prior to a call to a config_get_* function.
|
|
|
|
|
|
First version, Joris Robijn, 20011016
|
|
|