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