Annotation of src/lib/libusbhid/usbhid.3, Revision 1.10
1.10 ! uebayasi 1: .\" $NetBSD: usbhid.3,v 1.9 2003/06/06 13:42:50 wiz Exp $
1.1 augustss 2: .\"
1.7 grant 3: .\" Copyright (c) 1999, 2001 Lennart Augustsson <augustss@NetBSD.org>
1.1 augustss 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: .\"
1.2 wiz 27: .Dd December 29, 2001
28: .Dt USBHID 3
1.1 augustss 29: .Os
30: .Sh NAME
1.2 wiz 31: .Nm usbhid ,
1.1 augustss 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
1.2 wiz 47: .Lb libusbhid
1.1 augustss 48: .Sh SYNOPSIS
1.8 wiz 49: .In usbhid.h
1.1 augustss 50: .Ft report_desc_t
51: .Fn hid_get_report_desc "int file"
52: .Ft report_desc_t
53: .Fn hid_use_report_desc "unsigned char *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
1.9 wiz 85: USB HID devices send and receive data laid out in a device dependent way.
1.6 wiz 86: The
1.1 augustss 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
1.6 wiz 100: device.
101: Alternatively a data buffer containing the report descriptor can be
1.1 augustss 102: passed into
103: .Fn hid_use_report_desc .
1.6 wiz 104: The data is copied into an internal structure.
105: When the report descriptor
1.1 augustss 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
1.6 wiz 119: describes which items that are interesting.
120: The set is obtained by or-ing together values
1.5 ross 121: .Fa "(1 \*[Lt]\*[Lt] k)"
1.1 augustss 122: where
123: .Fa k
124: is an item of type
125: .Fa hid_kind_t .
1.9 wiz 126: The report ID (if present) is given by
1.1 augustss 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
1.9 wiz 136: To iterate through all the items in the report descriptor,
1.1 augustss 137: .Fn hid_get_item
138: should be called while it returns a value greater than 0.
1.9 wiz 139: When the report descriptor ends it will return 0; a syntax
1.1 augustss 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
1.9 wiz 148: .Aq Pa usbhid.h
1.1 augustss 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
1.6 wiz 152: the report.
153: The size of a report (of a certain kind) can be computed by the
1.1 augustss 154: .Fn hid_report_size
1.6 wiz 155: function.
156: If the report is prefixed by an ID byte it is given by
1.1 augustss 157: .Fa id .
158: .Pp
159: To locate a single item the
160: .Fn hid_locate
1.6 wiz 161: function can be used.
162: It should be given the usage code of
1.1 augustss 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
1.6 wiz 187: with the name of the table.
188: Passing
1.1 augustss 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.
1.2 wiz 202: .\" .Sh EXAMPLES
1.1 augustss 203: .Sh SEE ALSO
1.10 ! uebayasi 204: .Xr uhid 4 ,
! 205: .Xr usb 4
! 206: .Pp
1.1 augustss 207: The
208: .Tn USB
209: specifications can be found at
1.4 wiz 210: .Dv http://www.usb.org/developers/docs.html .
1.1 augustss 211: .Sh HISTORY
212: The
213: .Nm
214: library first appeared in
1.2 wiz 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.
CVSweb <webmaster@jp.NetBSD.org>