lib/usb_relay_device.h

   1 #ifndef USB_RELAY_DEVICE_H__
   2 #define USB_RELAY_DEVICE_H__
   3
   4 #define USBRELAY_LIB_VER 0x02
   5
   6 #ifdef WIN32
   7 #ifdef _MSC_VER /* Microsoft compiler: */
   8 #
   9 #ifndef USBRL_CALL
  10 #  define USBRL_CALL __cdecl
  11 #endif
  12 #ifndef USBRL_API
  13 #  define USBRL_API __declspec(dllimport) USBRL_CALL
  14 #  pragma comment(lib, "usb_relay_device")
  15 #endif
  16 #
  17 #else /* Windows & Not Microsoft's compiler */
  18 #  define USBRL_CALL
  19 #  define USBRL_API USBRL_CALL
  20 #endif /* Windows & Not Microsoft's compiler */
  21 #endif /* WIN32 */
  22
  23 #ifndef USBRL_CALL
  24 #  define USBRL_CALL
  25 #endif
  26 #ifndef USBRL_API
  27 #  define USBRL_API USBRL_CALL
  28 #endif
  29
  30
  31 #include <stddef.h>
  32
  33 enum usb_relay_device_type
  34 {
  35     USB_RELAY_DEVICE_ONE_CHANNEL   = 1,
  36     USB_RELAY_DEVICE_TWO_CHANNEL   = 2,
  37     USB_RELAY_DEVICE_FOUR_CHANNEL  = 4,
  38     USB_RELAY_DEVICE_EIGHT_CHANNEL = 8
  39 };
  40
  41
  42 /** USB relay board info structure */
  43 struct usb_relay_device_info
  44 {
  45     char *serial_number;
  46     char *device_path;
  47     intptr_t /*enum usb_relay_device_type*/ type;
  48     struct usb_relay_device_info* next;
  49 };
  50
  51 typedef struct usb_relay_device_info *pusb_relay_device_info_t;
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57 /** Initialize the USB Relay Library
  58 @returns: This function returns 0 on success and -1 on error.
  59 */
  60 int USBRL_API usb_relay_init(void);
  61
  62 /** Finalize the USB Relay Library.
  63 This function frees all of the static data associated with USB Relay Library.
  64 It should be called at the end of execution to avoid memory leaks.
  65 @returns:This function returns 0 on success and -1 on error.
  66 */
  67 int USBRL_API usb_relay_exit(void);
  68
  69 /** Enumerate the USB Relay Devices.
  70 @return Pointer to list of usb_relay_device_info
  71         Caller should free it with usb_relay_device_free_enumerate
  72 */
  73 pusb_relay_device_info_t USBRL_API usb_relay_device_enumerate(void);
  74
  75 /** Free an enumeration Linked List */
  76 void USBRL_API usb_relay_device_free_enumerate(struct usb_relay_device_info*);
  77
  78 /** Open device that serial number is serial_number
  79 @return: This function returns a valid handle to the device on success or NULL on failure.
  80 e.g: usb_relay_device_open_with_serial_number("abcde", 5") */
  81 intptr_t USBRL_API usb_relay_device_open_with_serial_number(const char *serial_number, unsigned len);
  82
  83 /* Open a USB relay device
  84 @return: This function returns a valid handle to the device on success or NULL on failure.
  85 */
  86 intptr_t USBRL_API usb_relay_device_open(struct usb_relay_device_info *device_info);
  87
  88 /* Close a USB relay device */
  89 void USBRL_API usb_relay_device_close(intptr_t hHandle);
  90
  91 /** Turn ON a relay channel on the USB-Relay-Device
  92 @param hHandle -- which usb relay device your want to operate
  93 @param index -- the channel number: 1...max
  94 @returns: 0 -- success; 1 -- error; 2 -- index is invalid
  95 */
  96 int USBRL_API usb_relay_device_open_one_relay_channel(intptr_t hHandle, int index);
  97
  98 /** Turn ON all relay channels on the USB-Relay-Device
  99 @param hHandle -- which usb relay device your want to operate
 100 @returns: 0 -- success; 1 -- error
 101 */
 102 int USBRL_API usb_relay_device_open_all_relay_channel(intptr_t hHandle);
 103
 104 /** Turn OFF a relay channel on the USB-Relay-Device
 105 @param index -- which channel your want to close
 106 @param hHandle -- which usb relay device your want to operate
 107 @returns: 0 -- success; 1 -- error
 108 */
 109 int USBRL_API usb_relay_device_close_one_relay_channel(intptr_t hHandle, int index);
 110
 111 /** Turn OFF all relay channels on the USB-Relay-Device
 112 @param hHandle -- which usb relay device your want to operate
 113 @returns: 0 -- success; 1 -- error; 2 -- index is invalid
 114 */
 115 int USBRL_API usb_relay_device_close_all_relay_channel(intptr_t hHandle);
 116
 117 /** Get state of all channels of the  USB-Relay-Device
 118 Status bits:  one bit indicate a relay status.
 119 bit 0/1/2/3/4/5/6/7/8 indicate channel 1/2/3/4/5/6/7/8 status
 120 Bit value 1 means ON, 0 means OFF.
 121 @returns: 0 -- success; 1 -- error
 122 */
 123 int USBRL_API usb_relay_device_get_status(intptr_t hHandle, unsigned int *status);
 124
 125 #if 1 /* added */
 126
 127 /** Get the library (dll) version
 128 @return Lower 16 bits: the library version. Higher bits: undefined, ignore.
 129 @note The original DLL does not have this function!
 130 */
 131 int USBRL_API usb_relay_device_lib_version(void);
 132
 133
 134 /**
 135  The following functions are for non-native callers, to avoid fumbling with C structs and pointers.
 136  Native C/C++ callers do not need to use these.
 137  The ptr_usb_relay_device_info arg is pointer to struct usb_relay_device_info, cast to intptr_t, void*, etc.
 138 */
 139
 140 /* Return next info struct pointer in the list returned by usb_relay_device_enumerate() */
 141 intptr_t USBRL_API usb_relay_device_next_dev(intptr_t ptr_usb_relay_device_info);
 142
 143 /* Get number of relay channels on the device */
 144 int      USBRL_API usb_relay_device_get_num_relays(intptr_t ptr_usb_relay_device_info);
 145
 146 /* Get the ID string of the device. Returns pointer to const C string (1-byte, 0-terminated) */
 147 intptr_t USBRL_API usb_relay_device_get_id_string(intptr_t ptr_usb_relay_device_info);
 148
 149 /* Get status of all relays on the device.
 150 * @param hHandle The relay device handle
 151 * @return Bitmask of all relay channels state, if the value > 0. Negative values mean error.
 152 *  bit 0/1/2/3/4/5/6/7/8 indicate channel 1/2/3/4/5/6/7/8 status
 153 *  Each bit value 1 means ON, 0 means OFF.
 154 * @note This is same as usb_relay_device_get_status, but without dereferencing pointers.
 155 */
 156 int USBRL_API usb_relay_device_get_status_bitmap(intptr_t hHandle);
 157
 158 #endif /* added */
 159
 160 #ifdef __cplusplus
 161 }
 162 #endif
 163
 164 #endif /* USB_RELAY_DEVICE_H__ */