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