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