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

Annotation of src/lib/libbluetooth/bt_dev.3, Revision 1.4

1.4     ! plunky      1: .\" $NetBSD: bt_dev.3,v 1.3 2011/10/25 09:33:55 plunky Exp $
1.1       plunky      2: .\"
                      3: .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
                      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.3       plunky     27: .Dd October 25, 2011
1.1       plunky     28: .Dt BT_DEV 3
                     29: .Os
                     30: .Sh NAME
1.2       wiz        31: .Nm bt_devaddr ,
                     32: .Nm bt_devname ,
1.1       plunky     33: .Nm bt_devenum ,
                     34: .Nm bt_devinfo ,
                     35: .Nm bt_devopen ,
                     36: .Nm bt_devsend ,
                     37: .Nm bt_devrecv ,
                     38: .Nm bt_devreq ,
                     39: .Nm bt_devfilter ,
                     40: .Nm bt_devfilter_pkt_set ,
                     41: .Nm bt_devfilter_pkt_clr ,
                     42: .Nm bt_devfilter_pkt_tst ,
                     43: .Nm bt_devfilter_evt_set ,
                     44: .Nm bt_devfilter_evt_clr ,
                     45: .Nm bt_devfilter_evt_tst ,
1.3       plunky     46: .Nm bt_devinquiry
1.1       plunky     47: .Nd Bluetooth device access routines
                     48: .Sh LIBRARY
                     49: .Lb libbluetooth
                     50: .Sh SYNOPSIS
                     51: .In bluetooth.h
                     52: .Ft int
                     53: .Fn bt_devaddr "const char *name" "bdaddr_t *bdaddr"
                     54: .Ft int
                     55: .Fn bt_devname "char *name" "const bdaddr_t *bdaddr"
                     56: .Ft int
                     57: .Fn bt_devenum "int (*cb)(int, const struct bt_devinfo *, void *)" "void *arg"
                     58: .Ft int
                     59: .Fn bt_devinfo "const char *name" "struct bt_devinfo *info"
                     60: .Ft int
                     61: .Fn bt_devopen "const char *name" "int flags"
                     62: .Ft ssize_t
                     63: .Fn bt_devsend "int s" "uint16_t opcode" "void *param" "size_t plen"
                     64: .Ft ssize_t
                     65: .Fn bt_devrecv "int s" "void *buf" "size_t size" "time_t timeout"
                     66: .Ft int
                     67: .Fn bt_devreq "int s" "struct bt_devreq *req" "time_t timeout"
                     68: .Ft int
                     69: .Fn bt_devfilter "int s" "const struct bt_devfilter *new" "struct bt_devfilter *old"
                     70: .Ft void
                     71: .Fn bt_devfilter_pkt_set "struct bt_devfilter *filter" "uint8_t type"
                     72: .Ft void
                     73: .Fn bt_devfilter_pkt_clr "struct bt_devfilter *filter" "uint8_t type"
                     74: .Ft int
                     75: .Fn bt_devfilter_pkt_tst "const struct bt_devfilter *filter" "uint8_t type"
                     76: .Ft void
                     77: .Fn bt_devfilter_evt_set "struct bt_devfilter *filter" "uint8_t event"
                     78: .Ft void
                     79: .Fn bt_devfilter_evt_clr "struct bt_devfilter *filter" "uint8_t event"
                     80: .Ft int
                     81: .Fn bt_devfilter_evt_tst "const struct bt_devfilter *filter" "uint8_t event"
                     82: .Ft int
                     83: .Fn bt_devinquiry "const char *name" "time_t timeout" "int max_rsp" "struct bt_devinquiry **iip"
                     84: .Sh DESCRIPTION
                     85: These routines are designed to provide access to locally configured Bluetooth
                     86: devices in an operating system independent manner via a socket providing access
                     87: to Bluetooth HCI packets.
                     88: .Sh FUNCTIONS
                     89: .Bl -tag -width 4n
                     90: .It Fn bt_devaddr "name" "bdaddr"
                     91: Return a Bluetooth device address.
                     92: .Fn bt_devaddr
                     93: will return 1 if the NUL-terminated
                     94: .Fa name
                     95: string refers to a Bluetooth device present in the system, otherwise 0.
                     96: The name may be given as a device name
                     97: .Pq eg Qo ubt0 Qc
                     98: or Bluetooth device address
                     99: .Pq eg Qo 00:11:22:33:44:55 Qc
                    100: and the actual device address will be written to
                    101: .Fa bdaddr
                    102: if not
                    103: .Dv NULL .
                    104: .It Fn bt_devname "name" "bdaddr"
                    105: Return a Bluetooth device name.
                    106: .Fn bt_devname
                    107: returns 1 if the
                    108: .Fa bdaddr
                    109: refers to a Bluetooth device present in the system, otherwise 0.
                    110: The
                    111: .Fa name
                    112: buffer, if given, should have space for at least
                    113: .Dv HCI_DEVNAME_SIZE
                    114: bytes and the string will be NUL-terminated.
                    115: .It Fn bt_devenum "cb" "arg"
                    116: Enumerate Bluetooth devices present in the system.
                    117: For each device found, the
                    118: .Fa cb
                    119: function
                    120: .Pq if not Dv NULL
                    121: will be called with the
                    122: .Fa arg
                    123: argument provided, a fully populated
                    124: .Ft bt_devinfo
                    125: structure and, where the device is enabled, a socket handle as returned by
                    126: .Fn bt_devopen .
                    127: The callback function can halt the enumeration by returning a
                    128: non-zero value, and
                    129: .Fn bt_devenum
                    130: returns the number of successfully enumerated devices.
                    131: .It Fn bt_devinfo "name" "info"
                    132: Obtain information from a Bluetooth device present in the system.
                    133: The
                    134: .Fa info
                    135: argument is a pointer to a
                    136: .Ft bt_devinfo
                    137: structure into which information about device
                    138: .Fa name
                    139: is placed.
                    140: The
                    141: .Ft bt_devinfo
                    142: structure contains at least the following members:
                    143: .Bd -literal
                    144:         char        devname[HCI_DEVNAME_SIZE];
                    145:         int         enabled;    /* device is enabled */
                    146:
                    147:         /* device information */
                    148:         bdaddr_t    bdaddr;
                    149:         uint8_t     features[HCI_FEATURES_SIZE];
                    150:         uint16_t    acl_size;   /* max ACL data size */
                    151:         uint16_t    acl_pkts;   /* total ACL packet buffers */
                    152:         uint16_t    sco_size;   /* max SCO data size */
                    153:         uint16_t    sco_pkts;   /* total SCO packet buffers */
                    154:
                    155:         /* flow control */
                    156:         uint16_t    cmd_free;   /* available CMD packet buffers */
                    157:         uint16_t    acl_free;   /* available ACL packet buffers */
1.4     ! plunky    158:         uint16_t    sco_free;   /* available SCO packet buffers */
1.1       plunky    159:
                    160:         /* statistics */
                    161:         uint32_t    cmd_sent;
                    162:         uint32_t    evnt_recv;
                    163:         uint32_t    acl_recv;
                    164:         uint32_t    acl_sent;
                    165:         uint32_t    sco_recv;
                    166:         uint32_t    sco_sent;
                    167:         uint32_t    bytes_recv;
                    168:         uint32_t    bytes_sent;
                    169:
                    170:         /* device settings */
                    171:         uint16_t    link_policy_info;
                    172:         uint16_t    packet_type_info;
                    173:         uint16_t    role_switch_info;
                    174: .Ed
                    175: .Lp
                    176: Because a Bluetooth device must be enabled in order to retrieve
                    177: information, the
                    178: .Fa enabled
                    179: flag should be tested to be non-zero before relying on further data.
                    180: .It Fn bt_devopen "name" "flags"
                    181: Return a Bluetooth HCI socket handle bound and connected to the
                    182: named Bluetooth device or, if
                    183: .Fa name
                    184: is
                    185: .Dv NULL ,
                    186: enabled to receive packets from any device.
                    187: The socket should be closed using
                    188: .Xr close 2
                    189: after use.
                    190: Any combination of the following
                    191: .Fa flags
                    192: may be used to pre-set the socket options:
                    193: .Bl -tag -width ".Dv BTOPT_DIRECTION"
                    194: .It Dv BTOPT_DIRECTION
                    195: Enable control messages on each packet indicating the direction of travel.
                    196: .It Dv BTOPT_TIMESTAMP
                    197: Enable control messages providing packet timestamps.
                    198: .El
                    199: .Lp
                    200: The default filter on the socket will only allow the HCI Event packets
                    201: .Qq Command Status
                    202: and
                    203: .Qq Command Complete
                    204: to be received.
                    205: .It Fn bt_devsend "s" "opcode" "param" "plen"
                    206: Send an HCI command packet on the socket
                    207: .Fa s .
                    208: The
                    209: .Fa opcode
                    210: should be in host byte order and the
                    211: .Fa param
                    212: and
                    213: .Fa plen
                    214: arguments can be used to provide command parameter data.
                    215: .Fn bt_devsend
                    216: will return the number of bytes successfully written.
                    217: .It Fn bt_devrecv "s" "buf" "size" "timeout"
                    218: Receive a single HCI packet on the socket
                    219: .Fa s .
                    220: .Fn bt_devrecv
                    221: will return the number of bytes successfully received unless the
                    222: provided buffer could not contain the entire packet, or if a timeout was
                    223: requested with a non-negative
                    224: .Fa timeout
                    225: value.
                    226: .It Fn bt_devreq "s" "req" "timeout"
                    227: Make an HCI request on the socket
                    228: .Fa s .
                    229: The
                    230: .Fa req
                    231: argument is a pointer to a
                    232: .Ft bt_devreq
                    233: structure, defined as:
                    234: .Bd -literal -offset indent
                    235: struct bt_devreq {
                    236:         uint16_t        opcode;
                    237:         uint8_t         event;
                    238:         void           *cparam;
                    239:         size_t          clen;
                    240:         void           *rparam;
                    241:         size_t          rlen;
                    242: };
                    243: .Ed
                    244: .Lp
                    245: .Fn bt_devreq
                    246: sends an HCI command packet with the given
                    247: .Fa opcode
                    248: and command parameters of
                    249: .Fa clen
                    250: bytes at
                    251: .Fa cparam
                    252: then waits up to
                    253: .Fa timeout
                    254: seconds for the command to return a
                    255: .Qq Command Complete
                    256: event.
                    257: In the case where the command returns
                    258: .Qq Command Status
                    259: and an additional event, and where the status indicates
                    260: that the command is in progress,
                    261: .Fn bt_devreq
                    262: will wait for the additional
                    263: .Fa event
                    264: specified in the request.
                    265: If required, any response will be copied into the buffer of
                    266: .Fa rlen
                    267: bytes at
                    268: .Fa rparam ,
                    269: and
                    270: .Fa rlen
                    271: will be adjusted to indicate the number of bytes stored.
                    272: .Fn bt_devreq
                    273: temporarily modifies the socket filter.
                    274: .It Fn bt_devfilter "s" "new" "old"
                    275: Update or extract the packet filter on HCI socket
                    276: .Fa s .
                    277: Filters can be set to indicate packet types
                    278: .Pq Commands, Events, ACL and SCO data ,
                    279: and individual event IDs.
                    280: Where
                    281: .Fa old
                    282: is given, the currently set filter will be extracted first, then if
                    283: .Fa new
                    284: is given, the filter will be updated.
                    285: .It Fn bt_devfilter_pkt_set "filter" "type"
                    286: Set packet
                    287: .Fa type
                    288: in
                    289: .Fa filter .
                    290: .It Fn bt_devfilter_pkt_clr "filter" "type"
                    291: Clear packet
                    292: .Fa type
                    293: from
                    294: .Fa filter .
                    295: .It Fn bt_devfilter_pkt_tst "filter" "type"
                    296: Test if
                    297: .Fa filter
                    298: has packet
                    299: .Fa type
                    300: set.
                    301: .It Fn bt_devfilter_evt_set "filter" "event"
                    302: Set
                    303: .Fa event
                    304: ID in
                    305: .Fa filter .
                    306: .It Fn bt_devfilter_evt_clr "filter" "event"
                    307: Clear
                    308: .Fa event
                    309: ID from
                    310: .Fa filter .
                    311: .It Fn bt_devfilter_evt_tst "filter" "event"
                    312: Test if
                    313: .Fa filter
                    314: has
                    315: .Fa event
                    316: ID set.
                    317: .It Fn bt_devinquiry "name" "timeout" "max_rsp" "iip"
                    318: Perform a Bluetooth Inquiry using the device
                    319: .Fa name ,
1.2       wiz       320: or the first available device if
                    321: .Dv NULL
                    322: is passed.
1.1       plunky    323: The inquiry length will be
                    324: .Fa timeout
                    325: seconds, and the number of responses
                    326: .Pq up to a limit of Fa max_rsp
                    327: will be returned.
                    328: A pointer to an array of
                    329: .Ft bt_devinquiry
                    330: structures, defined as:
                    331: .Bd -literal -offset indent
                    332: struct bt_devinquiry {
                    333:         bdaddr_t        bdaddr;
                    334:         uint8_t         pscan_rep_mode;
                    335:         uint8_t         pscan_period_mode;
                    336:         uint8_t         dev_class[3];
                    337:         uint16_t        clock_offset;
                    338:         int8_t          rssi;
                    339:         uint8_t         data[240];
                    340: };
                    341: .Ed
                    342: .Lp
                    343: will be stored in the location given by
                    344: .Fa iip
                    345: and this should be released after use with
                    346: .Xr free 3 .
                    347: .El
                    348: .Sh RETURN VALUES
1.2       wiz       349: These Bluetooth device access routines return \-1 on failure, and
1.1       plunky    350: .Va errno
                    351: will be set to indicate the error.
                    352: .Sh ERRORS
                    353: In addition to errors returned by the standard C library IO functions,
                    354: the following errors may be indicated by device access routines.
                    355: .Bl -tag -offset indent -width ".Bq Er ETIMEDOUT"
                    356: .It Bq Er EINVAL
                    357: A provided function argument was not valid.
                    358: .It Bq Er EIO
                    359: A device response was not properly understood.
                    360: .It Bq Er ETIMEDOUT
                    361: An operation exceeded the given time limit.
                    362: .El
                    363: .Sh SEE ALSO
                    364: .Xr bluetooth 3
                    365: .Sh HISTORY
                    366: The Bluetooth device access API was created by
                    367: .An Maksim Yevmenkin
                    368: and first appeared in
                    369: .Fx .
                    370: This implementation written for
                    371: .Nx
                    372: by
                    373: .An Iain Hibbert .

CVSweb <webmaster@jp.NetBSD.org>