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>