nut-debian/drivers/libshut.h

173 lines
6.5 KiB
C
Raw Normal View History

2010-03-26 01:20:59 +02:00
/*!
* @file libshut.h
* @brief HID Library - Generic serial SHUT backend for Generic HID Access (using MGE HIDParser)
* SHUT stands for Serial HID UPS Transfer, and was created by MGE UPS SYSTEMS
*
* @author Copyright (C) 2006 - 2007
* Arnaud Quette <aquette.dev@gmail.com>
*
* This program is sponsored by MGE UPS SYSTEMS - opensource.mgeups.com
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*
* -------------------------------------------------------------------------- */
2022-07-10 10:23:45 +03:00
#ifndef NUT_LIBSHUT_H_SEEN
#define NUT_LIBSHUT_H_SEEN 1
2010-03-26 01:20:59 +02:00
#include "main.h" /* for subdrv_info_t */
2022-07-10 10:23:45 +03:00
#include "nut_stdint.h" /* for uint16_t, size_t, PRIsize etc. */
2010-03-26 01:20:59 +02:00
2022-07-10 10:23:45 +03:00
extern upsdrv_info_t comm_upsdrv_info;
/* These typedefs are also named in usb-common.h (=> nut_libusb.h), adhering
* to one or another libusb API version. For consistency of "ifdef SHUT_MODE"
* handling in libhid.c and some drivers, these symbolic names are used in
* all the headers and are expected to match binary code of object files at
* (monolithic) driver build time.
*
* The MIN/MAX definitions here are primarily to generalize range-check
* code (especially if anything is done outside the libraries).
* FIXME: It may make sense to constrain the limits to lowest common
* denominator that should fit alll of libusb-0.1, libusb-1.0 and libshut,
* so that any build of the practical (driver) code knows to not exceed
* any use-case.
*
* Types below were mined from existing method signatures; see also the
* my_hid_descriptor struct in libshut.c for practical fixed-size types.
*/
/* Essentially the file descriptor type, "int" - as in ser_get_char() etc.: */
typedef int usb_dev_handle;
/* Originally "int" cast to "uint8_t" in shut_control_msg(),
* and "unsigned char" in shut_get_descriptor() */
typedef unsigned char usb_ctrl_requesttype;
#define USB_CTRL_REQUESTTYPE_MIN 0
#define USB_CTRL_REQUESTTYPE_MAX UCHAR_MAX
typedef int usb_ctrl_request;
#define USB_CTRL_REQUEST_MIN INT_MIN
#define USB_CTRL_REQUEST_MAX INT_MAX
typedef int usb_ctrl_endpoint;
#define USB_CTRL_ENDPOINT_MIN INT_MIN
#define USB_CTRL_ENDPOINT_MAX INT_MAX
typedef int usb_ctrl_msgvalue;
#define USB_CTRL_MSGVALUE_MIN INT_MIN
#define USB_CTRL_MSGVALUE_MAX INT_MAX
typedef int usb_ctrl_repindex;
#define USB_CTRL_REPINDEX_MIN INT_MIN
#define USB_CTRL_REPINDEX_MAX INT_MAX
typedef int usb_ctrl_strindex;
#define USB_CTRL_STRINDEX_MIN INT_MIN
#define USB_CTRL_STRINDEX_MAX INT_MAX
typedef unsigned char usb_ctrl_descindex;
#define USB_CTRL_DESCINDEX_MIN 0
#define USB_CTRL_DESCINDEX_MAX UCHAR_MAX
/* Here MIN/MAX should not matter much, type mostly used for casting */
typedef unsigned char* usb_ctrl_charbuf;
typedef unsigned char usb_ctrl_char;
#define USB_CTRL_CHAR_MIN 0
#define USB_CTRL_CHAR_MAX UCHAR_MAX
typedef size_t usb_ctrl_charbufsize; /*typedef int usb_ctrl_charbufsize;*/
#define USB_CTRL_CHARBUFSIZE_MIN 0
#define USB_CTRL_CHARBUFSIZE_MAX SIZE_MAX
#define PRI_NUT_USB_CTRL_CHARBUFSIZE PRIsize
typedef int usb_ctrl_timeout_msec; /* in milliseconds */
#define USB_CTRL_TIMEOUTMSEC_MIN INT_MIN
#define USB_CTRL_TIMEOUTMSEC_MAX INT_MAX
/* Same error-code definitions as in usb-common.h for libusb-0.1 API */
#define ERROR_ACCESS -EACCES
#define ERROR_BUSY -EBUSY
#define ERROR_IO -EIO
#define ERROR_NO_DEVICE -ENODEV
#define ERROR_NOT_FOUND -ENOENT
#define ERROR_OVERFLOW -EOVERFLOW
#define ERROR_PIPE -EPIPE
#define ERROR_TIMEOUT -ETIMEDOUT
2010-03-26 01:20:59 +02:00
/*!
* SHUTDevice_t: Describe a SHUT device. This structure contains exactly
* the 5 pieces of information by which a SHUT device identifies
* itself, so it serves as a kind of "fingerprint" of the device. This
* information must be matched exactly when reopening a device, and
* therefore must not be "improved" or updated by a client
* program. Vendor, Product, and Serial can be NULL if the
* corresponding string did not exist or could not be retrieved.
*/
typedef struct SHUTDevice_s {
2016-07-18 03:11:41 +03:00
uint16_t VendorID; /*!< Device's Vendor ID */
uint16_t ProductID; /*!< Device's Product ID */
char* Vendor; /*!< Device's Vendor Name */
char* Product; /*!< Device's Product Name */
char* Serial; /*!< Product serial number */
char* Bus; /*!< Bus name, e.g. "003" */
uint16_t bcdDevice; /*!< Device release number */
2022-07-10 10:23:45 +03:00
char *Device; /*!< Device name on the bus, e.g. "001" */
2010-03-26 01:20:59 +02:00
} SHUTDevice_t;
/*!
* shut_communication_subdriver_s: structure to describe the communication routines
*/
typedef struct shut_communication_subdriver_s {
2011-01-26 11:35:08 +02:00
const char *name; /* name of this subdriver */
2022-07-10 10:23:45 +03:00
const char *version; /* version of this subdriver */
int (*open)(usb_dev_handle *upsfd, /* try to open the next available */
2010-03-26 01:20:59 +02:00
SHUTDevice_t *curDevice, /* device matching USBDeviceMatcher_t */
char *device_path,
2022-07-10 10:23:45 +03:00
int (*callback)(usb_dev_handle upsfd, SHUTDevice_t *hd,
usb_ctrl_charbuf rdbuf, usb_ctrl_charbufsize rdlen));
void (*close)(usb_dev_handle upsfd);
int (*get_report)(usb_dev_handle upsfd, usb_ctrl_repindex ReportId,
usb_ctrl_charbuf raw_buf, usb_ctrl_charbufsize ReportSize);
int (*set_report)(usb_dev_handle upsfd, usb_ctrl_repindex ReportId,
usb_ctrl_charbuf raw_buf, usb_ctrl_charbufsize ReportSize);
int (*get_string)(usb_dev_handle upsfd,
usb_ctrl_strindex StringIdx, char *buf, usb_ctrl_charbufsize buflen);
int (*get_interrupt)(usb_dev_handle upsfd,
usb_ctrl_charbuf buf, usb_ctrl_charbufsize bufsize,
usb_ctrl_timeout_msec timeout);
2010-03-26 01:20:59 +02:00
} shut_communication_subdriver_t;
extern shut_communication_subdriver_t shut_subdriver;
/*!
* Notification levels
* These are however not processed currently
*/
#define OFF_NOTIFICATION 1 /* notification off */
#define LIGHT_NOTIFICATION 2 /* light notification */
#define COMPLETE_NOTIFICATION 3 /* complete notification for UPSs which do */
/* not support disabling it like some early */
/* Ellipse models */
#define DEFAULT_NOTIFICATION COMPLETE_NOTIFICATION
2022-07-10 10:23:45 +03:00
#endif /* NUT_LIBSHUT_H_SEEN */