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 .\" 27 .Dd April 30, 2018 28 .Dt SDP 3 29 .Os 30 .Sh NAME 31 .Nm SDP_GET8 , 32 .Nm SDP_GET16 , 33 .Nm SDP_GET32 , 34 .Nm SDP_GET64 , 35 .Nm SDP_GET128 , 36 .Nm SDP_GET_UUID128 , 37 .Nm SDP_PUT8 , 38 .Nm SDP_PUT16 , 39 .Nm SDP_PUT32 , 40 .Nm SDP_PUT64 , 41 .Nm SDP_PUT128 , 42 .Nm SDP_PUT_UUID128 , 43 .Nm sdp_open , 44 .Nm sdp_open_local , 45 .Nm sdp_close , 46 .Nm sdp_error , 47 .Nm sdp_get_lcaddr , 48 .Nm sdp_search , 49 .Nm sdp_attr2desc , 50 .Nm sdp_uuid2desc 51 .Nd Bluetooth SDP routines 52 .Sh LIBRARY 53 .Lb libsdp 54 .Sh SYNOPSIS 55 .In bluetooth.h 56 .In sdp.h 57 .Fn SDP_GET8 "b" "cp" 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" 63 .Fn SDP_PUT8 "b" "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" 69 .Ft "void *" 70 .Fn sdp_open "bdaddr_t const *l" "bdaddr_t const *r" 71 .Ft "void *" 72 .Fn sdp_open_local "char const *control" 73 .Ft int32_t 74 .Fn sdp_close "void *xs" 75 .Ft int32_t 76 .Fn sdp_error "void *xs" 77 .Ft int32_t 78 .Fn sdp_get_lcaddr "void *xs" "bdaddr_t *l" 79 .Ft int32_t 80 .Fo sdp_search 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" 83 .Fc 84 .Ft "char const * const" 85 .Fn sdp_attr2desc "uint16_t attr" 86 .Ft "char const * const" 87 .Fn sdp_uuid2desc "uint16_t uuid" 88 .Ft int32_t 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" 92 .Fc 93 .Ft int32_t 94 .Fn sdp_unregister_service "void *xss" "uint32_t handle" 95 .Ft int32_t 96 .Fo sdp_change_service 97 .Fa "void *xss" "uint32_t handle" "uint8_t const *data" "uint32_t datalen" 98 .Fc 99 .Sh DESCRIPTION 100 The 101 .Fn SDP_GET8 , 102 .Fn SDP_GET16 , 103 .Fn SDP_GET32 , 104 .Fn SDP_GET64 105 and 106 .Fn SDP_GET128 107 macros are used to get byte, short, long, long long and 128-bit integer 108 from the buffer pointed by 109 .Fa cp 110 pointer. 111 The pointer is automatically advanced. 112 .Pp 113 The 114 .Fn SDP_PUT8 , 115 .Fn SDP_PUT16 , 116 .Fn SDP_PUT32 , 117 .Fn SDP_PUT64 118 and 119 .Fn SDP_PUT128 120 macros are used to put byte, short, long, long long and 128-bit integer 121 into the buffer pointed by 122 .Fa cp 123 pointer. 124 The pointer is automatically advanced. 125 .Pp 126 .Fn SDP_GET_UUID128 127 and 128 .Fn SDP_PUT_UUID128 129 macros are used to get and put 128-bit UUID into the buffer pointed by 130 .Fa cp 131 pointer. 132 The pointer is automatically advanced. 133 .Pp 134 The 135 .Fn sdp_open 136 and 137 .Fn sdp_open_local 138 functions each return a pointer to an opaque object describing SDP session. 139 The 140 .Fa l 141 argument passed to 142 .Fn sdp_open 143 function should point to a source BD_ADDR. 144 If source BD_ADDR is 145 .Dv NULL 146 then source address 147 .Dv NG_HCI_BDADDR_ANY 148 is used. 149 The 150 .Fa r 151 argument passed to 152 .Fn sdp_open 153 function should point to a 154 .Pf non- Dv NULL 155 remote BD_ADDR. 156 Remote BD_ADDR cannot be 157 .Dv NG_HCI_BDADDR_ANY . 158 The 159 .Fn sdp_open_local 160 function takes path to the control socket and opens a connection to a local 161 SDP server. 162 If path to the control socket is 163 .Dv NULL 164 then default 165 .Pa /var/run/sdp 166 path will be used. 167 .Pp 168 The 169 .Fn sdp_close 170 function terminates active SDP session and deletes SDP session object. 171 The 172 .Fa xs 173 parameter should point to a valid SDP session object created with 174 .Fn sdp_open 175 or 176 .Fn sdp_open_local . 177 .Pp 178 The 179 .Fn sdp_error 180 function returns last error that is stored inside SDP session object. 181 The 182 .Fa xs 183 parameter should point to a valid SDP session object created with 184 .Fn sdp_open 185 or 186 .Fn sdp_open_local . 187 The error value returned can be converted to a human readable message by 188 calling 189 .Xr strerror 3 190 function. 191 .Pp 192 The 193 .Fn sdp_get_lcaddr 194 function returns the SDP session actual source BD_ADDR. 195 The 196 .Fa xs 197 parameter should point to a valid SDP session object created with 198 .Fn sdp_open . 199 The 200 .Fa l 201 parameter should point to a buffer in which the value for the requested BD_ADDR 202 is to be returned. 203 .Fn sdp_get_lcaddr 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. 207 .Pp 208 The 209 .Fn sdp_search 210 function is used to perform SDP Service Search Attribute Request. 211 The 212 .Fa xs 213 parameter should point to a valid SDP session object created with 214 .Fn sdp_open 215 or 216 .Fn sdp_open_local . 217 The 218 .Fa pp 219 parameter is a Service Search Pattern - an array of one or more Service 220 Class IDs. 221 The maximum number of Service Class IDs in the array is 12. 222 The 223 .Fa plen 224 parameter is the length of the Service Search pattern. 225 The 226 .Fa ap 227 parameter is an Attribute ID Range List - an array of one or more SDP Attribute 228 ID Range. 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 236 0x0000-0xFFFF. 237 The 238 .Fa alen 239 parameter is the length of the Attribute ID Ranges List. 240 The 241 .Fn SDP_ATTR_RANGE "lo" "hi" 242 macro can be used to prepare Attribute ID Range. 243 The 244 .Fa vp 245 parameter should be an array of 246 .Vt sdp_attr_t 247 structures. 248 Each 249 .Vt sdp_attr_t 250 structure describes single SDP attribute and defined as follows: 251 .Bd -literal -offset indent 252 struct sdp_attr { 253 uint16_t flags; 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 */ 260 }; 261 typedef struct sdp_attr sdp_attr_t; 262 typedef struct sdp_attr * sdp_attr_p; 263 .Ed 264 .Pp 265 The caller of the 266 .Fn sdp_search 267 function is expected to prepare the array of 268 .Vt sdp_attr 269 structures and for each element of the array both 270 .Va vlen 271 and 272 .Va value 273 must be set. 274 The 275 .Fn sdp_search 276 function will fill each 277 .Vt sdp_attr_t 278 structure with attribute and value, i.e., it will set 279 .Va flags , 280 .Va attr 281 and 282 .Va vlen 283 fields. 284 The actual value of the attribute will be copied into 285 .Va value 286 buffer. 287 Note: attributes are returned in the order they appear in the Service Search 288 Attribute Response. 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. 292 .Pp 293 The 294 .Fn sdp_attr2desc 295 and 296 .Fn sdp_uuid2desc 297 functions each take a numeric attribute ID/UUID value and convert it to a 298 human readable description. 299 .Pp 300 The 301 .Fn sdp_register_service 302 function 303 is used to register service with the local SDP server. 304 The 305 .Fa xss 306 parameter should point to a valid SDP session object obtained from 307 .Fn sdp_open_local . 308 The 309 .Fa uuid 310 parameter is a SDP Service Class ID for the service to be registered. 311 The 312 .Fa bdaddr 313 parameter should point to a valid BD_ADDR. 314 The service will be only advertised if request was received by the local device 315 with 316 .Fa bdaddr . 317 If 318 .Fa bdaddr 319 is set to 320 .Dv NG_HCI_BDADDR_ANY 321 then the service will be advertised to any remote devices that queries for it. 322 The 323 .Fa data 324 and 325 .Fa datalen 326 parameters specify data and size of the data for the service. 327 Upon successful return 328 .Fn sdp_register_service 329 will populate 330 .Fa handle 331 with the SDP record handle. 332 This parameter is optional and can be set to 333 .Dv NULL . 334 .Pp 335 The 336 .Fn sdp_unregister_service 337 function 338 is used to unregister service with the local SDP server. 339 The 340 .Fa xss 341 parameter should point to a valid SDP session object obtained from 342 .Fn sdp_open_local . 343 The 344 .Fa handle 345 parameter should contain a valid SDP record handle of the service to be 346 unregistered. 347 .Pp 348 The 349 .Fn sdp_change_service 350 function is used to change data associated with the existing service on 351 the local SDP server. 352 The 353 .Fa xss 354 parameter should point to a valid SDP session object obtained from 355 .Fn sdp_open_local . 356 The 357 .Fa handle 358 parameter should contain a valid SDP record handle of the service to be changed. 359 The 360 .Fa data 361 and 362 .Fa datalen 363 parameters specify data and size of the data for the service. 364 .Sh CAVEAT 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. 371 .Sh EXAMPLES 372 The following example shows how to get 373 .Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST 374 attribute for the 375 .Dv SDP_SERVICE_CLASS_SERIAL_PORT 376 service from the remote device. 377 .Bd -literal -offset indent 378 bdaddr_t remote; 379 uint8_t buffer[1024]; 380 void *ss = NULL; 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 }; 386 387 /* Obtain/set remote BDADDR here */ 388 389 if ((ss = sdp_open(NG_HCI_BDADDR_ANY, remote)) == NULL) 390 /* exit ENOMEM */ 391 if (sdp_error(ss) != 0) 392 /* exit sdp_error(ss) */ 393 394 if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0) 395 /* exit sdp_error(ss) */ 396 397 if (proto.flags != SDP_ATTR_OK) 398 /* exit see proto.flags for details */ 399 400 /* If we got here then we have attribute value in proto.value */ 401 .Ed 402 .Sh DIAGNOSTICS 403 Both 404 .Fn sdp_open 405 and 406 .Fn sdp_open_local 407 will return 408 .Dv NULL 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 411 .Fn sdp_error 412 to check if there was connection error. 413 .Pp 414 The 415 .Fn sdp_get_lcaddr , 416 .Fn sdp_search , 417 .Fn sdp_register_service , 418 .Fn sdp_unregister_service , 419 and 420 .Fn sdp_change_service 421 functions return non-zero value on error. 422 The caller is expected to call 423 .Fn sdp_error 424 to find out more about error. 425 .Sh SEE ALSO 426 .Xr bluetooth 3 , 427 .Xr strerror 3 , 428 .Xr sdpcontrol 8 , 429 .Xr sdpd 8 430 .Sh AUTHORS 431 .An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com 432 .Sh BUGS 433 Most likely. 434 Please report bugs if found. 435