xref: /freebsd/lib/libsdp/sdp.3 (revision 3193579b66fd7067f898dbc54bdea81a0e6f9bd0)
1.\" Copyright (c) 2003 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: sdp.3,v 1.1 2003/09/07 20:34:19 max Exp $
26.\" $FreeBSD$
27.\"
28.Dd September 7, 2003
29.Dt SDP 3
30.Os
31.Sh NAME
32.Nm SDP_GET8 ,
33.Nm SDP_GET16 ,
34.Nm SDP_GET32 ,
35.Nm SDP_GET64 ,
36.Nm SDP_GET128
37.Nd get SDP integer
38.Pp
39.Nm SDP_PUT8 ,
40.Nm SDP_PUT16 ,
41.Nm SDP_PUT32 ,
42.Nm SDP_PUT64 ,
43.Nm SDP_PUT128
44.Nd put SPD integer
45.Pp
46.Nm sdp_open ,
47.Nm sdp_open_local ,
48.Nm sdp_close
49.Nm sdp_error
50.Nd control SDP session
51.Pp
52.Nm sdp_search
53.Nd perform SDP query
54.Pp
55.Nm sdp_attr2desc ,
56.Nm sdp_uuid2desc
57.Nd convert numeric SDP attribute/UUID value into human readable description
58.Sh LIBRARY
59.Lb libsdp
60.Sh SYNOPSIS
61.In bluetooth.h
62.In sdp.h
63.Fn SDP_GET8 "b" "cp"
64.Fn SDP_GET16 "s" "cp"
65.Fn SDP_GET32 "l" "cp"
66.Fn SDP_GET64 "l" "cp"
67.Fn SDP_GET128 "l" "cp"
68.Fn SDP_PUT8 "b" "cp"
69.Fn SDP_PUT16 "s" "cp"
70.Fn SDP_PUT32 "l" "cp"
71.Fn SDP_PUT64 "l" "cp"
72.Fn SDP_PUT128 "l" "cp"
73.Ft void *
74.Fn sdp_open "bdaddr_t const *l" "bdaddr_t const *r"
75.Ft void *
76.Fn sdp_open_local "void"
77.Ft int32_t
78.Fn sdp_close "void *xs"
79.Ft int32_t
80.Fn sdp_error "void *xs"
81.Ft int32_t
82.Fn sdp_search "void *xs" "u_int32_t plen" "u_int16_t const *pp" "u_int32_t alen" "u_int32_t const *ap" "u_int32_t vlen" "sdp_attr_t *vp"
83.Ft char const * const
84.Fn sdp_attr2desc "u_int16_t attr"
85.Ft char const * const
86.Fn sdp_uuid2desc "u_int16_t uuid"
87.Sh DESCRIPTION
88The
89.Fn SDP_GET8 ,
90.Fn SDP_GET16 ,
91.Fn SDP_GET32 ,
92.Fn SDP_GET64
93and
94.Fn SDP_GET128
95macros are used to get byte, short, long, long long and 128-bit integer
96from the buffer pointed by
97.Vt cp
98pointer. The pointer is automatically advanced.
99.Pp
100The
101.Fn SDP_PUT8 ,
102.Fn SDP_PUT16 ,
103.Fn SDP_PUT32 ,
104.Fn SDP_PUT64
105and
106.Fn SDP_PUT128
107macros are used to put byte, short, long, long long and 128-bit integer
108into the buffer pointed by
109.Vt cp
110pointer. The pointer is automatically advanced.
111.Pp
112.Fn sdp_open
113and
114.Fn sdp_open_local
115functions each return a pointer to an opaque object describing SDP session.
116The
117.Vt l
118argument passed to
119.Fn sdp_open
120function should point to a source BD_ADDR.
121If source BD_ADDR is
122.Dv NULL
123then source address
124.Dv NG_HCI_BDADDR_ANY
125is used.
126The
127.Vt r
128argument passed to
129.Fn sdp_open
130function should point to a non
131.Dv NULL
132remote BD_ADDR.
133Remote BD_ADDR can not be
134.Dv NG_HCI_BDADDR_ANY .
135The
136.Fn sdp_open_local
137function takes no arguments and opens a connection to a local SDP server.
138.Pp
139The
140.Fn sdp_close
141function terminates active SDP session and deletes SDP session object.
142The
143.Vt xs
144parameter should point to a valid SDP session object created with
145.Fn sdp_open
146or
147.Fn sdp_open_local .
148.Pp
149The
150.Fn sdp_error
151function returns last error that is stored inside SDP session object.
152The
153.Vt xs
154parameter should point to a valid SDP session object created with
155.Fn sdp_open
156or
157.Fn sdp_open_local .
158The error value returned can be converted to a human readable message by
159calling
160.Xr strerror 3
161function.
162.Pp
163The
164.Fn sdp_search
165function is used to perform SDP Service Search Attribute Request.
166The
167.Vt xs
168parameter should point to a valid SDP session object created with
169.Fn sdp_open
170or
171.Fn sdp_open_local .
172The
173.Vt pp
174parameter is a Service Search Pattern - an array of one or more Service
175Class IDs.
176The maximum number of Service Class IDs in the array is 12.
177The
178.Vt plen
179parameter is the length of the Service Search pattern.
180The
181.Vt ap
182parameter is a Attribute ID Range List - an array of one or more SDP Attribute
183ID Range. Each attribute ID Range is encoded as a 32-bit unsigned integer data
184element, where the high order 16 bits are interpreted as the beginning
185attribute ID of the range and the low order 16 bits are interpreted as the
186ending attribute ID of the range.
187The attribute IDs contained in the Attribute ID Ranges List must be listed in
188ascending order without duplication of any attribute ID values.
189Note that all attributes may be requested by specifying a range of
1900x0000-0xFFFF.
191The
192.Vt alen
193parameter is the length of the Attribute ID Ranges List.
194The
195.Fn SDP_ATTR_RANGE "lo" "hi"
196macro can be used to prepare Attribute ID Range.
197The
198.Vt vp
199parameter should be an array of
200.Vt sdp_attr_t
201structures.
202Each
203.Vt sdp_attr_t
204structure describes single SDP attribute and defined as follows:
205.Bd -literal -offset indent
206struct sdp_attr {
207        u_int16_t        flags;
208#define SDP_ATTR_OK             (0 << 0)
209#define SDP_ATTR_INVALID        (1 << 0)
210#define SDP_ATTR_TRUNCATED      (1 << 1)
211        u_int16_t        attr;  /* SDP_ATTR_xxx */
212        u_int32_t        vlen;  /* length of the value[] in bytes */
213        u_int8_t        *value; /* base pointer */
214};
215typedef struct sdp_attr         sdp_attr_t;
216typedef struct sdp_attr *       sdp_attr_p;
217.Ed
218.Pp
219The caller of the
220.Fn sdp_search
221function is expected to prepare the array of
222.Vt sdp_attr
223structures and for each element of the array both
224.Vt vlen
225and
226.Vt value
227must be set.
228The
229.Fn sdp_search
230function will fill each
231.Vt sdp_attr_t
232structure with attribute and value, i.e. it will set
233.Vt flags ,
234.Vt attr
235and
236.Vt vlen
237fields.
238The actual value of the attribute will be copied into
239.Vt value
240buffer.
241Note: attributes are returned in the order they appear in the Service Search
242Attribute Response.
243SDP server could return several attributes for the same record.
244In this case the order of the attributes will be: all attributes for the first
245records, then all attributes for the secord record etc.
246.Pp
247The
248.Fn sdp_attr2desc
249and
250.Fn sdp_uuid2desc
251functions each take a numeric attribute ID/UUID value and convert it to a
252human readable description.
253.Sh EXAMPLES
254The following example shows how to get
255.Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST
256attribute for the
257.Dv SDP_SERVICE_CLASS_SERIAL_PORT
258service from the remote device.
259.Bd -literal -offset indent
260bdaddr_t       remote;
261u_int8_t       buffer[1024];
262void          *ss    = NULL;
263u_int16_t      serv  = SDP_SERVICE_CLASS_SERIAL_PORT;
264u_int32_t      attr  = SDP_ATTR_RANGE(
265                            SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST,
266                            SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST);
267sdp_attr_t     proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer };
268
269/* Obtain/set remote BDADDR here */
270
271if ((ss = sdp_open(NG_HCI_BDADDR_ANY, remote)) == NULL)
272        /* exit ENOMEM */
273if (sdp_error(ss) != 0)
274        /* exit spd_error(ss) */
275
276if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0)
277        /* exit sdp_error(ss) */
278
279if (proto.flags != SDP_ATTR_OK)
280        /* exit see proto.flags for details */
281
282/* If we got here then we have attribute value in proto.value */
283.Ed
284.Sh DIAGNOSTICS
285Both
286.Fn sdp_open
287and
288.Fn sdp_open_local
289will return
290.Dv NULL
291if memory allocation for the new SDP session object fails.
292If the new SDP object was created then caller is still expected to call
293.Fn sdp_error
294to check if there was connection error.
295.Pp
296The
297.Fn sdp_search
298function returns non-zero value on error.
299The caller is expected to call
300.Fn sdp_error
301to find out more about error.
302.Sh SEE ALSO
303.Xr bluetooth 3 ,
304.Xr strerror 3
305.Sh BUGS
306This is client only library for now.
307Please report bugs if found.
308.Sh AUTHORS
309.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
310