9c1b2b2dc01f3190bad7cfe7ab8e591f7ce39fad
[dragonfly.git] / lib / libsdp / sdp.3
1 .\" $NetBSD: sdp.3,v 1.1 2006/06/19 15:44:36 gdamore Exp $
2 .\" $DragonFly: src/lib/libsdp/sdp.3,v 1.1 2008/01/03 11:47:53 hasso Exp $
3 .\"
4 .\" Copyright (c) 2003 Maksim Yevmenkin <m_evmenkin@yahoo.com>
5 .\" All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\"    notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\" $Id: sdp.3,v 1.1 2006/06/19 15:44:36 gdamore Exp $
29 .\" $FreeBSD: src/lib/libsdp/sdp.3,v 1.10 2005/06/15 19:04:04 ru Exp $
30 .\"
31 .Dd May 27, 2005
32 .Dt SDP 3
33 .Os
34 .Sh NAME
35 .Nm SDP_GET8 ,
36 .Nm SDP_GET16 ,
37 .Nm SDP_GET32 ,
38 .Nm SDP_GET64 ,
39 .Nm SDP_GET128 ,
40 .Nm SDP_GET_UUID128 ,
41 .Nm SDP_PUT8 ,
42 .Nm SDP_PUT16 ,
43 .Nm SDP_PUT32 ,
44 .Nm SDP_PUT64 ,
45 .Nm SDP_PUT128 ,
46 .Nm SDP_PUT_UUID128 ,
47 .Nm sdp_open ,
48 .Nm sdp_open_local ,
49 .Nm sdp_close ,
50 .Nm sdp_error ,
51 .Nm sdp_search ,
52 .Nm sdp_attr2desc ,
53 .Nm sdp_uuid2desc
54 .Nd Bluetooth SDP routines
55 .Sh LIBRARY
56 .Lb libsdp
57 .Sh SYNOPSIS
58 .In bluetooth.h
59 .In sdp.h
60 .Fn SDP_GET8 "b" "cp"
61 .Fn SDP_GET16 "s" "cp"
62 .Fn SDP_GET32 "l" "cp"
63 .Fn SDP_GET64 "l" "cp"
64 .Fn SDP_GET128 "l" "cp"
65 .Fn SDP_GET_UUID128 "l" "cp"
66 .Fn SDP_PUT8 "b" "cp"
67 .Fn SDP_PUT16 "s" "cp"
68 .Fn SDP_PUT32 "l" "cp"
69 .Fn SDP_PUT64 "l" "cp"
70 .Fn SDP_PUT128 "l" "cp"
71 .Fn SDP_PUT_UUID128 "l" "cp"
72 .Ft "void *"
73 .Fn sdp_open "bdaddr_t const *l" "bdaddr_t const *r"
74 .Ft "void *"
75 .Fn sdp_open_local "char const *control"
76 .Ft int32_t
77 .Fn sdp_close "void *xs"
78 .Ft int32_t
79 .Fn sdp_error "void *xs"
80 .Ft int32_t
81 .Fo sdp_search
82 .Fa "void *xs" "uint32_t plen" "uint16_t const *pp" "uint32_t alen"
83 .Fa "uint32_t const *ap" "uint32_t vlen" "sdp_attr_t *vp"
84 .Fc
85 .Ft "char const * const"
86 .Fn sdp_attr2desc "uint16_t attr"
87 .Ft "char const * const"
88 .Fn sdp_uuid2desc "uint16_t uuid"
89 .Ft int32_t
90 .Fo sdp_register_service
91 .Fa "void *xss" "uint16_t uuid" "bdaddr_t const *bdaddr" "uint8_t const *data"
92 .Fa "uint32_t datalen" "uint32_t *handle"
93 .Fc
94 .Ft int32_t
95 .Fn sdp_unregister_service "void *xss" "uint32_t handle"
96 .Ft int32_t
97 .Fo sdp_change_service
98 .Fa "void *xss" "uint32_t handle" "uint8_t const *data" "uint32_t datalen"
99 .Fc
100 .Sh DESCRIPTION
101 The
102 .Fn SDP_GET8 ,
103 .Fn SDP_GET16 ,
104 .Fn SDP_GET32 ,
105 .Fn SDP_GET64
106 and
107 .Fn SDP_GET128
108 macros are used to get byte, short, long, long long and 128-bit integer
109 from the buffer pointed by
110 .Fa cp
111 pointer.
112 The pointer is automatically advanced.
113 .Pp
114 The
115 .Fn SDP_PUT8 ,
116 .Fn SDP_PUT16 ,
117 .Fn SDP_PUT32 ,
118 .Fn SDP_PUT64
119 and
120 .Fn SDP_PUT128
121 macros are used to put byte, short, long, long long and 128-bit integer
122 into the buffer pointed by
123 .Fa cp
124 pointer.
125 The pointer is automatically advanced.
126 .Pp
127 .Fn SDP_GET_UUID128
128 and
129 .Fn SDP_PUT_UUID128
130 macros are used to get and put 128-bit UUID into the buffer pointed by
131 .Fa cp
132 pointer.
133 The pointer is automatically advanced.
134 .Pp
135 The
136 .Fn sdp_open
137 and
138 .Fn sdp_open_local
139 functions each return a pointer to an opaque object describing SDP session.
140 The
141 .Fa l
142 argument passed to
143 .Fn sdp_open
144 function should point to a source BD_ADDR.
145 If source BD_ADDR is
146 .Dv NULL
147 then source address
148 .Dv BDADDR_ANY
149 is used.
150 The
151 .Fa r
152 argument passed to
153 .Fn sdp_open
154 function should point to a
155 .Pf non- Dv NULL
156 remote BD_ADDR.
157 Remote BD_ADDR cannot be
158 .Dv BDADDR_ANY .
159 The
160 .Fn sdp_open_local
161 function takes path to the control socket and opens a connection to a local
162 SDP server.
163 If path to the control socket is
164 .Dv NULL
165 then default
166 .Pa /var/run/sdp
167 path will be used.
168 .Pp
169 The
170 .Fn sdp_close
171 function terminates active SDP session and deletes SDP session object.
172 The
173 .Fa xs
174 parameter should point to a valid SDP session object created with
175 .Fn sdp_open
176 or
177 .Fn sdp_open_local .
178 .Pp
179 The
180 .Fn sdp_error
181 function returns last error that is stored inside SDP session object.
182 The
183 .Fa xs
184 parameter should point to a valid SDP session object created with
185 .Fn sdp_open
186 or
187 .Fn sdp_open_local .
188 The error value returned can be converted to a human readable message by
189 calling
190 .Xr strerror 3
191 function.
192 .Pp
193 The
194 .Fn sdp_search
195 function is used to perform SDP Service Search Attribute Request.
196 The
197 .Fa xs
198 parameter should point to a valid SDP session object created with
199 .Fn sdp_open
200 or
201 .Fn sdp_open_local .
202 The
203 .Fa pp
204 parameter is a Service Search Pattern - an array of one or more Service
205 Class IDs.
206 The maximum number of Service Class IDs in the array is 12.
207 The
208 .Fa plen
209 parameter is the length of the Service Search pattern.
210 The
211 .Fa ap
212 parameter is an Attribute ID Range List - an array of one or more SDP Attribute
213 ID Range.
214 Each attribute ID Range is encoded as a 32-bit unsigned integer data
215 element, where the high order 16 bits are interpreted as the beginning
216 attribute ID of the range and the low order 16 bits are interpreted as the
217 ending attribute ID of the range.
218 The attribute IDs contained in the Attribute ID Ranges List must be listed in
219 ascending order without duplication of any attribute ID values.
220 Note that all attributes may be requested by specifying a range of
221 0x0000-0xFFFF.
222 The
223 .Fa alen
224 parameter is the length of the Attribute ID Ranges List.
225 The
226 .Fn SDP_ATTR_RANGE "lo" "hi"
227 macro can be used to prepare Attribute ID Range.
228 The
229 .Fa vp
230 parameter should be an array of
231 .Vt sdp_attr_t
232 structures.
233 Each
234 .Vt sdp_attr_t
235 structure describes single SDP attribute and defined as follows:
236 .Bd -literal -offset indent
237 struct sdp_attr {
238         uint16_t        flags;
239 #define SDP_ATTR_OK             (0 << 0)
240 #define SDP_ATTR_INVALID        (1 << 0)
241 #define SDP_ATTR_TRUNCATED      (1 << 1)
242         uint16_t        attr;  /* SDP_ATTR_xxx */
243         uint32_t        vlen;  /* length of the value[] in bytes */
244         uint8_t        *value; /* base pointer */
245 };
246 typedef struct sdp_attr         sdp_attr_t;
247 typedef struct sdp_attr *       sdp_attr_p;
248 .Ed
249 .Pp
250 The caller of the
251 .Fn sdp_search
252 function is expected to prepare the array of
253 .Vt sdp_attr
254 structures and for each element of the array both
255 .Va vlen
256 and
257 .Va value
258 must be set.
259 The
260 .Fn sdp_search
261 function will fill each
262 .Vt sdp_attr_t
263 structure with attribute and value, i.e., it will set
264 .Va flags ,
265 .Va attr
266 and
267 .Va vlen
268 fields.
269 The actual value of the attribute will be copied into
270 .Va value
271 buffer.
272 Note: attributes are returned in the order they appear in the Service Search
273 Attribute Response.
274 SDP server could return several attributes for the same record.
275 In this case the order of the attributes will be: all attributes for the first
276 records, then all attributes for the secord record etc.
277 .Pp
278 The
279 .Fn sdp_attr2desc
280 and
281 .Fn sdp_uuid2desc
282 functions each take a numeric attribute ID/UUID value and convert it to a
283 human readable description.
284 .Pp
285 The
286 .Fn sdp_register_service
287 function
288 is used to register service with the local SDP server.
289 The
290 .Fa xss
291 parameter should point to a valid SDP session object obtained from
292 .Fn sdp_open_local .
293 The
294 .Fa uuid
295 parameter is a SDP Service Class ID for the service to be registered.
296 The
297 .Fa bdaddr
298 parameter should point to a valid BD_ADDR.
299 The service will be only advertised if request was received by the local device
300 with
301 .Fa bdaddr .
302 If
303 .Fa bdaddr
304 is set to
305 .Dv BDADDR_ANY
306 then the service will be advertised to any remote devices that queries for it.
307 The
308 .Fa data
309 and
310 .Fa datalen
311 parameters specify data and size of the data for the service.
312 Upon successful return
313 .Fn sdp_register_service
314 will populate
315 .Fa handle
316 with the SDP record handle.
317 This parameter is optional and can be set to
318 .Dv NULL .
319 .Pp
320 The
321 .Fn sdp_unregister_service
322 function
323 is used to unregister service with the local SDP server.
324 The
325 .Fa xss
326 parameter should point to a valid SDP session object obtained from
327 .Fn sdp_open_local .
328 The
329 .Fa handle
330 parameter should contain a valid SDP record handle of the service to be
331 unregistered.
332 .Pp
333 The
334 .Fn sdp_change_service
335 function is used to change data associated with the existing service on
336 the local SDP server.
337 The
338 .Fa xss
339 parameter should point to a valid SDP session object obtained from
340 .Fn sdp_open_local .
341 The
342 .Fa handle
343 parameter should contain a valid SDP record handle of the service to be changed.
344 The
345 .Fa data
346 and
347 .Fa datalen
348 parameters specify data and size of the data for the service.
349 .Sh CAVEAT
350 When registering services with the local SDP server the application must
351 keep the SDP session open.
352 If SDP session is closed then the local SDP server will remove all services
353 that were registered over the session.
354 The application is allowed to change or unregister service if it was registered
355 over the same session.
356 .Sh EXAMPLES
357 The following example shows how to get
358 .Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST
359 attribute for the
360 .Dv SDP_SERVICE_CLASS_SERIAL_PORT
361 service from the remote device.
362 .Bd -literal -offset indent
363 bdaddr_t       remote;
364 uint8_t        buffer[1024];
365 void          *ss    = NULL;
366 uint16_t       serv  = SDP_SERVICE_CLASS_SERIAL_PORT;
367 uint32_t       attr  = SDP_ATTR_RANGE(
368                             SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST,
369                             SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST);
370 sdp_attr_t     proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer };
371
372 /* Obtain/set remote BDADDR here */
373
374 if ((ss = sdp_open(BDADDR_ANY, remote)) == NULL)
375         /* exit ENOMEM */
376 if (sdp_error(ss) != 0)
377         /* exit sdp_error(ss) */
378
379 if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0)
380         /* exit sdp_error(ss) */
381
382 if (proto.flags != SDP_ATTR_OK)
383         /* exit see proto.flags for details */
384
385 /* If we got here then we have attribute value in proto.value */
386 .Ed
387 .Sh DIAGNOSTICS
388 Both
389 .Fn sdp_open
390 and
391 .Fn sdp_open_local
392 will return
393 .Dv NULL
394 if memory allocation for the new SDP session object fails.
395 If the new SDP object was created then caller is still expected to call
396 .Fn sdp_error
397 to check if there was connection error.
398 .Pp
399 The
400 .Fn sdp_search ,
401 .Fn sdp_register_service ,
402 .Fn sdp_unregister_service
403 and
404 .Fn sdp_change_service
405 functions return non-zero value on error.
406 The caller is expected to call
407 .Fn sdp_error
408 to find out more about error.
409 .Sh SEE ALSO
410 .Xr sdpquery 1 ,
411 .Xr strerror 3 ,
412 .Xr bluetooth 4 ,
413 .Xr sdpd 8
414 .Sh AUTHORS
415 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
416 .Sh BUGS
417 Most likely.
418 Please report bugs if found.
419 .Sh HISTORY
420 .Nm libsdp
421 first appeared in
422 .Fx ,
423 was ported to
424 .Nx 4.0
425 by
426 .An Iain Hibbert and imported into
427 .Dx 1.11 .