lib/libusbhid/usbhid.3

   1 .\"     $NetBSD: usb.3,v 1.13 2000/09/24 02:17:52 augustss 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 .\" $FreeBSD: src/lib/libusbhid/usbhid.3,v 1.18 2005/11/24 11:26:36 ru Exp $
  28 .\" $DragonFly: src/lib/libusbhid/usbhid.3,v 1.10 2008/11/26 17:17:16 swildner Exp $
  29 .\"
  30 .Dd November 24, 2008
  31 .Dt USBHID 3
  32 .Os
  33 .Sh NAME
  34 .Nm usbhid ,
  35 .Nm hid_get_report_desc ,
  36 .Nm hid_use_report_desc ,
  37 .Nm hid_dispose_report_desc ,
  38 .Nm hid_start_parse ,
  39 .Nm hid_end_parse ,
  40 .Nm hid_get_item ,
  41 .Nm hid_report_size ,
  42 .Nm hid_locate ,
  43 .Nm hid_usage_page ,
  44 .Nm hid_usage_in_page ,
  45 .Nm hid_parse_usage_page ,
  46 .Nm hid_parse_usage_in_page ,
  47 .Nm hid_init ,
  48 .Nm hid_get_data ,
  49 .Nm hid_set_data
  50 .Nd USB HID access routines
  51 .Sh LIBRARY
  52 .Lb libusbhid
  53 .Sh SYNOPSIS
  54 .In usbhid.h
  55 .Ft report_desc_t
  56 .Fn hid_get_report_desc "int file"
  57 .Ft report_desc_t
  58 .Fn hid_use_report_desc "unsigned char *data" "unsigned int size"
  59 .Ft void
  60 .Fn hid_dispose_report_desc "report_desc_t d"
  61 .Ft hid_data_t
  62 .Fn hid_start_parse "report_desc_t d" "int kindset" "int id"
  63 .Ft void
  64 .Fn hid_end_parse "hid_data_t s"
  65 .Ft int
  66 .Fn hid_get_item "hid_data_t s" "hid_item_t *h"
  67 .Ft int
  68 .Fn hid_report_size "report_desc_t d" "hid_kind_t k" "int id"
  69 .Ft int
  70 .Fn hid_locate "report_desc_t d" "u_int usage" "hid_kind_t k" "hid_item_t *h" "int id"
  71 .Ft "const char *"
  72 .Fn hid_usage_page "int i"
  73 .Ft "const char *"
  74 .Fn hid_usage_in_page "u_int u"
  75 .Ft int
  76 .Fn hid_parse_usage_page "const char *"
  77 .Ft int
  78 .Fn hid_parse_usage_in_page "const char *"
  79 .Ft void
  80 .Fn hid_init "const char *file"
  81 .Ft int
  82 .Fn hid_get_data "const void *data" "const hid_item_t *h"
  83 .Ft void
  84 .Fn hid_set_data "void *buf" "const hid_item_t *h" "int data"
  85 .Sh DESCRIPTION
  86 The
  87 .Nm
  88 library provides routines to extract data from USB Human Interface Devices.
  89 .Ss Introduction
  90 USB HID devices send and receive data laid out in a device dependent way.
  91 The
  92 .Nm
  93 library contains routines to extract the
  94 .Em "report descriptor"
  95 which contains the data layout information and then use this information.
  96 .Pp
  97 The routines can be divided into four parts: extraction of the descriptor,
  98 parsing of the descriptor, translating to/from symbolic names, and
  99 data manipulation.
 100 .Ss Descriptor Functions
 101 A report descriptor can be obtained by calling
 102 .Fn hid_get_report_desc
 103 with a file descriptor obtained by opening a
 104 .Xr uhid 4
 105 device.
 106 Alternatively a data buffer containing the report descriptor can be
 107 passed into
 108 .Fn hid_use_report_desc .
 109 The data is copied into an internal structure.
 110 When the report descriptor
 111 is no longer needed it should be freed by calling
 112 .Fn hid_dispose_report_desc .
 113 The type
 114 .Vt report_desc_t
 115 is opaque and should be used when calling the parsing functions.
 116 If
 117 .Fn hid_dispose_report_desc
 118 fails it will return
 119 .Dv NULL .
 120 .Ss Descriptor Parsing Functions
 121 To parse the report descriptor the
 122 .Fn hid_start_parse
 123 function should be called with a report descriptor and a set that
 124 describes which items that are interesting.
 125 The set is obtained by OR-ing together values
 126 .Fa "(1 << k)"
 127 where
 128 .Fa k
 129 is an item of type
 130 .Vt hid_kind_t .
 131 The report ID (if present) is given by
 132 .Fa id .
 133 The function returns
 134 .Dv NULL
 135 if the initialization fails, otherwise an opaque value to be used
 136 in subsequent calls.
 137 After parsing the
 138 .Fn hid_end_parse
 139 function should be called to free internal data structures.
 140 .Pp
 141 To iterate through all the items in the report descriptor
 142 .Fn hid_get_item
 143 should be called while it returns a value greater than 0.
 144 When the report descriptor ends it will returns 0; a syntax
 145 error within the report descriptor will cause a return value less
 146 than 0.
 147 The struct pointed to by
 148 .Fa h
 149 will be filled with the relevant data for the item.
 150 The definition of
 151 .Vt hid_item_t
 152 can be found in
 153 .In usbhid.h
 154 and the meaning of the components in the USB HID documentation.
 155 .Pp
 156 Data should be read/written to the device in the size of
 157 the report.
 158 The size of a report (of a certain kind) can be computed by the
 159 .Fn hid_report_size
 160 function.
 161 If the report is prefixed by an ID byte it is given by
 162 .Fa id .
 163 .Pp
 164 To locate a single item the
 165 .Fn hid_locate
 166 function can be used.
 167 It should be given the usage code of
 168 the item and its kind and it will fill the item and return
 169 non-zero if the item was found.
 170 .Ss Name Translation Functions
 171 The function
 172 .Fn hid_usage_page
 173 will return the symbolic name of a usage page, and the function
 174 .Fn hid_usage_in_page
 175 will return the symbolic name of the usage within the page.
 176 Both these functions may return a pointer to static data.
 177 .Pp
 178 The functions
 179 .Fn hid_parse_usage_page
 180 and
 181 .Fn hid_parse_usage_in_page
 182 are the inverses of
 183 .Fn hid_usage_page
 184 and
 185 .Fn hid_usage_in_page .
 186 They take a usage string and return the number of the usage, or \-1
 187 if it cannot be found.
 188 .Pp
 189 Before any of these functions can be called the usage table
 190 must be parsed, this is done by calling
 191 .Fn hid_init
 192 with the name of the table.
 193 Passing
 194 .Dv NULL
 195 to this function will cause it to use the default table.
 196 .Ss Data Extraction Functions
 197 Given the data obtained from a HID device and an item in the
 198 report descriptor the
 199 .Fn hid_get_data
 200 function extracts the value of the item.
 201 Conversely
 202 .Fn hid_set_data
 203 can be used to put data into a report (which must be zeroed first).
 204 .Sh FILES
 205 .Bl -tag -width ".Pa /usr/share/misc/usb_hid_usages"
 206 .It Pa /usr/share/misc/usb_hid_usages
 207 The default HID usage table.
 208 .El
 209 .Sh EXAMPLES
 210 Not yet.
 211 .Sh SEE ALSO
 212 The
 213 .Tn USB
 214 specifications can be found at
 215 .Pa http://www.usb.org/developers/docs/ .
 216 .Pp
 217 .Xr uhid 4 ,
 218 .Xr usb 4
 219 .Sh HISTORY
 220 The
 221 .Nm
 222 library first appeared in
 223 .Nx 1.5 .
 224 .Sh BUGS
 225 This man page is woefully incomplete.