1 .\" Copyright (c) 2003 Maksim Yevmenkin <m_evmenkin@yahoo.com>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $Id: sdp.3,v 1.1 2003/09/07 20:34:19 max Exp $
52 .Nd Bluetooth SDP routines
59 .Fn SDP_GET16 "s" "cp"
60 .Fn SDP_GET32 "l" "cp"
61 .Fn SDP_GET64 "l" "cp"
62 .Fn SDP_GET128 "l" "cp"
63 .Fn SDP_GET_UUID128 "l" "cp"
65 .Fn SDP_PUT16 "s" "cp"
66 .Fn SDP_PUT32 "l" "cp"
67 .Fn SDP_PUT64 "l" "cp"
68 .Fn SDP_PUT128 "l" "cp"
69 .Fn SDP_PUT_UUID128 "l" "cp"
71 .Fn sdp_open "bdaddr_t const *l" "bdaddr_t const *r"
73 .Fn sdp_open_local "char const *control"
75 .Fn sdp_close "void *xs"
77 .Fn sdp_error "void *xs"
79 .Fn sdp_get_lcaddr "void *xs" "bdaddr_t *l"
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"
85 .Ft "char const * const"
86 .Fn sdp_attr2desc "uint16_t attr"
87 .Ft "char const * const"
88 .Fn sdp_uuid2desc "uint16_t uuid"
90 .Fo sdp_register_service
91 .Fa "void *xss" "uint16_t uuid" "bdaddr_p const bdaddr" "uint8_t const *data"
92 .Fa "uint32_t datalen" "uint32_t *handle"
95 .Fn sdp_unregister_service "void *xss" "uint32_t handle"
97 .Fo sdp_change_service
98 .Fa "void *xss" "uint32_t handle" "uint8_t const *data" "uint32_t datalen"
108 macros are used to get byte, short, long, long long and 128-bit integer
109 from the buffer pointed by
112 The pointer is automatically advanced.
121 macros are used to put byte, short, long, long long and 128-bit integer
122 into the buffer pointed by
125 The pointer is automatically advanced.
130 macros are used to get and put 128-bit UUID into the buffer pointed by
133 The pointer is automatically advanced.
139 functions each return a pointer to an opaque object describing SDP session.
144 function should point to a source BD_ADDR.
148 .Dv NG_HCI_BDADDR_ANY
154 function should point to a
157 Remote BD_ADDR cannot be
158 .Dv NG_HCI_BDADDR_ANY .
161 function takes path to the control socket and opens a connection to a local
163 If path to the control socket is
171 function terminates active SDP session and deletes SDP session object.
174 parameter should point to a valid SDP session object created with
181 function returns last error that is stored inside SDP session object.
184 parameter should point to a valid SDP session object created with
188 The error value returned can be converted to a human readable message by
195 function returns the SDP session actual source BD_ADDR.
198 parameter should point to a valid SDP session object created with
202 parameter should point to a buffer in which the value for the requested BD_ADDR
205 function is useful if the current SDP session has been opened with the
206 .Dv NG_HCI_BDADDR_ANY
207 value passed as a source address.
211 function is used to perform SDP Service Search Attribute Request.
214 parameter should point to a valid SDP session object created with
220 parameter is a Service Search Pattern - an array of one or more Service
222 The maximum number of Service Class IDs in the array is 12.
225 parameter is the length of the Service Search pattern.
228 parameter is an Attribute ID Range List - an array of one or more SDP Attribute
230 Each attribute ID Range is encoded as a 32-bit unsigned integer data
231 element, where the high order 16 bits are interpreted as the beginning
232 attribute ID of the range and the low order 16 bits are interpreted as the
233 ending attribute ID of the range.
234 The attribute IDs contained in the Attribute ID Ranges List must be listed in
235 ascending order without duplication of any attribute ID values.
236 Note that all attributes may be requested by specifying a range of
240 parameter is the length of the Attribute ID Ranges List.
242 .Fn SDP_ATTR_RANGE "lo" "hi"
243 macro can be used to prepare Attribute ID Range.
246 parameter should be an array of
251 structure describes single SDP attribute and defined as follows:
252 .Bd -literal -offset indent
255 #define SDP_ATTR_OK (0 << 0)
256 #define SDP_ATTR_INVALID (1 << 0)
257 #define SDP_ATTR_TRUNCATED (1 << 1)
258 uint16_t attr; /* SDP_ATTR_xxx */
259 uint32_t vlen; /* length of the value[] in bytes */
260 uint8_t *value; /* base pointer */
262 typedef struct sdp_attr sdp_attr_t;
263 typedef struct sdp_attr * sdp_attr_p;
268 function is expected to prepare the array of
270 structures and for each element of the array both
277 function will fill each
279 structure with attribute and value, i.e., it will set
285 The actual value of the attribute will be copied into
288 Note: attributes are returned in the order they appear in the Service Search
290 SDP server could return several attributes for the same record.
291 In this case the order of the attributes will be: all attributes for the first
292 records, then all attributes for the second record etc.
298 functions each take a numeric attribute ID/UUID value and convert it to a
299 human readable description.
302 .Fn sdp_register_service
304 is used to register service with the local SDP server.
307 parameter should point to a valid SDP session object obtained from
311 parameter is a SDP Service Class ID for the service to be registered.
314 parameter should point to a valid BD_ADDR.
315 The service will be only advertised if request was received by the local device
321 .Dv NG_HCI_BDADDR_ANY
322 then the service will be advertised to any remote devices that queries for it.
327 parameters specify data and size of the data for the service.
328 Upon successful return
329 .Fn sdp_register_service
332 with the SDP record handle.
333 This parameter is optional and can be set to
337 .Fn sdp_unregister_service
339 is used to unregister service with the local SDP server.
342 parameter should point to a valid SDP session object obtained from
346 parameter should contain a valid SDP record handle of the service to be
350 .Fn sdp_change_service
351 function is used to change data associated with the existing service on
352 the local SDP server.
355 parameter should point to a valid SDP session object obtained from
359 parameter should contain a valid SDP record handle of the service to be changed.
364 parameters specify data and size of the data for the service.
366 When registering services with the local SDP server the application must
367 keep the SDP session open.
368 If SDP session is closed then the local SDP server will remove all services
369 that were registered over the session.
370 The application is allowed to change or unregister service if it was registered
371 over the same session.
373 The following example shows how to get
374 .Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST
376 .Dv SDP_SERVICE_CLASS_SERIAL_PORT
377 service from the remote device.
378 .Bd -literal -offset indent
380 uint8_t buffer[1024];
382 uint16_t serv = SDP_SERVICE_CLASS_SERIAL_PORT;
383 uint32_t attr = SDP_ATTR_RANGE(
384 SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST,
385 SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST);
386 sdp_attr_t proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer };
388 /* Obtain/set remote BDADDR here */
390 if ((ss = sdp_open(NG_HCI_BDADDR_ANY, remote)) == NULL)
392 if (sdp_error(ss) != 0)
393 /* exit sdp_error(ss) */
395 if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0)
396 /* exit sdp_error(ss) */
398 if (proto.flags != SDP_ATTR_OK)
399 /* exit see proto.flags for details */
401 /* If we got here then we have attribute value in proto.value */
410 if memory allocation for the new SDP session object fails.
411 If the new SDP object was created then caller is still expected to call
413 to check if there was connection error.
418 .Fn sdp_register_service ,
419 .Fn sdp_unregister_service ,
421 .Fn sdp_change_service
422 functions return non-zero value on error.
423 The caller is expected to call
425 to find out more about error.
432 .An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com
435 Please report bugs if found.