lib/libusb/usb.3

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