Sort sections in various manual pages.
[dragonfly.git] / lib / libsdp / sdp.3
CommitLineData
37f60ad1
HT
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
101The
102.Fn SDP_GET8 ,
103.Fn SDP_GET16 ,
104.Fn SDP_GET32 ,
105.Fn SDP_GET64
106and
107.Fn SDP_GET128
108macros are used to get byte, short, long, long long and 128-bit integer
109from the buffer pointed by
110.Fa cp
111pointer.
112The pointer is automatically advanced.
113.Pp
114The
115.Fn SDP_PUT8 ,
116.Fn SDP_PUT16 ,
117.Fn SDP_PUT32 ,
118.Fn SDP_PUT64
119and
120.Fn SDP_PUT128
121macros are used to put byte, short, long, long long and 128-bit integer
122into the buffer pointed by
123.Fa cp
124pointer.
125The pointer is automatically advanced.
126.Pp
127.Fn SDP_GET_UUID128
128and
129.Fn SDP_PUT_UUID128
130macros are used to get and put 128-bit UUID into the buffer pointed by
131.Fa cp
132pointer.
133The pointer is automatically advanced.
134.Pp
135The
136.Fn sdp_open
137and
138.Fn sdp_open_local
139functions each return a pointer to an opaque object describing SDP session.
140The
141.Fa l
142argument passed to
143.Fn sdp_open
144function should point to a source BD_ADDR.
145If source BD_ADDR is
146.Dv NULL
147then source address
148.Dv BDADDR_ANY
149is used.
150The
151.Fa r
152argument passed to
153.Fn sdp_open
154function should point to a
155.Pf non- Dv NULL
156remote BD_ADDR.
157Remote BD_ADDR cannot be
158.Dv BDADDR_ANY .
159The
160.Fn sdp_open_local
161function takes path to the control socket and opens a connection to a local
162SDP server.
163If path to the control socket is
164.Dv NULL
165then default
166.Pa /var/run/sdp
167path will be used.
168.Pp
169The
170.Fn sdp_close
171function terminates active SDP session and deletes SDP session object.
172The
173.Fa xs
174parameter should point to a valid SDP session object created with
175.Fn sdp_open
176or
177.Fn sdp_open_local .
178.Pp
179The
180.Fn sdp_error
181function returns last error that is stored inside SDP session object.
182The
183.Fa xs
184parameter should point to a valid SDP session object created with
185.Fn sdp_open
186or
187.Fn sdp_open_local .
188The error value returned can be converted to a human readable message by
189calling
190.Xr strerror 3
191function.
192.Pp
193The
194.Fn sdp_search
195function is used to perform SDP Service Search Attribute Request.
196The
197.Fa xs
198parameter should point to a valid SDP session object created with
199.Fn sdp_open
200or
201.Fn sdp_open_local .
202The
203.Fa pp
204parameter is a Service Search Pattern - an array of one or more Service
205Class IDs.
206The maximum number of Service Class IDs in the array is 12.
207The
208.Fa plen
209parameter is the length of the Service Search pattern.
210The
211.Fa ap
212parameter is an Attribute ID Range List - an array of one or more SDP Attribute
213ID Range.
214Each attribute ID Range is encoded as a 32-bit unsigned integer data
215element, where the high order 16 bits are interpreted as the beginning
216attribute ID of the range and the low order 16 bits are interpreted as the
217ending attribute ID of the range.
218The attribute IDs contained in the Attribute ID Ranges List must be listed in
219ascending order without duplication of any attribute ID values.
220Note that all attributes may be requested by specifying a range of
2210x0000-0xFFFF.
222The
223.Fa alen
224parameter is the length of the Attribute ID Ranges List.
225The
226.Fn SDP_ATTR_RANGE "lo" "hi"
227macro can be used to prepare Attribute ID Range.
228The
229.Fa vp
230parameter should be an array of
231.Vt sdp_attr_t
232structures.
233Each
234.Vt sdp_attr_t
235structure describes single SDP attribute and defined as follows:
236.Bd -literal -offset indent
237struct 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};
246typedef struct sdp_attr sdp_attr_t;
247typedef struct sdp_attr * sdp_attr_p;
248.Ed
249.Pp
250The caller of the
251.Fn sdp_search
252function is expected to prepare the array of
253.Vt sdp_attr
254structures and for each element of the array both
255.Va vlen
256and
257.Va value
258must be set.
259The
260.Fn sdp_search
261function will fill each
262.Vt sdp_attr_t
263structure with attribute and value, i.e., it will set
264.Va flags ,
265.Va attr
266and
267.Va vlen
268fields.
269The actual value of the attribute will be copied into
270.Va value
271buffer.
272Note: attributes are returned in the order they appear in the Service Search
273Attribute Response.
274SDP server could return several attributes for the same record.
275In this case the order of the attributes will be: all attributes for the first
276records, then all attributes for the secord record etc.
277.Pp
278The
279.Fn sdp_attr2desc
280and
281.Fn sdp_uuid2desc
282functions each take a numeric attribute ID/UUID value and convert it to a
283human readable description.
284.Pp
285The
286.Fn sdp_register_service
287function
288is used to register service with the local SDP server.
289The
290.Fa xss
291parameter should point to a valid SDP session object obtained from
292.Fn sdp_open_local .
293The
294.Fa uuid
295parameter is a SDP Service Class ID for the service to be registered.
296The
297.Fa bdaddr
298parameter should point to a valid BD_ADDR.
299The service will be only advertised if request was received by the local device
300with
301.Fa bdaddr .
302If
303.Fa bdaddr
304is set to
305.Dv BDADDR_ANY
306then the service will be advertised to any remote devices that queries for it.
307The
308.Fa data
309and
310.Fa datalen
311parameters specify data and size of the data for the service.
312Upon successful return
313.Fn sdp_register_service
314will populate
315.Fa handle
316with the SDP record handle.
317This parameter is optional and can be set to
318.Dv NULL .
319.Pp
320The
321.Fn sdp_unregister_service
322function
323is used to unregister service with the local SDP server.
324The
325.Fa xss
326parameter should point to a valid SDP session object obtained from
327.Fn sdp_open_local .
328The
329.Fa handle
330parameter should contain a valid SDP record handle of the service to be
331unregistered.
332.Pp
333The
334.Fn sdp_change_service
335function is used to change data associated with the existing service on
336the local SDP server.
337The
338.Fa xss
339parameter should point to a valid SDP session object obtained from
340.Fn sdp_open_local .
341The
342.Fa handle
343parameter should contain a valid SDP record handle of the service to be changed.
344The
345.Fa data
346and
347.Fa datalen
348parameters specify data and size of the data for the service.
349.Sh CAVEAT
350When registering services with the local SDP server the application must
351keep the SDP session open.
352If SDP session is closed then the local SDP server will remove all services
353that were registered over the session.
354The application is allowed to change or unregister service if it was registered
355over the same session.
356.Sh EXAMPLES
357The following example shows how to get
358.Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST
359attribute for the
360.Dv SDP_SERVICE_CLASS_SERIAL_PORT
361service from the remote device.
362.Bd -literal -offset indent
363bdaddr_t remote;
364uint8_t buffer[1024];
365void *ss = NULL;
366uint16_t serv = SDP_SERVICE_CLASS_SERIAL_PORT;
367uint32_t attr = SDP_ATTR_RANGE(
368 SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST,
369 SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST);
370sdp_attr_t proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer };
371
372/* Obtain/set remote BDADDR here */
373
374if ((ss = sdp_open(BDADDR_ANY, remote)) == NULL)
375 /* exit ENOMEM */
376if (sdp_error(ss) != 0)
377 /* exit sdp_error(ss) */
378
379if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0)
380 /* exit sdp_error(ss) */
381
382if (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
388Both
389.Fn sdp_open
390and
391.Fn sdp_open_local
392will return
393.Dv NULL
394if memory allocation for the new SDP session object fails.
395If the new SDP object was created then caller is still expected to call
396.Fn sdp_error
397to check if there was connection error.
398.Pp
399The
400.Fn sdp_search ,
401.Fn sdp_register_service ,
402.Fn sdp_unregister_service
403and
404.Fn sdp_change_service
405functions return non-zero value on error.
406The caller is expected to call
407.Fn sdp_error
408to find out more about error.
409.Sh SEE ALSO
37f60ad1 410.Xr sdpquery 1 ,
666855ca
SW
411.Xr strerror 3 ,
412.Xr bluetooth 4 ,
413.Xr sdpd 8
37f60ad1
HT
414.Sh HISTORY
415.Nm libsdp
416first appeared in
417.Fx ,
418was ported to
419.Nx 4.0
420by
421.An Iain Hibbert and imported into
422.Dx 1.11 .
a68e0df0
SW
423.Sh AUTHORS
424.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
425.Sh BUGS
426Most likely.
427Please report bugs if found.