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