From 8c65ae3293671131ff1bcf8bf73c25f2d4663f61 Mon Sep 17 00:00:00 2001 From: pavel Date: Tue, 31 Mar 2015 20:35:38 +0300 Subject: [PATCH] Upd. library doc. --- doc/Readme_USB-Relay-DLL.md | 119 ++++++++++++++++++++---------------- 1 file changed, 65 insertions(+), 54 deletions(-) diff --git a/doc/Readme_USB-Relay-DLL.md b/doc/Readme_USB-Relay-DLL.md index 618ff36..525aed8 100644 --- a/doc/Readme_USB-Relay-DLL.md +++ b/doc/Readme_USB-Relay-DLL.md @@ -7,103 +7,90 @@ Changes to the original DLL: ---------------------------- - The type used for handles changed from int to intptr_t, for 64-bit compatibility. This should be binary compatible with existing 32-bit clients. - - Added helper functions for use from managed languages and scripts; see below. + - Added helper functions for use from managed languages and scripts; see below, and + `usb_relay_device_lib_version` -Windows, Visual C++ applications ---------------------------------- - -Include file name: usb_relay_device.h -Library file name: usb_relay_device.lib - -Put the following lines in your source file: - - `#include ` +Functions: +--------- - `#pragma comment(lib, "usb_relay_device.lib")` - -The file usb_relay_device.dll must be installed with your application. -Use either 32-bit or 64-bit DLL, matching your application. -The DLL may require VC++ redistributable runtime library. - -Using the API: --------------- - - * `usb_relay_init()` + * `usb_relay_init` Call this before calling other functions - * `usb_relay_device_enumerate` + * `usb_relay_device_enumerate` Enumerates all Relay devices plugged into the PC. Returns list of usb_relay_device_info structures. Caller should free this list by passing it to usb_relay_device_free_enumerate(). - * `usb_relay_device_open` + * `usb_relay_device_open` Opens one Relay board device by its usb_relay_device_info structure, obtained from usb_relay_device_enumerate(). - * `usb_relay_device_open_with_serial_number` + * `usb_relay_device_open_with_serial_number` Opens one Relay board device by its serial number string. These strings can be obtained from usb_relay_device_enumerate(). - - * `usb_relay_device_open_one_relay_channel` + + * `usb_relay_device_open_one_relay_channel` Turns ON one channel of a Relay board. Parameters: - device handle, obtained from usb_relay_device_open() - Index: integer from 1 to the maximal number of channels on a board. - * `usb_relay_device_open_all_relay_channel` + * `usb_relay_device_open_all_relay_channel` Turns ON all channels on a board. - * `usb_relay_device_close_one_relay_channel` + * `usb_relay_device_close_one_relay_channel` Turns OFF one channel of a Relay board. Parameters: - - device handle, obtained from `usb_relay_device_open()` + - device handle, obtained from `usb_relay_device_open()` - Index: integer from 1 to the maximal number of channels on a board. - * `usb_relay_device_close_all_relay_channel` + * `usb_relay_device_close_all_relay_channel` Turns OFF all channels on a board. - - * `usb_relay_device_get_status` + + * `usb_relay_device_get_status` Get status of all channels on a board as a bit mask. The least significant bit in returned value corresponds to channel 1. Bit value 1 means the corresponding relay is switched ON, value 0 means the relay is OFF. - - * `usb_relay_device_close` + + * `usb_relay_device_close` Closes the Relay device handle opened by `usb_relay_device_open()` or `usb_relay_device_open_with_serial_number()` - - * `usb_relay_exit` + + * `usb_relay_exit` Finalizes the library - - + * `usb_relay_device_lib_version` + Returns the version of the library. + The lower 16 bits are the library version. Higher bits: undefined, ignore. + Note: this function is extension of the original library. + + + Helper functions for managed callers and scripts ------------------------------------------------ -These functions help to use this lib in managed languages. -Native C or C++ callers do not need to use these. -The ptr_usb_relay_device_info parameter is pointer to `struct usb_relay_device_info`, converted to a pointer-sized integer. +The following functions help to use this lib in managed languages by avoiding dereferencing C pointers. +Native C or C++ callers do not have to use these. +All these functions are extension of the original library. +The `ptr_usb_relay_device_info parameter` is pointer to `struct usb_relay_device_info`, converted to a pointer-sized integer. Type `int` means the "C" integer (which usually is 32-bit), `ptr` is a pointer-sized integer. * `ptr_usb_relay_device_info usb_relay_device_next_dev(ptr_usb_relay_device_info)` Returns pointer to the next element of device list obtained from `usb_relay_device_enumerate` - + * `int usb_relay_device_get_num_relays(ptr_usb_relay_device_info)` Returns number of relay channels on the device. Values <= 0 are not valid and mean error. - + * `ptr usb_relay_device_get_id_string(ptr_usb_relay_device_info)` Returns the "serial number" string of the device, as pointer to constant C string (one-byte characters, null terminated). - * `int USBRL_API usb_relay_device_lib_version()` - Returns the version of the library. - The lower 16 bits are the library version. Higher bits: undefined, ignore. - * `int usb_relay_device_get_status_bitmap(intptr_t hHandle)` Returns the states of all channels on a relay device as a bit mask. This is same as `usb_relay_device_get_status` but without dereferencing pointers. Negative returned values indicate error. Else, bits 0-7 of the value are states of each channel. - + Error handling --------------- If error occurred, the API functions that return error code return -1; @@ -116,16 +103,40 @@ Notes * The library is not thread-safe. Client application must ensure that only one thread calls the library. - -Managed .NET applications (C#, VB.NET) ---------------------------------------- -TBD +Windows, Visual C++ applications +--------------------------------- + +Include file name: `usb_relay_device.h` +Library file name: `usb_relay_device.lib` + +Put the following lines in your source file: + + `#include ` + + `#pragma comment(lib, "usb_relay_device.lib")` + +The library can be also loaded dynamically. +The file `usb_relay_device.dll` must be installed with your application. +Use either 32-bit or 64-bit DLL, matching your application. +The DLL may require VC++ redistributable runtime library. + + +Linux C/C++ applications (gcc, llvm) +----------------- +Same as above, except the #pragma. The library name is `usb_relay_device.so`. Python (CPython) ------------------- -TBD +Python programs can use this library via the Ctypes module. Examples are in Test directory. +Be sure to use the correct variant (32 or 64-bit) for your Python interpreter. + +Managed .NET applications (C#, VB.NET, Powershell) +--------------------------------------- +Managed programs can use this library via PInvoke. +Be sure to use the correct variant (32 or 64-bit). +TBD. -GCC or MinGW applications --------------------------- +GCC or MinGW applications on Windows +------------------------------------ TBD -- 2.25.1