Added descriptions of the v0.4 API and the new to-be-created v0.5 API.
Request for comments.
This commit is contained in:
robijn
@@ -0,0 +1,157 @@
|
||||
This document describes the driver API of v0.4 of LCDproc.
|
||||
|
||||
The API consists of several functions to tell the driver that
|
||||
certains actions should be performed, and some data. I consider
|
||||
the data part of the API, because this data is transfered
|
||||
between core and driver.
|
||||
|
||||
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 various variables and functions in this struct are filled by the server
|
||||
with default values and functions. It is then passed to the driver while
|
||||
calling the init function of the driver. The driver can decide to change
|
||||
values and to override functions.
|
||||
|
||||
typedef struct lcd_logical_driver {
|
||||
// Size in cells of the LCD
|
||||
int wid, hgt;
|
||||
// Size of each LCD cell, in pixels
|
||||
int cellwid, cellhgt;
|
||||
// Frame buffer...
|
||||
char *framebuf;
|
||||
|
||||
// Functions which might be the same for all drivers...
|
||||
void (*clear) ();
|
||||
void (*string) (int x, int y, char lcd[]);
|
||||
|
||||
void (*chr) (int x, int y, char c);
|
||||
void (*vbar) (int x, int len);
|
||||
void (*hbar) (int x, int y, int len);
|
||||
void (*init_num) ();
|
||||
void (*num) (int x, int num);
|
||||
|
||||
// Functions which should probably be implemented in each driver...
|
||||
int (*init) (struct lcd_logical_driver * driver, char *args);
|
||||
void (*close) ();
|
||||
void (*flush) ();
|
||||
void (*flush_box) (int lft, int top, int rgt, int bot);
|
||||
int (*contrast) (int contrast);
|
||||
void (*backlight) (int on);
|
||||
void (*output) (int on);
|
||||
void (*set_char) (int n, char *dat);
|
||||
void (*icon) (int which, char dest);
|
||||
void (*init_vbar) ();
|
||||
void (*init_hbar) ();
|
||||
void (*draw_frame) ();
|
||||
|
||||
// Returns 0 for "no key pressed", or (A-Z).
|
||||
char (*getkey) ();
|
||||
|
||||
// more?
|
||||
|
||||
} lcd_logical_driver;
|
||||
|
||||
The various parts are meant for the following:
|
||||
|
||||
1. Several variables
|
||||
These vars are meant to tell the server how many characters wide and high the
|
||||
LCD is, and what size the definable characters are.
|
||||
|
||||
2. Framebuf
|
||||
The framebuffer can be written to by server and client in the 0.4 version.
|
||||
Therefor the framebuffer must always be of the size wid*hgt. It holds the
|
||||
display contents, line after line.
|
||||
|
||||
3. Functions which might be the same for all drivers
|
||||
These functions are usually implemented by server's internal functions that
|
||||
perform standard operations. Placing a char in the framebuffer etc. are
|
||||
all equal in all drivers and therefor are implemented in the server.
|
||||
This behaviour probably changes in v0.5.
|
||||
|
||||
4. Functions which should probably be implemented in each driver
|
||||
These functions are probably different for all drivers.
|
||||
|
||||
|
||||
FUNCTIONS IN DETAIL
|
||||
|
||||
void (*clear) ();
|
||||
// Clears the framebuffer
|
||||
|
||||
void (*string) (int x, int y, char lcd[]);
|
||||
// Places a string in the framebuffer
|
||||
// All coordinates are 1-based, (1,1) is top left.
|
||||
|
||||
void (*chr) (int x, int y, char c);
|
||||
// Places a char in the framebuffer
|
||||
|
||||
void (*vbar) (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) (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 (*init_num) ();
|
||||
// Initializes the big number displaying. A big number should have a width
|
||||
// of 4 characters, and a spacing of 1 character.
|
||||
|
||||
void (*num) (int x, int num);
|
||||
// Displays a big number at position x.
|
||||
|
||||
int (*init) (struct lcd_logical_driver * driver, char *args);
|
||||
// The init function
|
||||
// Starts up the LCD and initializes the struct with correct values and
|
||||
// correct function pointers.
|
||||
|
||||
void (*close) ();
|
||||
// Shuts down the connection with the LCD.
|
||||
|
||||
void (*flush) ();
|
||||
// Flushes the framebuffer to the LCD.
|
||||
|
||||
void (*flush_box) (int lft, int top, int rgt, int bot);
|
||||
// Flushes only a part of the framebuffer to the LCD.
|
||||
// Not called by the server currently.
|
||||
|
||||
int (*contrast) (int contrast);
|
||||
// Sets the contrast to the given value.
|
||||
// Many displays do not support software setting of contrast.
|
||||
|
||||
void (*backlight) (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) (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'.
|
||||
|
||||
void (*set_char) (int n, char *dat);
|
||||
// Define a character
|
||||
|
||||
void (*icon) (int which, char dest);
|
||||
// Define a character to be a standard icon. Is used for the heartbeat.
|
||||
|
||||
void (*init_vbar) ();
|
||||
// Initializes the LCD to display vertical bars
|
||||
|
||||
void (*init_hbar) ();
|
||||
// Initializes the LCD to display horizontal bars
|
||||
|
||||
void (*draw_frame) ();
|
||||
// Unclear function.
|
||||
// Not called by the server currently.
|
||||
|
||||
char (*getkey) ();
|
||||
// Checks if a key has been pressed on the device.
|
||||
// Returns 0 for "no key pressed", or a character for the key.
|
||||
// These characters do not always match the keypad-layout.
|
||||
|
||||
|
||||
First version, Joris Robijn, 20011016
|
||||
|
||||
@@ -0,0 +1,207 @@
|
||||
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
|
||||
driver_init function. For the v0.5 version this should be 50. If it is wrong,
|
||||
the driver will not be loaded. This version number can be found in the define
|
||||
API_VERSION (TODO!!!).
|
||||
|
||||
#define drvthis struct lcd_logical_driver * driver
|
||||
|
||||
typedef struct lcd_logical_driver {
|
||||
|
||||
char * name; // Name of this driver. Filled by server.
|
||||
|
||||
// Basic functions
|
||||
int (*init) (drvthis, char *args);
|
||||
void (*close) (drvthis);
|
||||
int (*wid) (drvthis);
|
||||
int (*hgt) (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 (*init_vbar) (drvthis);
|
||||
void (*vbar) (drvthis, int x, int len);
|
||||
void (*init_hbar) (drvthis);
|
||||
void (*hbar) (drvthis, int x, int y, int len);
|
||||
void (*init_num) (drvthis);
|
||||
void (*num) (drvthis, int x, int num);
|
||||
void (*heartbeat) (drvthis, int state);
|
||||
|
||||
// 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 (*cellwid) (drvthis);
|
||||
//int (*cellhgt) (drvthis);
|
||||
|
||||
// Key functions
|
||||
char *(*getkey) (drvthis);
|
||||
// Returns a string. Server cannot modify
|
||||
// this string.
|
||||
|
||||
// Config file functions, filled by server
|
||||
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()
|
||||
// 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 wid, hgt;
|
||||
// Size of each LCD cell, in pixels
|
||||
int cellwid, cellhgt;
|
||||
// Frame buffer...
|
||||
char *framebuf;
|
||||
};
|
||||
|
||||
|
||||
|
||||
FUNCTIONS IN DETAIL
|
||||
|
||||
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.
|
||||
|
||||
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 (*init_vbar) (drvthis);
|
||||
// Initializes the LCD to display vertical bars
|
||||
|
||||
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 (*init_hbar) (drvthis);
|
||||
// Initializes the LCD to display horizontal bars
|
||||
|
||||
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 (*init_num) (drvthis);
|
||||
// Initializes the big number displaying. A big number should have a width
|
||||
// of 4 characters, and a spacing of 1 character.
|
||||
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user