1.\" $NetBSD: bt_dev.3,v 1.2 2009/08/03 22:13:47 wiz Exp $ 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.\" 27.Dd August 3, 2009 28.Dt BT_DEV 3 29.Os 30.Sh NAME 31.Nm bt_devaddr , 32.Nm bt_devname , 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 , 46.Nm bt_devinquiry , 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 85These routines are designed to provide access to locally configured Bluetooth 86devices in an operating system independent manner via a socket providing access 87to Bluetooth HCI packets. 88.Sh FUNCTIONS 89.Bl -tag -width 4n 90.It Fn bt_devaddr "name" "bdaddr" 91Return a Bluetooth device address. 92.Fn bt_devaddr 93will return 1 if the NUL-terminated 94.Fa name 95string refers to a Bluetooth device present in the system, otherwise 0. 96The name may be given as a device name 97.Pq eg Qo ubt0 Qc 98or Bluetooth device address 99.Pq eg Qo 00:11:22:33:44:55 Qc 100and the actual device address will be written to 101.Fa bdaddr 102if not 103.Dv NULL . 104.It Fn bt_devname "name" "bdaddr" 105Return a Bluetooth device name. 106.Fn bt_devname 107returns 1 if the 108.Fa bdaddr 109refers to a Bluetooth device present in the system, otherwise 0. 110The 111.Fa name 112buffer, if given, should have space for at least 113.Dv HCI_DEVNAME_SIZE 114bytes and the string will be NUL-terminated. 115.It Fn bt_devenum "cb" "arg" 116Enumerate Bluetooth devices present in the system. 117For each device found, the 118.Fa cb 119function 120.Pq if not Dv NULL 121will be called with the 122.Fa arg 123argument provided, a fully populated 124.Ft bt_devinfo 125structure and, where the device is enabled, a socket handle as returned by 126.Fn bt_devopen . 127The callback function can halt the enumeration by returning a 128non-zero value, and 129.Fn bt_devenum 130returns the number of successfully enumerated devices. 131.It Fn bt_devinfo "name" "info" 132Obtain information from a Bluetooth device present in the system. 133The 134.Fa info 135argument is a pointer to a 136.Ft bt_devinfo 137structure into which information about device 138.Fa name 139is placed. 140The 141.Ft bt_devinfo 142structure 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 */ 158 uint16_t sco_free; /* available ACL packet buffers */ 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 176Because a Bluetooth device must be enabled in order to retrieve 177information, the 178.Fa enabled 179flag should be tested to be non-zero before relying on further data. 180.It Fn bt_devopen "name" "flags" 181Return a Bluetooth HCI socket handle bound and connected to the 182named Bluetooth device or, if 183.Fa name 184is 185.Dv NULL , 186enabled to receive packets from any device. 187The socket should be closed using 188.Xr close 2 189after use. 190Any combination of the following 191.Fa flags 192may be used to pre-set the socket options: 193.Bl -tag -width ".Dv BTOPT_DIRECTION" 194.It Dv BTOPT_DIRECTION 195Enable control messages on each packet indicating the direction of travel. 196.It Dv BTOPT_TIMESTAMP 197Enable control messages providing packet timestamps. 198.El 199.Lp 200The default filter on the socket will only allow the HCI Event packets 201.Qq Command Status 202and 203.Qq Command Complete 204to be received. 205.It Fn bt_devsend "s" "opcode" "param" "plen" 206Send an HCI command packet on the socket 207.Fa s . 208The 209.Fa opcode 210should be in host byte order and the 211.Fa param 212and 213.Fa plen 214arguments can be used to provide command parameter data. 215.Fn bt_devsend 216will return the number of bytes successfully written. 217.It Fn bt_devrecv "s" "buf" "size" "timeout" 218Receive a single HCI packet on the socket 219.Fa s . 220.Fn bt_devrecv 221will return the number of bytes successfully received unless the 222provided buffer could not contain the entire packet, or if a timeout was 223requested with a non-negative 224.Fa timeout 225value. 226.It Fn bt_devreq "s" "req" "timeout" 227Make an HCI request on the socket 228.Fa s . 229The 230.Fa req 231argument is a pointer to a 232.Ft bt_devreq 233structure, defined as: 234.Bd -literal -offset indent 235struct 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 246sends an HCI command packet with the given 247.Fa opcode 248and command parameters of 249.Fa clen 250bytes at 251.Fa cparam 252then waits up to 253.Fa timeout 254seconds for the command to return a 255.Qq Command Complete 256event. 257In the case where the command returns 258.Qq Command Status 259and an additional event, and where the status indicates 260that the command is in progress, 261.Fn bt_devreq 262will wait for the additional 263.Fa event 264specified in the request. 265If required, any response will be copied into the buffer of 266.Fa rlen 267bytes at 268.Fa rparam , 269and 270.Fa rlen 271will be adjusted to indicate the number of bytes stored. 272.Fn bt_devreq 273temporarily modifies the socket filter. 274.It Fn bt_devfilter "s" "new" "old" 275Update or extract the packet filter on HCI socket 276.Fa s . 277Filters can be set to indicate packet types 278.Pq Commands, Events, ACL and SCO data , 279and individual event IDs. 280Where 281.Fa old 282is given, the currently set filter will be extracted first, then if 283.Fa new 284is given, the filter will be updated. 285.It Fn bt_devfilter_pkt_set "filter" "type" 286Set packet 287.Fa type 288in 289.Fa filter . 290.It Fn bt_devfilter_pkt_clr "filter" "type" 291Clear packet 292.Fa type 293from 294.Fa filter . 295.It Fn bt_devfilter_pkt_tst "filter" "type" 296Test if 297.Fa filter 298has packet 299.Fa type 300set. 301.It Fn bt_devfilter_evt_set "filter" "event" 302Set 303.Fa event 304ID in 305.Fa filter . 306.It Fn bt_devfilter_evt_clr "filter" "event" 307Clear 308.Fa event 309ID from 310.Fa filter . 311.It Fn bt_devfilter_evt_tst "filter" "event" 312Test if 313.Fa filter 314has 315.Fa event 316ID set. 317.It Fn bt_devinquiry "name" "timeout" "max_rsp" "iip" 318Perform a Bluetooth Inquiry using the device 319.Fa name , 320or the first available device if 321.Dv NULL 322is passed. 323The inquiry length will be 324.Fa timeout 325seconds, and the number of responses 326.Pq up to a limit of Fa max_rsp 327will be returned. 328A pointer to an array of 329.Ft bt_devinquiry 330structures, defined as: 331.Bd -literal -offset indent 332struct 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 343will be stored in the location given by 344.Fa iip 345and this should be released after use with 346.Xr free 3 . 347.El 348.Sh RETURN VALUES 349These Bluetooth device access routines return \-1 on failure, and 350.Va errno 351will be set to indicate the error. 352.Sh ERRORS 353In addition to errors returned by the standard C library IO functions, 354the following errors may be indicated by device access routines. 355.Bl -tag -offset indent -width ".Bq Er ETIMEDOUT" 356.It Bq Er EINVAL 357A provided function argument was not valid. 358.It Bq Er EIO 359A device response was not properly understood. 360.It Bq Er ETIMEDOUT 361An operation exceeded the given time limit. 362.El 363.Sh SEE ALSO 364.Xr bluetooth 3 365.Sh HISTORY 366The Bluetooth device access API was created by 367.An Maksim Yevmenkin 368and first appeared in 369.Fx . 370This implementation written for 371.Nx 372by 373.An Iain Hibbert . 374