1.\" $NetBSD: sdp.3,v 1.1 2006/06/19 15:44:36 gdamore Exp $ 2.\" 3.\" Copyright (c) 2003 Maksim Yevmenkin <m_evmenkin@yahoo.com> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $Id: sdp.3,v 1.1 2006/06/19 15:44:36 gdamore Exp $ 28.\" $FreeBSD: src/lib/libsdp/sdp.3,v 1.10 2005/06/15 19:04:04 ru Exp $ 29.\" 30.Dd May 27, 2005 31.Dt SDP 3 32.Os 33.Sh NAME 34.Nm SDP_GET8 , 35.Nm SDP_GET16 , 36.Nm SDP_GET32 , 37.Nm SDP_GET64 , 38.Nm SDP_GET128 , 39.Nm SDP_GET_UUID128 , 40.Nm SDP_PUT8 , 41.Nm SDP_PUT16 , 42.Nm SDP_PUT32 , 43.Nm SDP_PUT64 , 44.Nm SDP_PUT128 , 45.Nm SDP_PUT_UUID128 , 46.Nm sdp_open , 47.Nm sdp_open_local , 48.Nm sdp_close , 49.Nm sdp_error , 50.Nm sdp_search , 51.Nm sdp_attr2desc , 52.Nm sdp_uuid2desc 53.Nd Bluetooth SDP routines 54.Sh LIBRARY 55.Lb libsdp 56.Sh SYNOPSIS 57.In bluetooth.h 58.In sdp.h 59.Fn SDP_GET8 "b" "cp" 60.Fn SDP_GET16 "s" "cp" 61.Fn SDP_GET32 "l" "cp" 62.Fn SDP_GET64 "l" "cp" 63.Fn SDP_GET128 "l" "cp" 64.Fn SDP_GET_UUID128 "l" "cp" 65.Fn SDP_PUT8 "b" "cp" 66.Fn SDP_PUT16 "s" "cp" 67.Fn SDP_PUT32 "l" "cp" 68.Fn SDP_PUT64 "l" "cp" 69.Fn SDP_PUT128 "l" "cp" 70.Fn SDP_PUT_UUID128 "l" "cp" 71.Ft "void *" 72.Fn sdp_open "bdaddr_t const *l" "bdaddr_t const *r" 73.Ft "void *" 74.Fn sdp_open_local "char const *control" 75.Ft int32_t 76.Fn sdp_close "void *xs" 77.Ft int32_t 78.Fn sdp_error "void *xs" 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_t 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 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 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_search 194function is used to perform SDP Service Search Attribute Request. 195The 196.Fa xs 197parameter should point to a valid SDP session object created with 198.Fn sdp_open 199or 200.Fn sdp_open_local . 201The 202.Fa pp 203parameter is a Service Search Pattern - an array of one or more Service 204Class IDs. 205The maximum number of Service Class IDs in the array is 12. 206The 207.Fa plen 208parameter is the length of the Service Search pattern. 209The 210.Fa ap 211parameter is an Attribute ID Range List - an array of one or more SDP Attribute 212ID Range. 213Each attribute ID Range is encoded as a 32-bit unsigned integer data 214element, where the high order 16 bits are interpreted as the beginning 215attribute ID of the range and the low order 16 bits are interpreted as the 216ending attribute ID of the range. 217The attribute IDs contained in the Attribute ID Ranges List must be listed in 218ascending order without duplication of any attribute ID values. 219Note that all attributes may be requested by specifying a range of 2200x0000-0xFFFF. 221The 222.Fa alen 223parameter is the length of the Attribute ID Ranges List. 224The 225.Fn SDP_ATTR_RANGE "lo" "hi" 226macro can be used to prepare Attribute ID Range. 227The 228.Fa vp 229parameter should be an array of 230.Vt sdp_attr_t 231structures. 232Each 233.Vt sdp_attr_t 234structure describes single SDP attribute and defined as follows: 235.Bd -literal -offset indent 236struct sdp_attr { 237 uint16_t flags; 238#define SDP_ATTR_OK (0 << 0) 239#define SDP_ATTR_INVALID (1 << 0) 240#define SDP_ATTR_TRUNCATED (1 << 1) 241 uint16_t attr; /* SDP_ATTR_xxx */ 242 uint32_t vlen; /* length of the value[] in bytes */ 243 uint8_t *value; /* base pointer */ 244}; 245typedef struct sdp_attr sdp_attr_t; 246typedef struct sdp_attr * sdp_attr_p; 247.Ed 248.Pp 249The caller of the 250.Fn sdp_search 251function is expected to prepare the array of 252.Vt sdp_attr 253structures and for each element of the array both 254.Va vlen 255and 256.Va value 257must be set. 258The 259.Fn sdp_search 260function will fill each 261.Vt sdp_attr_t 262structure with attribute and value, i.e., it will set 263.Va flags , 264.Va attr 265and 266.Va vlen 267fields. 268The actual value of the attribute will be copied into 269.Va value 270buffer. 271Note: attributes are returned in the order they appear in the Service Search 272Attribute Response. 273SDP server could return several attributes for the same record. 274In this case the order of the attributes will be: all attributes for the first 275records, then all attributes for the secord record etc. 276.Pp 277The 278.Fn sdp_attr2desc 279and 280.Fn sdp_uuid2desc 281functions each take a numeric attribute ID/UUID value and convert it to a 282human readable description. 283.Pp 284The 285.Fn sdp_register_service 286function 287is used to register service with the local SDP server. 288The 289.Fa xss 290parameter should point to a valid SDP session object obtained from 291.Fn sdp_open_local . 292The 293.Fa uuid 294parameter is a SDP Service Class ID for the service to be registered. 295The 296.Fa bdaddr 297parameter should point to a valid BD_ADDR. 298The service will be only advertised if request was received by the local device 299with 300.Fa bdaddr . 301If 302.Fa bdaddr 303is set to 304.Dv BDADDR_ANY 305then the service will be advertised to any remote devices that queries for it. 306The 307.Fa data 308and 309.Fa datalen 310parameters specify data and size of the data for the service. 311Upon successful return 312.Fn sdp_register_service 313will populate 314.Fa handle 315with the SDP record handle. 316This parameter is optional and can be set to 317.Dv NULL . 318.Pp 319The 320.Fn sdp_unregister_service 321function 322is used to unregister service with the local SDP server. 323The 324.Fa xss 325parameter should point to a valid SDP session object obtained from 326.Fn sdp_open_local . 327The 328.Fa handle 329parameter should contain a valid SDP record handle of the service to be 330unregistered. 331.Pp 332The 333.Fn sdp_change_service 334function is used to change data associated with the existing service on 335the local SDP server. 336The 337.Fa xss 338parameter should point to a valid SDP session object obtained from 339.Fn sdp_open_local . 340The 341.Fa handle 342parameter should contain a valid SDP record handle of the service to be changed. 343The 344.Fa data 345and 346.Fa datalen 347parameters specify data and size of the data for the service. 348.Sh CAVEAT 349When registering services with the local SDP server the application must 350keep the SDP session open. 351If SDP session is closed then the local SDP server will remove all services 352that were registered over the session. 353The application is allowed to change or unregister service if it was registered 354over the same session. 355.Sh EXAMPLES 356The following example shows how to get 357.Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST 358attribute for the 359.Dv SDP_SERVICE_CLASS_SERIAL_PORT 360service from the remote device. 361.Bd -literal -offset indent 362bdaddr_t remote; 363uint8_t buffer[1024]; 364void *ss = NULL; 365uint16_t serv = SDP_SERVICE_CLASS_SERIAL_PORT; 366uint32_t attr = SDP_ATTR_RANGE( 367 SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST, 368 SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST); 369sdp_attr_t proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer }; 370 371/* Obtain/set remote BDADDR here */ 372 373if ((ss = sdp_open(BDADDR_ANY, remote)) == NULL) 374 /* exit ENOMEM */ 375if (sdp_error(ss) != 0) 376 /* exit sdp_error(ss) */ 377 378if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0) 379 /* exit sdp_error(ss) */ 380 381if (proto.flags != SDP_ATTR_OK) 382 /* exit see proto.flags for details */ 383 384/* If we got here then we have attribute value in proto.value */ 385.Ed 386.Sh DIAGNOSTICS 387Both 388.Fn sdp_open 389and 390.Fn sdp_open_local 391will return 392.Dv NULL 393if memory allocation for the new SDP session object fails. 394If the new SDP object was created then caller is still expected to call 395.Fn sdp_error 396to check if there was connection error. 397.Pp 398The 399.Fn sdp_search , 400.Fn sdp_register_service , 401.Fn sdp_unregister_service 402and 403.Fn sdp_change_service 404functions return non-zero value on error. 405The caller is expected to call 406.Fn sdp_error 407to find out more about error. 408.Sh SEE ALSO 409.Xr sdpquery 1 , 410.Xr strerror 3 , 411.Xr bluetooth 4 , 412.Xr sdpd 8 413.Sh HISTORY 414.Nm libsdp 415first appeared in 416.Fx , 417was ported to 418.Nx 4.0 419by 420.An Iain Hibbert 421and imported into 422.Dx 1.11 . 423.Sh AUTHORS 424.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com 425.Sh BUGS 426Most likely. 427Please report bugs if found. 428