208 lines
7.2 KiB
Plaintext
208 lines
7.2 KiB
Plaintext
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
|
|
|