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