lib/libusbhid/usbhid.3

   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.