Added descriptions of the v0.4 API and the new to-be-created v0.5 API.

Request for comments.

docs/API-v0.4.txt

@@ -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
+

docs/API-v0.5.txt

@@ -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
+