lib/libusbhid/usbhid.3

   1 .\"     $NetBSD: usbhid.3,v 1.10 2004/06/10 14:01:45 uebayasi 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 .In usbhid.h
  50 .Ft report_desc_t
  51 .Fn hid_get_report_desc "int file"
  52 .Ft report_desc_t
  53 .Fn hid_use_report_desc "const uint8_t *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
  81 The
  82 .Nm
  83 library provides routines to extract data from USB Human Interface Devices.
  84 .Ss INTRODUCTION
  85 USB HID devices send and receive data laid out in a device dependent way.
  86 The
  87 .Nm
  88 library contains routines to extract the
  89 .Em report descriptor
  90 which contains the data layout information and then use this information.
  91 .Pp
  92 The routines can be divided into four parts: extraction of the descriptor,
  93 parsing of the descriptor, translating to/from symbolic names, and
  94 data manipulation.
  95 .Ss DESCRIPTOR FUNCTIONS
  96 A report descriptor can be obtained by calling
  97 .Fn hid_get_report_desc
  98 with a file descriptor obtained by opening a
  99 .Xr uhid 4
 100 device.
 101 Alternatively a data buffer containing the report descriptor can be
 102 passed into
 103 .Fn hid_use_report_desc .
 104 The data is copied into an internal structure.
 105 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.
 120 The set is obtained by or-ing together values
 121 .Fa "(1 \*[Lt]\*[Lt] k)"
 122 where
 123 .Fa k
 124 is an item of type
 125 .Fa hid_kind_t .
 126 The report ID (if present) is given by
 127 .Fa id .
 128 The function returns
 129 .Fa NULL
 130 if the initialization fails, otherwise an opaque value to be used
 131 in subsequent calls.
 132 After parsing the
 133 .Fn hid_end_parse
 134 function should be called to free internal data structures.
 135 .Pp
 136 To iterate through all the items in the report descriptor,
 137 .Fn hid_get_item
 138 should be called while it returns a value greater than 0.
 139 When the report descriptor ends it will return 0; a syntax
 140 error within the report descriptor will cause a return value less
 141 than 0.
 142 The struct pointed to by
 143 .Fa h
 144 will be filled with the relevant data for the item.
 145 The definition of
 146 .Fa hid_item_t
 147 can be found in
 148 .Aq Pa usbhid.h
 149 and the meaning of the components in the USB HID documentation.
 150 .Pp
 151 Data should be read/written to the device in the size of
 152 the report.
 153 The size of a report (of a certain kind) can be computed by the
 154 .Fn hid_report_size
 155 function.
 156 If the report is prefixed by an ID byte it is given by
 157 .Fa id .
 158 .Pp
 159 To locate a single item the
 160 .Fn hid_locate
 161 function can be used.
 162 It should be given the usage code of
 163 the item and its kind and it will fill the item and return
 164 non-zero if the item was found.
 165 .Ss NAME TRANSLATION FUNCTIONS
 166 The function
 167 .Fn hid_usage_page
 168 will return the symbolic name of a usage page, and the function
 169 .Fn hid_usage_in_page
 170 will return the symbolic name of the usage within the page.
 171 Both these functions may return a pointer to static data.
 172 .Pp
 173 The functions
 174 .Fn hid_parse_usage_page
 175 and
 176 .Fn hid_parse_usage_in_page
 177 are the inverses of
 178 .Fn hid_usage_page
 179 and
 180 .Fn hid_usage_in_page .
 181 They take a usage string and return the number of the usage, or -1
 182 if it cannot be found.
 183 .Pp
 184 Before any of these functions can be called the usage table
 185 must be parsed, this is done by calling
 186 .Fn hid_init
 187 with the name of the table.
 188 Passing
 189 .Fa NULL
 190 to this function will cause it to use the default table.
 191 .Ss DATA EXTRACTION FUNCTIONS
 192 Given the data obtained from a HID device and an item in the
 193 report descriptor the
 194 .Fn hid_get_data
 195 function extracts the value of the item.
 196 Conversely
 197 .Fn hid_set_data
 198 can be used to put data into a report (which must be zeroed first).
 199 .Sh FILES
 200 .Pa /usr/share/misc/usb_hid_usages
 201 The default HID usage table.
 202 .\" .Sh EXAMPLES
 203 .Sh SEE ALSO
 204 .Xr uhid 4 ,
 205 .Xr usb 4
 206 .Pp
 207 The
 208 .Tn USB
 209 specifications can be found at
 210 .Dv http://www.usb.org/developers/docs.html .
 211 .Sh HISTORY
 212 The
 213 .Nm
 214 library first appeared in
 215 .Nx 1.5
 216 as
 217 .Nm usb
 218 library
 219 and was renamed to
 220 .Nm
 221 for
 222 .Nx 1.6 .
 223 .Sh BUGS
 224 This man page is woefully incomplete.