include/liblpfk.h

changeset 0
745037d69d81
child 1
3e775df109e6
     1.1 diff -r 000000000000 -r 745037d69d81 include/liblpfk.h
     1.2 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 +++ b/include/liblpfk.h	Tue Aug 26 12:45:33 2008 +0100
     1.4 @@ -0,0 +1,135 @@
     1.5 +/****************************************************************************
     1.6 + * Project:		liblpfk
     1.7 + * Purpose:		Driver library for the IBM 6094-020 Lighted Program Function
     1.8 + * 				Keyboard.
     1.9 + * Version:		1.0
    1.10 + * Author:		Philip Pemberton <philpem@philpem.me.uk>
    1.11 + *
    1.12 + * The latest version of this library is available from
    1.13 + * <http://www.philpem.me.uk/code/liblpfk/>.
    1.14 + *
    1.15 + * Copyright (c) 2008, Philip Pemberton
    1.16 + * All rights reserved.
    1.17 + *
    1.18 + * Redistribution and use in source and binary forms, with or without
    1.19 + * modification, are permitted provided that the following conditions
    1.20 + * are met:
    1.21 + *
    1.22 + *  * Redistributions of source code must retain the above copyright
    1.23 + *    notice, this list of conditions and the following disclaimer.
    1.24 + *  * Redistributions in binary form must reproduce the above copyright
    1.25 + *    notice, this list of conditions and the following disclaimer in
    1.26 + *    the documentation and/or other materials provided with the
    1.27 + *    distribution.
    1.28 + *  * Neither the name of the project nor the names of its
    1.29 + *    contributors may be used to endorse or promote products derived
    1.30 + *    from this software without specific prior written permission.
    1.31 + *
    1.32 + *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    1.33 + *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    1.34 + *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
    1.35 + *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
    1.36 + *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
    1.37 + *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
    1.38 + *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
    1.39 + *  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    1.40 + *  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
    1.41 + *  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
    1.42 + *  USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    1.43 + ****************************************************************************/
    1.44 +
    1.45 +/**
    1.46 + * @file	liblpfk.h
    1.47 + * @brief	liblpfk library header
    1.48 + */
    1.49 +
    1.50 +#ifndef _liblpfk_h_included
    1.51 +#define _liblpfk_h_included
    1.52 +
    1.53 +#include <termios.h>
    1.54 +
    1.55 +/**
    1.56 + * @brief	LPFK context
    1.57 + *
    1.58 + * Do not change any variables inside this struct, they are for liblpfk's
    1.59 + * internal use only.
    1.60 + */
    1.61 +typedef struct {
    1.62 +	int				fd;			///< serial port file descriptor
    1.63 +	struct termios	oldtio;		///< old termios setup
    1.64 +	int				enabled;	///< LPFK enabled
    1.65 +	unsigned long	led_mask;	///< lit LEDs mask
    1.66 +} LPFK_CTX;
    1.67 +
    1.68 +/**
    1.69 + * @brief	liblpfk error codes
    1.70 + */
    1.71 +enum {
    1.72 +	LPFK_E_OK = 0,				///< No error, success.
    1.73 +	LPFK_E_PORT_OPEN,			///< Could not open comm port.
    1.74 +	LPFK_E_NOT_PRESENT,			///< LPFK not present on specified port.
    1.75 +	LPFK_E_COMMS,				///< Communication error.
    1.76 +	LPFK_E_PARAM				///< Invalid function parameter.
    1.77 +};
    1.78 +
    1.79 +/**
    1.80 + * @brief	Open a serial port and attempt to connecct to an LPFK on that
    1.81 + * 			port.
    1.82 + * @param	port	Serial port path (e.g. /dev/ttyS0).
    1.83 + * @param	ctx		Pointer to an LPFK_CTX struct where LPFK context will be
    1.84 + * 					stored.
    1.85 + * @return	LPFK_E_OK on success, LPFK_E_PORT_OPEN if port could not be
    1.86 + * 			opened, LPFK_E_NOT_PRESENT if no LPFK present on specified port.
    1.87 + */
    1.88 +int lpfk_open(const char *port, LPFK_CTX *ctx);
    1.89 +
    1.90 +/**
    1.91 + * @brief	Close the LPFK.
    1.92 + * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
    1.93 + * @return	LPFK_E_OK
    1.94 + */
    1.95 +int lpfk_close(LPFK_CTX *ctx);
    1.96 +
    1.97 +/**
    1.98 + * @brief	Enable or disable LPFK input
    1.99 + * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
   1.100 + * @param	val		true to enable the LPFK's keys, false to disable.
   1.101 + * @return	LPFK_E_OK on success, LPFK_E_COMMS on comms error.
   1.102 + */
   1.103 +int lpfk_enable(LPFK_CTX *ctx, int val);
   1.104 +
   1.105 +/**
   1.106 + * @brief	Set or clear an LED on the LPFK.
   1.107 + * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
   1.108 + * @param	num		LED/key number, from 0 to 31.
   1.109 + * @param	state	State, true for on, false for off.
   1.110 + * @return	LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
   1.111 + * 			on comms error.
   1.112 + */
   1.113 +int lpfk_set_led(LPFK_CTX *ctx, const int num, const int state);
   1.114 +
   1.115 +/**
   1.116 + * @brief	Set or clear all the LEDs on the LPFK.
   1.117 + * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
   1.118 + * @param	state	State, true for on, false for off.
   1.119 + * @return	LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS
   1.120 + * 			on comms error.
   1.121 + */
   1.122 +int lpfk_set_leds(LPFK_CTX *ctx, const int state);
   1.123 +
   1.124 +/**
   1.125 + * @brief	Get the status of an LED on the LPFK.
   1.126 + * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
   1.127 + * @param	num		LED/key number, from 0 to 31.
   1.128 + * @return	true if LED is on, false otherwise.
   1.129 + */
   1.130 +int lpfk_get_led(LPFK_CTX *ctx, const int num);
   1.131 +
   1.132 +/**
   1.133 + * @brief	Read a key from the LPFK
   1.134 + * @param	ctx		Pointer to an LPFK_CTX struct initialised by lpfk_open().
   1.135 + * @return	-1 if no keys in buffer, 0-31 for key 1-32 down.
   1.136 + */
   1.137 +int lpfk_read(LPFK_CTX *ctx);
   1.138 +
   1.139 +#endif // _liblpfk_h_included