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