mangavalk/lcdproc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update API documentation to match actual declarations and descriptions.

Browse Source
This commit is contained in:
mmdolze
2009-03-21 23:41:14 +00:00
parent e0b1d1a0b3
commit 823a66aa0c
2 changed files with 123 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API-v0.5.txt
+83 -57
View File
@@ -30,7 +30,7 @@ typedef struct lcd_logical_driver {
char *api_version;
// Does this driver require to be in foreground ?
int *stay_in_foreground;// Does this driver require to be in foreground ?
int *stay_in_foreground;
/ Does this driver support multiple instances ?
int *supports_multiple;
@@ -40,9 +40,9 @@ typedef struct lcd_logical_driver {
/*
The programmer should define the following symbols:
char * api_version = API_VERSION; // <-- this symbol is defined by make
int stay_in_foreground = 0; // This driver does not need to be in foreground
int supports_multiple = 0; // This driver does not c$support multiple instances
char * api_version = API_VERSION; // <-- this symbol is defined by make
int stay_in_foreground = 0; // This driver does not need to be in foreground
int supports_multiple = 0; // This driver does not support multiple instances
char *symbol_prefix = "MyDriver_"; // Driver functions start with MyDriver_
And fill these values with the correct values. Upon loading the driver module,
the server will locate these symbols and store pointers to them in the
@@ -69,7 +69,7 @@ API_VERSION in the code.
//// Essential output functions (necessary for output drivers)
// get display width & height (in characters)
// get display width / height (in characters; 1-based)
int (*width) (Driver *drvthis);
int (*height) (Driver *drvthis);
@@ -80,7 +80,7 @@ API_VERSION in the code.
void (*flush) (Driver *drvthis);
// write string s at position (x,y)
void (*string) (Driver *drvthis, int x, int y, char *str);
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);
@@ -105,7 +105,7 @@ API_VERSION in the code.
void (*heartbeat) (Driver *drvthis, int state);
// draw named icon at position (x,y)
void (*icon) (Driver *drvthis, int x, int y, int icon);
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);
@@ -117,10 +117,10 @@ API_VERSION in the code.
// - 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, char ch, unsigned char *dat);
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)
// 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);
@@ -129,13 +129,13 @@ API_VERSION in the code.
//// Hardware functions
// get & set ithe display's contrast
// get / set the display's contrast
int (*get_contrast) (Driver *drvthis);
int (*set_contrast) (Driver *drvthis, int promille);
void (*set_contrast) (Driver *drvthis, int promille);
// get & set brightness for given backlight state
// get / set brightness for given backlight state
int (*get_brightness) (Driver *drvthis, int state);
int (*set_brightness) (Driver *drvthis, int state, int promille);
void (*set_brightness) (Driver *drvthis, int state, int promille);
// set backlight state
void (*backlight) (Driver *drvthis, int state);
@@ -171,22 +171,22 @@ API_VERSION in the code.
// 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
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);
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);
char *(*config_get_string) (char * sectionname, char * keyname,
int skip, char * 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 (char *sectionname);
int config_has_key (char *sectionname, char *keyname);
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*/ );
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
@@ -207,7 +207,7 @@ daemons on one machine. They will then use the same variables !
In the driver's private structure will probably at least be something like:
typedef struct my_driver_private {
typedef struct MyDriver_private_data {
int fd; // file descriptor for the LCD device
int width, height; // dimension of the LCD (in characters, 1-based
int cellwidth, cellheight; // Size of each LCD cell, in pixels
@@ -251,16 +251,19 @@ int (*init) (Driver *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();
// Returns <0 on error.
void (*close) (Driver *drvthis);
// Shuts down the connection with the LCD.
// Called just before unloading the driver.
int (*width) (Driver *drvthis);
// Get the screen width.
// Get the screen width in characters.
// The result is 1-based.
int (*height) (Driver *drvthis);
// Get the screen height.
// Get the screen height in character lines.
// The result is 1-based.
void (*clear) (Driver *drvthis);
// Clears the framebuffer
@@ -268,7 +271,7 @@ void (*clear) (Driver *drvthis);
void (*flush) (Driver *drvthis);
// Flushes the framebuffer to the LCD.
void (*string) (Driver *drvthis, int x, int y, char *str);
void (*string) (Driver *drvthis, int x, int y, const char *str);
// Places a string in the framebuffer
// All coordinates are 1-based, (1,1) is top left.
// Driver should check for overflows
@@ -277,56 +280,79 @@ void (*chr) (Driver *drvthis, int x, int y, char c);
// Places a char in the framebuffer
// Driver should check for overflows
void (*vbar) (Driver *drvthis, int x, int len);
// Draws a vertical bar at horizontal position x and with length len.
void (*vbar) (Driver *drvthis, int x, int y, int len, int promille, int options);
// Draw a vertical bar at position (x,y) that has maximal length len,
// where a fraction of (promille / 1000) is filled.
void (*hbar) (Driver *drvthis, int x, int y, int len);
// Draws a horizontal bar at position x,y and with length len.
void (*hbar) (Driver *drvthis, int x, int y, int len, int promille, int options);
// Draw a horizontal bar at position (x,y) that has maximal length len,
// where a fraction of (promille / 1000) is filled.
void (*num) (Driver *drvthis, int x, int num);
// Displays a big number at horizontal position x.
void (*heartbeat) (Driver *drvthis, int type);
// Sets the heartbeat to the indicated type: 0=off 1=graph1 2=graph2
//HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
//The driver choose how to do it. See MtxOrb.c"
void (*heartbeat) (Driver *drvthis, int state);
// Sets the heartbeat to the indicated state: 0=off, 1=on
// Use HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
// The driver choose how to do it.
void (*icon) (Driver *drvthis, int x, int y, int icon);
int (*icon) (Driver *drvthis, int x, int y, int icon);
// draw named icon at position (x,y)
// If the driver returns -1 the server core will draw
// an appropriate replacement character.
void (*cursor) (Driver *drvthis, int x, int y, int type);
// set cursor type and move it to position (x,y)
int (*get_contrast) (Driver *drvthis);
void (*set_char) (Driver *drvthis, int n, unsigned char *dat);
// 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)
int (*get_free_chars) (Driver *drvthis);
// Get total number of custom characters available.
int (*cellwidth) (Driver *drvthis);
// Return the width of a character cell in pixels.
// The result is 1-based.
int (*cellheight) (Driver *drvthis);
// Return the height of a character cell in pixels.
// The result is 1-based.
int (*get_contrast) (Driver *drvthis);
// Gets the contrast from the driver.
// the value returned is in the ramnge 0 - 1000
// The return value is an integer in the range from 0 to 1000.
// Many displays do not support software setting of contrast.
void (*set_contrast) (Driver *drvthis, int contrast);
// Sets the contrast to the given value. Values should be 0 to 1000.
void (*set_contrast) (Driver *drvthis, int contrast);
// Sets the contrast to the given value, which is an integer in the range
// from 0 to 1000. It is up to the driver to map the logical interval [0, 1000]
// into the interval that the hardware supports.
// Many displays do not support software setting of contrast.
int (*get_brightness) (Driver *drvthis, int state);
int (*get_brightness) (Driver *drvthis, int state);
// Get the brightness for the given backlight state.
// Returned values are in the range from 0 - 1000.
// The return value is an integer in the range from 0 to 1000.
// Many displays do not support software setting of contrast.
void (*set_brightness) (Driver *drvthis, int state, int int brightness);
// Sets the contrast to the given value. Values should be 0 to 1000.
// Many displays do not support software setting of contrast.
// Use -1 to get the current value returned.
void (*set_brightness) (Driver *drvthis, int state, int int brightness);
// Set the brightness for the given backlight state to the value given.
// Value must be an integer in the range from 0 to 1000.
// It is up to the driver to map the logical interval [0, 1000] into the
// interval that the hardware supports.
// Many displays do not support software setting of brightness.
void (*backlight) (Driver *drvthis, int state);
// Sets the backlight to brightness 'on'.
// Sets the backlight to the given brightness state.
// Often hardware can only support on and off, in that case any value
// of on>0 will switch the backlight on.
// of state > 0 will switch the backlight on.
void (*output) (Driver *drvthis, int state);
// 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'.
const char *(*get_key) (Driver *drvthis);
const char *(*get_key) (Driver *drvthis);
// 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.
@@ -335,24 +361,24 @@ const char *(*get_info) (Driver *drvthis);
// Returns a string describing the driver and its features.
char (*config_get_bool) (char * sectionname, char * keyname,
int skip, char default_value);
short (*config_get_bool) (char * sectionname, char * keyname,
int skip, short 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);
long int (*config_get_int) (char * sectionname, char * keyname,
int skip, long 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);
const char *(*config_get_string) (char * sectionname, char * keyname,
int skip, const 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
@@ -361,15 +387,15 @@ char *(*config_get_string) (char * sectionname, char * keyname,
// It is in the address space of the server, and will be freed at the
// next call.
int config_has_section (char *sectionname);
int config_has_section (const 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);
int config_has_key (const char *sectionname, const 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
Corrected and expanded, Peter Marschall 20060411
Sync'd with lcd.h, Markus Dolze, 20090322
docs/lcdproc-dev/driver-api.docbook
+40 -34
View File
@@ -45,7 +45,7 @@ typedef struct lcd_logical_driver {
char *api_version;
// Does this driver require to be in foreground ?
int *stay_in_foreground;// Does this driver require to be in foreground ?
int *stay_in_foreground;
/ Does this driver support multiple instances ?
int *supports_multiple;
@@ -57,7 +57,7 @@ typedef struct lcd_logical_driver {
The programmer should define the following symbols:
char * api_version = API_VERSION; // &lt;-- this symbol is defined by make
int stay_in_foreground = 0; // This driver does not need to be in foreground
int supports_multiple = 0; // This driver does not c$support multiple instances
int supports_multiple = 0; // This driver does not support multiple instances
char *symbol_prefix = "MyDriver_"; // Driver functions start with MyDriver_
And fill these values with the correct values. Upon loading the driver module,
the server will locate these symbols and store pointers to them in the
@@ -95,7 +95,7 @@ API_VERSION in the code.
void (*flush) (Driver *drvthis);
// write string s at position (x,y)
void (*string) (Driver *drvthis, int x, int y, char *str);
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);
@@ -120,7 +120,7 @@ API_VERSION in the code.
void (*heartbeat) (Driver *drvthis, int state);
// draw named icon at position (x,y)
void (*icon) (Driver *drvthis, int x, int y, int icon);
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);
@@ -132,7 +132,7 @@ API_VERSION in the code.
// - 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, char ch, unsigned char *dat);
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)
@@ -146,11 +146,11 @@ API_VERSION in the code.
// get / set the display's contrast
int (*get_contrast) (Driver *drvthis);
int (*set_contrast) (Driver *drvthis, int promille);
void (*set_contrast) (Driver *drvthis, int promille);
// get / set brightness for given backlight state
int (*get_brightness) (Driver *drvthis, int state);
int (*set_brightness) (Driver *drvthis, int state, int promille);
void (*set_brightness) (Driver *drvthis, int state, int promille);
// set backlight state
void (*backlight) (Driver *drvthis, int state);
@@ -186,22 +186,22 @@ API_VERSION in the code.
// 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
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);
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);
char *(*config_get_string) (char * sectionname, char * keyname,
int skip, char * 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 (char *sectionname);
int config_has_key (char *sectionname, char *keyname);
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*/ );
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
@@ -230,7 +230,7 @@ API_VERSION in the code.
</para>
<screen>
typedef struct my_driver_private {
typedef struct MyDriver_private_data {
int fd; // file descriptor for the LCD device
int width, height; // dimension of the LCD (in characters, 1-based
int cellwidth, cellheight; // Size of each LCD cell, in pixels
@@ -291,6 +291,7 @@ typedef struct my_driver_private {
The init() function.
It starts up the LCD, initializes all variables, allocates private data space
and stores the pointer by calling store_private_ptr();
Returns &lt;0 on error.
</para>
<funcsynopsis>
@@ -352,7 +353,7 @@ typedef struct my_driver_private {
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>char *<parameter>str</parameter></paramdef>
<paramdef>const char *<parameter>str</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -435,14 +436,14 @@ typedef struct my_driver_private {
</funcprototype>
</funcsynopsis>
<para>
Sets the heartbeat to the indicated state: 0=off 1=graph1 2=graph2
HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
The driver choose how to do it. See MtxOrb.c
Sets the heartbeat to the indicated state: 0=off, 1=on.
Use HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
The driver choose how to do it.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*icon)</function></funcdef>
<funcdef>int <function>(*icon)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
@@ -452,6 +453,8 @@ typedef struct my_driver_private {
<para>
Draw named icon <replaceable>icon</replaceable> at position
(<replaceable>x</replaceable>,<replaceable>y</replaceable>).
If the driver returns -1 the server core will draw an appropriate replacement
character.
</para>
<funcsynopsis>
@@ -477,8 +480,8 @@ typedef struct my_driver_private {
</funcprototype>
</funcsynopsis>
<para>
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)
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)
</para>
<funcsynopsis>
@@ -488,6 +491,7 @@ The set_char function expects a simple block of data with 1 byte for each pixel-
</funcprototype>
</funcsynopsis>
<para>
Get total number of custom characters available.
</para>
<funcsynopsis>
@@ -547,7 +551,7 @@ The set_char function expects a simple block of data with 1 byte for each pixel-
</funcsynopsis>
<para>
Get the brightness value from the driver for the given backlight state.
The parameter <parameter>state</parameter> determnies which one
The parameter <parameter>state</parameter> determines which one
is returned.
The return value is an integer in the range from 0 to 1000.
Many displays do not support getting or setting brightness using software.
@@ -620,11 +624,11 @@ The set_char function expects a simple block of data with 1 byte for each pixel-
<funcsynopsis>
<funcprototype>
<funcdef>char <function>(*config_get_bool)</function></funcdef>
<funcdef>short <function>(*config_get_bool)</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
<paramdef>char *<parameter>keyname</parameter></paramdef>
<paramdef>int <parameter>skip</parameter></paramdef>
<paramdef>char <parameter>default_value</parameter></paramdef>
<paramdef>short <parameter>default_value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -637,11 +641,11 @@ The set_char function expects a simple block of data with 1 byte for each pixel-
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*config_get_int)</function></funcdef>
<funcdef>long int <function>(*config_get_int)</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
<paramdef>char *<parameter>keyname</parameter></paramdef>
<paramdef>int <parameter>skip</parameter></paramdef>
<paramdef>int <parameter>default_value</parameter></paramdef>
<paramdef>long int <parameter>default_value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -663,11 +667,11 @@ The set_char function expects a simple block of data with 1 byte for each pixel-
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>(*config_get_string)</function></funcdef>
<funcdef>const char *<function>(*config_get_string)</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
<paramdef>char *<parameter>keyname</parameter></paramdef>
<paramdef>int <parameter>skip</parameter></paramdef>
<paramdef>char *<parameter>default</parameter></paramdef>
<paramdef>const char *<parameter>default</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -683,7 +687,7 @@ The set_char function expects a simple block of data with 1 byte for each pixel-
<funcsynopsis>
<funcprototype>
<funcdef>int <function>config_has_section</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
<paramdef>const char *<parameter>sectionname</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -694,8 +698,8 @@ The set_char function expects a simple block of data with 1 byte for each pixel-
<funcsynopsis>
<funcprototype>
<funcdef>int <function>config_has_key</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
<paramdef>char *<parameter>keyname</parameter></paramdef>
<paramdef>const char *<parameter>sectionname</parameter></paramdef>
<paramdef>const char *<parameter>keyname</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -706,6 +710,8 @@ The set_char function expects a simple block of data with 1 byte for each pixel-
<screen>
First version, Joris Robijn, 20011016
Corrected and expanded, Peter Marschall 20060411
Sync'd with lcd.h, Markus Dolze, 20090322
</screen>
</sect1>