lib/libsdp/sdp.3

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