lib/libbluetooth/bluetooth.3

   1 .\" Copyright (c) 2003-2009 Maksim Yevmenkin <m_evmenkin@yahoo.com>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $Id: bluetooth.3,v 1.5 2003/05/20 23:04:30 max Exp $
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd February 13, 2009
  29 .Dt BLUETOOTH 3
  30 .Os
  31 .Sh NAME
  32 .Nm bt_gethostbyname ,
  33 .Nm bt_gethostbyaddr ,
  34 .Nm bt_gethostent ,
  35 .Nm bt_sethostent ,
  36 .Nm bt_endhostent ,
  37 .Nm bt_getprotobyname ,
  38 .Nm bt_getprotobynumber ,
  39 .Nm bt_getprotoent ,
  40 .Nm bt_setprotoent ,
  41 .Nm bt_endprotoent ,
  42 .Nm bt_aton ,
  43 .Nm bt_ntoa ,
  44 .Nm bdaddr_same ,
  45 .Nm bdaddr_any ,
  46 .Nm bdaddr_copy
  47 .Nd Bluetooth routines
  48 .Sh LIBRARY
  49 .Lb libbluetooth
  50 .Sh SYNOPSIS
  51 .In bluetooth.h
  52 .Ft struct hostent *
  53 .Fn bt_gethostbyname "const char *name"
  54 .Ft struct hostent *
  55 .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
  56 .Ft struct hostent *
  57 .Fn bt_gethostent void
  58 .Ft void
  59 .Fn bt_sethostent "int stayopen"
  60 .Ft void
  61 .Fn bt_endhostent void
  62 .Ft struct protoent *
  63 .Fn bt_getprotobyname "const char *name"
  64 .Ft struct protoent *
  65 .Fn bt_getprotobynumber "int proto"
  66 .Ft struct protoent *
  67 .Fn bt_getprotoent void
  68 .Ft void
  69 .Fn bt_setprotoent "int stayopen"
  70 .Ft void
  71 .Fn bt_endprotoent void
  72 .Ft int
  73 .Fn bt_aton "const char *str" "bdaddr_t *ba"
  74 .Ft const char *
  75 .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
  76 .Ft int
  77 .Fn bt_devaddr "const char *devname" "bdaddr_t *addr"
  78 .Ft int
  79 .Fn bt_devname "char *devname" "const bdaddr_t *addr"
  80 .Ft int
  81 .Fn (bt_devenum_cb_t) "int s" "struct bt_devinfo const *di" "void *arg"
  82 .Ft int
  83 .Fn bt_devinfo "struct bt_devinfo *di"
  84 .Ft int
  85 .Fn bt_devenum "bt_devenum_cb_t *cb" "void *arg"
  86 .Ft int
  87 .Fn bdaddr_same "const bdaddr_t *a" "const bdaddr_t *b"
  88 .Ft int
  89 .Fn bdaddr_any "const bdaddr_t *a"
  90 .Ft int
  91 .Fn bdaddr_copy "const bdaddr_t *dst" "const bdaddr_t *src"
  92 .Sh DESCRIPTION
  93 The
  94 .Fn bt_gethostent ,
  95 .Fn bt_gethostbyname
  96 and
  97 .Fn bt_gethostbyaddr
  98 functions
  99 each return a pointer to an object with the
 100 .Vt hostent
 101 structure describing a Bluetooth host
 102 referenced by name or by address, respectively.
 103 .Pp
 104 The
 105 .Fa name
 106 argument passed to
 107 .Fn bt_gethostbyname
 108 should point to a
 109 .Dv NUL Ns -terminated
 110 hostname.
 111 The
 112 .Fa addr
 113 argument passed to
 114 .Fn bt_gethostbyaddr
 115 should point to an address which is
 116 .Fa len
 117 bytes long,
 118 in binary form
 119 (i.e., not a Bluetooth BD_ADDR in human readable
 120 .Tn ASCII
 121 form).
 122 The
 123 .Fa type
 124 argument specifies the address family of this address and must be set to
 125 .Dv AF_BLUETOOTH .
 126 .Pp
 127 The structure returned contains the information obtained from a line in
 128 .Pa /etc/bluetooth/hosts
 129 file.
 130 .Pp
 131 The
 132 .Fn bt_sethostent
 133 function controls whether
 134 .Pa /etc/bluetooth/hosts
 135 file should stay open after each call to
 136 .Fn bt_gethostbyname
 137 or
 138 .Fn bt_gethostbyaddr .
 139 If the
 140 .Fa stayopen
 141 flag is non-zero, the file will not be closed.
 142 .Pp
 143 The
 144 .Fn bt_endhostent
 145 function closes the
 146 .Pa /etc/bluetooth/hosts
 147 file.
 148 .Pp
 149 The
 150 .Fn bt_getprotoent ,
 151 .Fn bt_getprotobyname
 152 and
 153 .Fn bt_getprotobynumber
 154 functions each return a pointer to an object with the
 155 .Vt protoent
 156 structure describing a Bluetooth Protocol Service Multiplexor referenced
 157 by name or number, respectively.
 158 .Pp
 159 The
 160 .Fa name
 161 argument passed to
 162 .Fn bt_getprotobyname
 163 should point to a
 164 .Dv NUL Ns -terminated
 165 Bluetooth Protocol Service Multiplexor name.
 166 The
 167 .Fa proto
 168 argument passed to
 169 .Fn bt_getprotobynumber
 170 should have numeric value of the desired Bluetooth Protocol Service Multiplexor.
 171 .Pp
 172 The structure returned contains the information obtained from a line in
 173 .Pa /etc/bluetooth/protocols
 174 file.
 175 .Pp
 176 The
 177 .Fn bt_setprotoent
 178 function controls whether
 179 .Pa /etc/bluetooth/protocols
 180 file should stay open after each call to
 181 .Fn bt_getprotobyname
 182 or
 183 .Fn bt_getprotobynumber .
 184 If the
 185 .Fa stayopen
 186 flag is non-zero, the file will not be closed.
 187 .Pp
 188 The
 189 .Fn bt_endprotoent
 190 function closes the
 191 .Pa /etc/bluetooth/protocols
 192 file.
 193 .Pp
 194 The
 195 .Fn bt_aton
 196 routine interprets the specified character string as a Bluetooth address,
 197 placing the address into the structure provided.
 198 It returns 1 if the string was successfully interpreted,
 199 or 0 if the string is invalid.
 200 .Pp
 201 The routine
 202 .Fn bt_ntoa
 203 takes a Bluetooth address and places an
 204 .Tn ASCII
 205 string representing the address into the buffer provided.
 206 It is up to the caller to ensure that provided buffer has enough space.
 207 If no buffer was provided then internal static buffer will be used.
 208 .Pp
 209 The
 210 .Fn bt_devaddr
 211 function interprets the specified
 212 .Fa devname
 213 string as the address or device name of a Bluetooth device on the local system,
 214 and places the device address in the provided
 215 .Fa bdaddr ,
 216 if any.
 217 The function returns 1 if the string was successfully interpreted,
 218 or 0 if the string did not match any local device.
 219 The
 220 .Fn bt_devname
 221 function takes a Bluetooth device address and copies the local device
 222 name associated with that address into the buffer provided,
 223 if any.
 224 Caller must ensure that provided buffer is at least
 225 .Dv HCI_DEVNAME_SIZE
 226 characters in size.
 227 The function returns 1 when the device was found,
 228 otherwise 0.
 229 .Pp
 230 The
 231 .Fn bt_devinfo
 232 function populates prodivded
 233 .Vt bt_devinfo
 234 structure with the information about given Bluetooth device.
 235 The caller is expected to pass Bluetooth device name in the
 236 .Fa devname
 237 field of the passed
 238 .Vt bt_devinfo
 239 structure.
 240 The function returns 0 when successful,
 241 otherwise -1.
 242 The
 243 .Vt bt_devinfo
 244 structure is defined as follows
 245 .Bd -literal -offset indent
 246 struct bt_devinfo
 247 {
 248         char            devname[HCI_DEVNAME_SIZE];
 249
 250         uint32_t        state;
 251
 252         bdaddr_t        bdaddr;
 253         uint16_t        _reserved0;
 254
 255         uint8_t         features[HCI_DEVFEATURES_SIZE];
 256
 257         /* buffer info */
 258         uint16_t        _reserved1;
 259         uint16_t        cmd_free;
 260         uint16_t        sco_size;
 261         uint16_t        sco_pkts;
 262         uint16_t        sco_free;
 263         uint16_t        acl_size;
 264         uint16_t        acl_pkts;
 265         uint16_t        acl_free;
 266
 267         /* stats */
 268         uint32_t        cmd_sent;
 269         uint32_t        evnt_recv;
 270         uint32_t        acl_recv;
 271         uint32_t        acl_sent;
 272         uint32_t        sco_recv;
 273         uint32_t        sco_sent;
 274         uint32_t        bytes_recv;
 275         uint32_t        bytes_sent;
 276
 277         /* misc/specific */
 278         uint16_t        link_policy_info;
 279         uint16_t        packet_type_info;
 280         uint16_t        role_switch_info;
 281         uint16_t        debug;
 282
 283         uint8_t         _padding[20];
 284 };
 285 .Ed
 286 .Pp
 287 The
 288 .Fn bt_devenum
 289 function enumerates Bluetooth devices present in the system.
 290 For every device found,
 291 the function will call provided
 292 .Fa cb
 293 callback function which should be of
 294 .Vt bt_devenum_cb_t
 295 type.
 296 The callback function is passed a
 297 .Dv HCI
 298 socket
 299 .Fa s ,
 300 fully populated
 301 .Vt bt_devinfo
 302 structure
 303 .Fa di
 304 and
 305 .Fa arg
 306 argument provided to the
 307 .Fn bt_devenum .
 308 The callback function can stop enumeration by returning a value
 309 that is greater than zero.
 310 The function returns number of successfully enumerated devices,
 311 or -1 if an error occurred.
 312 .Pp
 313 The
 314 .Fn bdaddr_same ,
 315 .Fn bdaddr_any
 316 and
 317 .Fn bdaddr_copy
 318 are handy shorthand Bluetooth address utility functions.
 319 The
 320 .Fn bdaddr_same
 321 function will test if two provided BD_ADDRs are the same.
 322 The
 323 .Fn bdaddr_any
 324 function will test if provided BD_ADDR is
 325 .Dv ANY
 326 BD_ADDR.
 327 The
 328 .Fn bdaddr_copy
 329 function will copy provided
 330 .Fa src
 331 BD_ADDR into provided
 332 .Fa dst
 333 BD_ADDR.
 334 .Sh FILES
 335 .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
 336 .It Pa /etc/bluetooth/hosts
 337 .It Pa /etc/bluetooth/protocols
 338 .El
 339 .Sh EXAMPLES
 340 Print out the hostname associated with a specific BD_ADDR:
 341 .Bd -literal -offset indent
 342 const char *bdstr = "00:01:02:03:04:05";
 343 bdaddr_t bd;
 344 struct hostent *hp;
 345
 346 if (!bt_aton(bdstr, &bd))
 347         errx(1, "can't parse BD_ADDR %s", bdstr);
 348
 349 if ((hp = bt_gethostbyaddr((const char *)&bd,
 350     sizeof(bd), AF_BLUETOOTH)) == NULL)
 351         errx(1, "no name associated with %s", bdstr);
 352
 353 printf("name associated with %s is %s\en", bdstr, hp->h_name);
 354 .Ed
 355 .Sh DIAGNOSTICS
 356 Error return status from
 357 .Fn bt_gethostent ,
 358 .Fn bt_gethostbyname
 359 and
 360 .Fn bt_gethostbyaddr
 361 is indicated by return of a
 362 .Dv NULL
 363 pointer.
 364 The external integer
 365 .Va h_errno
 366 may then be checked to see whether this is a temporary failure
 367 or an invalid or unknown host.
 368 The routine
 369 .Xr herror 3
 370 can be used to print an error message describing the failure.
 371 If its argument
 372 .Fa string
 373 is
 374 .Pf non- Dv NULL ,
 375 it is printed, followed by a colon and a space.
 376 The error message is printed with a trailing newline.
 377 .Pp
 378 The variable
 379 .Va h_errno
 380 can have the following values:
 381 .Bl -tag -width ".Dv HOST_NOT_FOUND"
 382 .It Dv HOST_NOT_FOUND
 383 No such host is known.
 384 .It Dv NO_RECOVERY
 385 Some unexpected server failure was encountered.
 386 This is a non-recoverable error.
 387 .El
 388 .Pp
 389 The
 390 .Fn bt_getprotoent ,
 391 .Fn bt_getprotobyname
 392 and
 393 .Fn bt_getprotobynumber
 394 return
 395 .Dv NULL
 396 on EOF or error.
 397 .Sh SEE ALSO
 398 .Xr gethostbyaddr 3 ,
 399 .Xr gethostbyname 3 ,
 400 .Xr getprotobyname 3 ,
 401 .Xr getprotobynumber 3 ,
 402 .Xr herror 3 ,
 403 .Xr inet_aton 3 ,
 404 .Xr inet_ntoa 3 ,
 405 .Xr ng_hci 4
 406 .Sh CAVEAT
 407 The
 408 .Fn bt_gethostent
 409 function reads the next line of
 410 .Pa /etc/bluetooth/hosts ,
 411 opening the file if necessary.
 412 .Pp
 413 The
 414 .Fn bt_sethostent
 415 function opens and/or rewinds the
 416 .Pa /etc/bluetooth/hosts
 417 file.
 418 .Pp
 419 The
 420 .Fn bt_getprotoent
 421 function reads the next line of
 422 .Pa /etc/bluetooth/protocols ,
 423 opening the file if necessary.
 424 .Pp
 425 The
 426 .Fn bt_setprotoent
 427 function opens and/or rewinds the
 428 .Pa /etc/bluetooth/protocols
 429 file.
 430 .Pp
 431 The
 432 .Fn bt_devenum
 433 function enumerates up to
 434 .Dv HCI_DEVMAX
 435 Bluetooth devices.
 436 During enumeration the
 437 .Fn bt_devenum
 438 function uses the same
 439 .Dv HCI
 440 socket.
 441 The function guarantees that the socket,
 442 passed to the callback function,
 443 will be bound and connected to the Bluetooth device being enumerated.
 444 .Sh AUTHORS
 445 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
 446 .Sh BUGS
 447 These functions use static data storage;
 448 if the data is needed for future use, it should be
 449 copied before any subsequent calls overwrite it.