Update API documentation to match actual declarations and descriptions.

docs/API-v0.5.txt

@@ -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;
@@ -42,7 +42,7 @@ 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
+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,18 +171,18 @@ 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,
+	short (*config_get_bool) (char * sectionname, char * keyname,
-				int skip, char default_value);
+				int skip, short default_value);
-	int (*config_get_int)	(char * sectionname, char * keyname,
+	long int (*config_get_int) (char * sectionname, char * keyname,
-				int skip, int default_value);
+				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,
+	const char *(*config_get_string) (char * sectionname, char * keyname,
-				int skip, char * default_value);
+				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_section	(const char *sectionname);
-	int config_has_key	(char *sectionname, char *keyname);
+	int config_has_key	(const char *sectionname, const char *keyname);
 
 	// error reporting function
 	// - see drivers/report.h for details
@@ -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,49 +280,72 @@ 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);
+void (*vbar)		(Driver *drvthis, int x, int y, int len, int promille, int options);
-// Draws a vertical bar at horizontal position x and with length len.
+// 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);
+void (*hbar)		(Driver *drvthis, int x, int y, int len, int promille, int options);
-// Draws a horizontal bar at position x,y and with length len.
+// 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);
+void (*heartbeat)	(Driver *drvthis, int state);
-// Sets the heartbeat to the indicated type: 0=off 1=graph1 2=graph2
+// Sets the heartbeat to the indicated state: 0=off, 1=on
-//HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
+// Use HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
-//The driver choose how to do it. See MtxOrb.c"
+// 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)
 
+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.
+// 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);
 // 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.
+// Set the brightness for the given backlight state to the value given.
-// Many displays do not support software setting of contrast.
+// Value must be an integer in the range from 0 to 1000.
-// Use -1 to get the current value returned.
+// 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
@@ -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,
+short (*config_get_bool) (char * sectionname, char * keyname,
-			int skip, char default_value);
+			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,
+long int (*config_get_int) (char * sectionname, char * keyname,
-			int skip, int default_value);
+			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,
+const char *(*config_get_string) (char * sectionname, char * keyname,
-			int skip, char * default);
+			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

@@ -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;	// <-- 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,18 +186,18 @@ 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,
+	short (*config_get_bool) (char * sectionname, char * keyname,
-				int skip, char default_value);
+				int skip, short default_value);
-	int (*config_get_int)	(char * sectionname, char * keyname,
+	long int (*config_get_int) (char * sectionname, char * keyname,
-				int skip, int default_value);
+				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,
+	const char *(*config_get_string) (char * sectionname, char * keyname,
-				int skip, char * default_value);
+				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_section	(const char *sectionname);
-	int config_has_key	(char *sectionname, char *keyname);
+	int config_has_key	(const char *sectionname, const char *keyname);
 
 	// error reporting function
 	// - see drivers/report.h for details
@@ -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
+  Sets the heartbeat to the indicated state: 0=off, 1=on.
-  HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
+  Use HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
-  The driver choose how to do it. See MtxOrb.c
+  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>
@@ -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>const char *<parameter>sectionname</parameter></paramdef>
-	<paramdef>char *<parameter>keyname</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>