1.\" $NetBSD: usbhid.3,v 1.6 2002/10/01 19:31:54 wiz Exp $ 2.\" 3.\" Copyright (c) 1999, 2001 Lennart Augustsson <augustss@netbsd.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd December 29, 2001 28.Dt USBHID 3 29.Os 30.Sh NAME 31.Nm usbhid , 32.Nm hid_get_report_desc , 33.Nm hid_use_report_desc , 34.Nm hid_dispose_report_desc , 35.Nm hid_start_parse , 36.Nm hid_end_parse , 37.Nm hid_get_item , 38.Nm hid_report_size , 39.Nm hid_locate , 40.Nm hid_usage_page , 41.Nm hid_usage_in_page , 42.Nm hid_init , 43.Nm hid_get_data , 44.Nm hid_set_data 45.Nd USB HID access routines 46.Sh LIBRARY 47.Lb libusbhid 48.Sh SYNOPSIS 49.Fd #include \*[Lt]usbhid.h\*[Gt] 50.Ft report_desc_t 51.Fn hid_get_report_desc "int file" 52.Ft report_desc_t 53.Fn hid_use_report_desc "unsigned char *data" "unsigned int size" 54.Ft void 55.Fn hid_dispose_report_desc "report_desc_t d" 56.Ft hid_data_t 57.Fn hid_start_parse "report_desc_t d" "int kindset" "int id" 58.Ft void 59.Fn hid_end_parse "hid_data_t s" 60.Ft int 61.Fn hid_get_item "hid_data_t s" "hid_item_t *h" 62.Ft int 63.Fn hid_report_size "report_desc_t d" "hid_kind_t k" "int id" 64.Ft int 65.Fn hid_locate "report_desc_t d" "u_int usage" "hid_kind_t k" "hid_item_t *h" "int id" 66.Ft char * 67.Fn hid_usage_page "int i" 68.Ft char * 69.Fn hid_usage_in_page "u_int u" 70.Ft int 71.Fn hid_parse_usage_page "const char *" 72.Ft char * 73.Fn hid_parse_usage_in_page "const char *" 74.Ft void 75.Fn hid_init "char *file" 76.Ft int 77.Fn hid_get_data "void *data" "hid_item_t *h" 78.Ft void 79.Fn hid_set_data "void *data" "hid_item_t *h" "u_int data" 80.Sh DESCRIPTION 81The 82.Nm 83library provides routines to extract data from USB Human Interface Devices. 84.Ss INTRODUCTION 85USB HID devices send and receive data layed out in a device dependent way. 86The 87.Nm 88library contains routines to extract the 89.Em report descriptor 90which contains the data layout information and then use this information. 91.Pp 92The routines can be divided into four parts: extraction of the descriptor, 93parsing of the descriptor, translating to/from symbolic names, and 94data manipulation. 95.Ss DESCRIPTOR FUNCTIONS 96A report descriptor can be obtained by calling 97.Fn hid_get_report_desc 98with a file descriptor obtained by opening a 99.Xr uhid 4 100device. 101Alternatively a data buffer containing the report descriptor can be 102passed into 103.Fn hid_use_report_desc . 104The data is copied into an internal structure. 105When the report descriptor 106is no longer needed it should be freed by calling 107.Fn hid_dispose_report_desc . 108The type 109.Fa report_desc_t 110is opaque and should be used when calling the parsing functions. 111If 112.Fn hid_dispose_report_desc 113fails it will return 114.Fa NULL . 115.Ss DESCRIPTOR PARSING FUNCTIONS 116To parse the report descriptor the 117.Fn hid_start_parse 118function should be called with a report descriptor and a set that 119describes which items that are interesting. 120The set is obtained by or-ing together values 121.Fa "(1 \*[Lt]\*[Lt] k)" 122where 123.Fa k 124is an item of type 125.Fa hid_kind_t . 126The report id (if present) is given by 127.Fa id . 128The function returns 129.Fa NULL 130if the initialization fails, otherwise an opaque value to be used 131in subsequent calls. 132After parsing the 133.Fn hid_end_parse 134function should be called to free internal data structures. 135.Pp 136To iterate through all the items in the report descriptor 137.Fn hid_get_item 138should be called while it returns a value greater than 0. 139When the report descriptor ends it will returns 0; a syntax 140error within the report descriptor will cause a return value less 141than 0. 142The struct pointed to by 143.Fa h 144will be filled with the relevant data for the item. 145The definition of 146.Fa hid_item_t 147can be found in 148.Pa \*[Lt]usbhid.h\*[Gt] 149and the meaning of the components in the USB HID documentation. 150.Pp 151Data should be read/written to the device in the size of 152the report. 153The size of a report (of a certain kind) can be computed by the 154.Fn hid_report_size 155function. 156If the report is prefixed by an ID byte it is given by 157.Fa id . 158.Pp 159To locate a single item the 160.Fn hid_locate 161function can be used. 162It should be given the usage code of 163the item and its kind and it will fill the item and return 164non-zero if the item was found. 165.Ss NAME TRANSLATION FUNCTIONS 166The function 167.Fn hid_usage_page 168will return the symbolic name of a usage page, and the function 169.Fn hid_usage_in_page 170will return the symbolic name of the usage within the page. 171Both these functions may return a pointer to static data. 172.Pp 173The functions 174.Fn hid_parse_usage_page 175and 176.Fn hid_parse_usage_in_page 177are the inverses of 178.Fn hid_usage_page 179and 180.Fn hid_usage_in_page . 181They take a usage string and return the number of the usage, or -1 182if it cannot be found. 183.Pp 184Before any of these functions can be called the usage table 185must be parsed, this is done by calling 186.Fn hid_init 187with the name of the table. 188Passing 189.Fa NULL 190to this function will cause it to use the default table. 191.Ss DATA EXTRACTION FUNCTIONS 192Given the data obtained from a HID device and an item in the 193report descriptor the 194.Fn hid_get_data 195function extracts the value of the item. 196Conversely 197.Fn hid_set_data 198can be used to put data into a report (which must be zeroed first). 199.Sh FILES 200.Pa /usr/share/misc/usb_hid_usages 201The default HID usage table. 202.\" .Sh EXAMPLES 203.Sh SEE ALSO 204The 205.Tn USB 206specifications can be found at 207.Dv http://www.usb.org/developers/docs.html . 208.Pp 209.Xr uhid 4 , 210.Xr usb 4 211.Sh HISTORY 212The 213.Nm 214library first appeared in 215.Nx 1.5 216as 217.Nm usb 218library 219and was renamed to 220.Nm 221for 222.Nx 1.6 . 223.Sh BUGS 224This man page is woefully incomplete. 225