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 $
51 .Nd Bluetooth SDP routines
58 .Fn SDP_GET16 "s" "cp"
59 .Fn SDP_GET32 "l" "cp"
60 .Fn SDP_GET64 "l" "cp"
61 .Fn SDP_GET128 "l" "cp"
62 .Fn SDP_GET_UUID128 "l" "cp"
64 .Fn SDP_PUT16 "s" "cp"
65 .Fn SDP_PUT32 "l" "cp"
66 .Fn SDP_PUT64 "l" "cp"
67 .Fn SDP_PUT128 "l" "cp"
68 .Fn SDP_PUT_UUID128 "l" "cp"
70 .Fn sdp_open "bdaddr_t const *l" "bdaddr_t const *r"
72 .Fn sdp_open_local "char const *control"
74 .Fn sdp_close "void *xs"
76 .Fn sdp_error "void *xs"
78 .Fn sdp_get_lcaddr "void *xs" "bdaddr_t *l"
81 .Fa "void *xs" "uint32_t plen" "uint16_t const *pp" "uint32_t alen"
82 .Fa "uint32_t const *ap" "uint32_t vlen" "sdp_attr_t *vp"
84 .Ft "char const * const"
85 .Fn sdp_attr2desc "uint16_t attr"
86 .Ft "char const * const"
87 .Fn sdp_uuid2desc "uint16_t uuid"
89 .Fo sdp_register_service
90 .Fa "void *xss" "uint16_t uuid" "bdaddr_p const bdaddr" "uint8_t const *data"
91 .Fa "uint32_t datalen" "uint32_t *handle"
94 .Fn sdp_unregister_service "void *xss" "uint32_t handle"
96 .Fo sdp_change_service
97 .Fa "void *xss" "uint32_t handle" "uint8_t const *data" "uint32_t datalen"
107 macros are used to get byte, short, long, long long and 128-bit integer
108 from the buffer pointed by
111 The pointer is automatically advanced.
120 macros are used to put byte, short, long, long long and 128-bit integer
121 into the buffer pointed by
124 The pointer is automatically advanced.
129 macros are used to get and put 128-bit UUID into the buffer pointed by
132 The pointer is automatically advanced.
138 functions each return a pointer to an opaque object describing SDP session.
143 function should point to a source BD_ADDR.
147 .Dv NG_HCI_BDADDR_ANY
153 function should point to a
156 Remote BD_ADDR cannot be
157 .Dv NG_HCI_BDADDR_ANY .
160 function takes path to the control socket and opens a connection to a local
162 If path to the control socket is
170 function terminates active SDP session and deletes SDP session object.
173 parameter should point to a valid SDP session object created with
180 function returns last error that is stored inside SDP session object.
183 parameter should point to a valid SDP session object created with
187 The error value returned can be converted to a human readable message by
194 function returns the SDP session actual source BD_ADDR.
197 parameter should point to a valid SDP session object created with
201 parameter should point to a buffer in which the value for the requested BD_ADDR
204 function is useful if the current SDP session has been opened with the
205 .Dv NG_HCI_BDADDR_ANY
206 value passed as a source address.
210 function is used to perform SDP Service Search Attribute Request.
213 parameter should point to a valid SDP session object created with
219 parameter is a Service Search Pattern - an array of one or more Service
221 The maximum number of Service Class IDs in the array is 12.
224 parameter is the length of the Service Search pattern.
227 parameter is an Attribute ID Range List - an array of one or more SDP Attribute
229 Each attribute ID Range is encoded as a 32-bit unsigned integer data
230 element, where the high order 16 bits are interpreted as the beginning
231 attribute ID of the range and the low order 16 bits are interpreted as the
232 ending attribute ID of the range.
233 The attribute IDs contained in the Attribute ID Ranges List must be listed in
234 ascending order without duplication of any attribute ID values.
235 Note that all attributes may be requested by specifying a range of
239 parameter is the length of the Attribute ID Ranges List.
241 .Fn SDP_ATTR_RANGE "lo" "hi"
242 macro can be used to prepare Attribute ID Range.
245 parameter should be an array of
250 structure describes single SDP attribute and defined as follows:
251 .Bd -literal -offset indent
254 #define SDP_ATTR_OK (0 << 0)
255 #define SDP_ATTR_INVALID (1 << 0)
256 #define SDP_ATTR_TRUNCATED (1 << 1)
257 uint16_t attr; /* SDP_ATTR_xxx */
258 uint32_t vlen; /* length of the value[] in bytes */
259 uint8_t *value; /* base pointer */
261 typedef struct sdp_attr sdp_attr_t;
262 typedef struct sdp_attr * sdp_attr_p;
267 function is expected to prepare the array of
269 structures and for each element of the array both
276 function will fill each
278 structure with attribute and value, i.e., it will set
284 The actual value of the attribute will be copied into
287 Note: attributes are returned in the order they appear in the Service Search
289 SDP server could return several attributes for the same record.
290 In this case the order of the attributes will be: all attributes for the first
291 records, then all attributes for the second record etc.
297 functions each take a numeric attribute ID/UUID value and convert it to a
298 human readable description.
301 .Fn sdp_register_service
303 is used to register service with the local SDP server.
306 parameter should point to a valid SDP session object obtained from
310 parameter is a SDP Service Class ID for the service to be registered.
313 parameter should point to a valid BD_ADDR.
314 The service will be only advertised if request was received by the local device
320 .Dv NG_HCI_BDADDR_ANY
321 then the service will be advertised to any remote devices that queries for it.
326 parameters specify data and size of the data for the service.
327 Upon successful return
328 .Fn sdp_register_service
331 with the SDP record handle.
332 This parameter is optional and can be set to
336 .Fn sdp_unregister_service
338 is used to unregister service with the local SDP server.
341 parameter should point to a valid SDP session object obtained from
345 parameter should contain a valid SDP record handle of the service to be
349 .Fn sdp_change_service
350 function is used to change data associated with the existing service on
351 the local SDP server.
354 parameter should point to a valid SDP session object obtained from
358 parameter should contain a valid SDP record handle of the service to be changed.
363 parameters specify data and size of the data for the service.
365 When registering services with the local SDP server the application must
366 keep the SDP session open.
367 If SDP session is closed then the local SDP server will remove all services
368 that were registered over the session.
369 The application is allowed to change or unregister service if it was registered
370 over the same session.
372 The following example shows how to get
373 .Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST
375 .Dv SDP_SERVICE_CLASS_SERIAL_PORT
376 service from the remote device.
377 .Bd -literal -offset indent
379 uint8_t buffer[1024];
381 uint16_t serv = SDP_SERVICE_CLASS_SERIAL_PORT;
382 uint32_t attr = SDP_ATTR_RANGE(
383 SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST,
384 SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST);
385 sdp_attr_t proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer };
387 /* Obtain/set remote BDADDR here */
389 if ((ss = sdp_open(NG_HCI_BDADDR_ANY, remote)) == NULL)
391 if (sdp_error(ss) != 0)
392 /* exit sdp_error(ss) */
394 if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0)
395 /* exit sdp_error(ss) */
397 if (proto.flags != SDP_ATTR_OK)
398 /* exit see proto.flags for details */
400 /* If we got here then we have attribute value in proto.value */
409 if memory allocation for the new SDP session object fails.
410 If the new SDP object was created then caller is still expected to call
412 to check if there was connection error.
417 .Fn sdp_register_service ,
418 .Fn sdp_unregister_service ,
420 .Fn sdp_change_service
421 functions return non-zero value on error.
422 The caller is expected to call
424 to find out more about error.
431 .An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com
434 Please report bugs if found.