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