include/liblpfk.h

Tue, 26 Aug 2008 12:45:33 +0100

author
Philip Pemberton <philpem@philpem.me.uk>
date
Tue, 26 Aug 2008 12:45:33 +0100
changeset 0
745037d69d81
child 1
3e775df109e6
permissions
-rw-r--r--

initial commit

     1 /****************************************************************************
     2  * Project:		liblpfk
     3  * Purpose:		Driver library for the IBM 6094-020 Lighted Program Function
     4  * 				Keyboard.
     5  * Version:		1.0
     6  * Author:		Philip Pemberton <philpem@philpem.me.uk>
     7  *
     8  * The latest version of this library is available from
     9  * <http://www.philpem.me.uk/code/liblpfk/>.
    10  *
    11  * Copyright (c) 2008, Philip Pemberton
    12  * All rights reserved.
    13  *
    14  * Redistribution and use in source and binary forms, with or without
    15  * modification, are permitted provided that the following conditions
    16  * are met:
    17  *
    18  *  * Redistributions of source code must retain the above copyright
    19  *    notice, this list of conditions and the following disclaimer.
    20  *  * Redistributions in binary form must reproduce the above copyright
    21  *    notice, this list of conditions and the following disclaimer in
    22  *    the documentation and/or other materials provided with the
    23  *    distribution.
    24  *  * Neither the name of the project nor the names of its
    25  *    contributors may be used to endorse or promote products derived
    26  *    from this software without specific prior written permission.
    27  *
    28  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    29  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    30  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
    31  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
    32  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
    33  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
    34  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
    35  *  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    36  *  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
    37  *  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
    38  *  USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    39  ****************************************************************************/
    41 /**
    42  * @file	liblpfk.h
    43  * @brief	liblpfk library header
    44  */
    46 #ifndef _liblpfk_h_included
    47 #define _liblpfk_h_included
    49 #include <termios.h>
    51 /**
    52  * @brief	LPFK context
    53  *
    54  * Do not change any variables inside this struct, they are for liblpfk's
    55  * internal use only.
    56  */
    57 typedef struct {
    58 	int				fd;			///< serial port file descriptor
    59 	struct termios	oldtio;		///< old termios setup
    60 	int				enabled;	///< LPFK enabled
    61 	unsigned long	led_mask;	///< lit LEDs mask
    62 } LPFK_CTX;
    64 /**
    65  * @brief	liblpfk error codes
    66  */
    67 enum {
    68 	LPFK_E_OK = 0,				///< No error, success.
    69 	LPFK_E_PORT_OPEN,			///< Could not open comm port.
    70 	LPFK_E_NOT_PRESENT,			///< LPFK not present on specified port.
    71 	LPFK_E_COMMS,				///< Communication error.
    72 	LPFK_E_PARAM				///< Invalid function parameter.
    73 };
    75 /**
    76  * @brief	Open a serial port and attempt to connecct to an LPFK on that
    77  * 			port.
    78  * @param	port	Serial port path (e.g. /dev/ttyS0).
    79  * @param	ctx		Pointer to an LPFK_CTX struct where LPFK context will be
    80  * 					stored.
    81  * @return	LPFK_E_OK on success, LPFK_E_PORT_OPEN if port could not be
    82  * 			opened, LPFK_E_NOT_PRESENT if no LPFK present on specified port.
    83  */
    84 int lpfk_open(const char *port, LPFK_CTX *ctx);
    86 /**
    87  * @brief	Close the LPFK.
    88  * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
    89  * @return	LPFK_E_OK
    90  */
    91 int lpfk_close(LPFK_CTX *ctx);
    93 /**
    94  * @brief	Enable or disable LPFK input
    95  * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
    96  * @param	val		true to enable the LPFK's keys, false to disable.
    97  * @return	LPFK_E_OK on success, LPFK_E_COMMS on comms error.
    98  */
    99 int lpfk_enable(LPFK_CTX *ctx, int val);
   101 /**
   102  * @brief	Set or clear an LED on the LPFK.
   103  * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
   104  * @param	num		LED/key number, from 0 to 31.
   105  * @param	state	State, true for on, false for off.
   106  * @return	LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
   107  * 			on comms error.
   108  */
   109 int lpfk_set_led(LPFK_CTX *ctx, const int num, const int state);
   111 /**
   112  * @brief	Set or clear all the LEDs on the LPFK.
   113  * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
   114  * @param	state	State, true for on, false for off.
   115  * @return	LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
   116  * 			on comms error.
   117  */
   118 int lpfk_set_leds(LPFK_CTX *ctx, const int state);
   120 /**
   121  * @brief	Get the status of an LED on the LPFK.
   122  * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
   123  * @param	num		LED/key number, from 0 to 31.
   124  * @return	true if LED is on, false otherwise.
   125  */
   126 int lpfk_get_led(LPFK_CTX *ctx, const int num);
   128 /**
   129  * @brief	Read a key from the LPFK
   130  * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
   131  * @return	-1 if no keys in buffer, 0-31 for key 1-32 down.
   132  */
   133 int lpfk_read(LPFK_CTX *ctx);
   135 #endif // _liblpfk_h_included