From 1618f3e2edf92668722a098c4a20bf491d4b75a8 Mon Sep 17 00:00:00 2001 From: robijn Date: Tue, 16 Oct 2001 19:38:07 +0000 Subject: [PATCH] Added descriptions of the v0.4 API and the new to-be-created v0.5 API. Request for comments. --- docs/API-v0.4.txt | 157 +++++++++++++++++++++++++++++++++++ docs/API-v0.5.txt | 207 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 364 insertions(+) create mode 100644 docs/API-v0.4.txt create mode 100644 docs/API-v0.5.txt diff --git a/docs/API-v0.4.txt b/docs/API-v0.4.txt new file mode 100644 index 0000000..83ad39d --- /dev/null +++ b/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 + diff --git a/docs/API-v0.5.txt b/docs/API-v0.5.txt new file mode 100644 index 0000000..22b68e1 --- /dev/null +++ b/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 +