[BACK]Return to usbhid.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libusbhid

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>