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