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