lib/libsdp/sdp.3

   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 April 6, 2018
  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 *"
  85 .Fn sdp_attr2desc "uint16_t attr"
  86 .Ft "char 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 *bdaddr" "uint8_t *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 *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 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 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_search
 194 function is used to perform SDP Service Search Attribute Request.
 195 The
 196 .Fa xs
 197 parameter should point to a valid SDP session object created with
 198 .Fn sdp_open
 199 or
 200 .Fn sdp_open_local .
 201 The
 202 .Fa pp
 203 parameter is a Service Search Pattern - an array of one or more Service
 204 Class IDs.
 205 The maximum number of Service Class IDs in the array is 12.
 206 The
 207 .Fa plen
 208 parameter is the length of the Service Search pattern.
 209 The
 210 .Fa ap
 211 parameter is an Attribute ID Range List - an array of one or more SDP Attribute
 212 ID Range.
 213 Each attribute ID Range is encoded as a 32-bit unsigned integer data
 214 element, where the high order 16 bits are interpreted as the beginning
 215 attribute ID of the range and the low order 16 bits are interpreted as the
 216 ending attribute ID of the range.
 217 The attribute IDs contained in the Attribute ID Ranges List must be listed in
 218 ascending order without duplication of any attribute ID values.
 219 Note that all attributes may be requested by specifying a range of
 220 0x0000-0xFFFF.
 221 The
 222 .Fa alen
 223 parameter is the length of the Attribute ID Ranges List.
 224 The
 225 .Fn SDP_ATTR_RANGE "lo" "hi"
 226 macro can be used to prepare Attribute ID Range.
 227 The
 228 .Fa vp
 229 parameter should be an array of
 230 .Vt sdp_attr_t
 231 structures.
 232 Each
 233 .Vt sdp_attr_t
 234 structure describes single SDP attribute and defined as follows:
 235 .Bd -literal -offset indent
 236 struct 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 };
 245 typedef struct sdp_attr         sdp_attr_t;
 246 typedef struct sdp_attr *       sdp_attr_p;
 247 .Ed
 248 .Pp
 249 The caller of the
 250 .Fn sdp_search
 251 function is expected to prepare the array of
 252 .Vt sdp_attr
 253 structures and for each element of the array both
 254 .Va vlen
 255 and
 256 .Va value
 257 must be set.
 258 The
 259 .Fn sdp_search
 260 function will fill each
 261 .Vt sdp_attr_t
 262 structure with attribute and value, i.e., it will set
 263 .Va flags ,
 264 .Va attr
 265 and
 266 .Va vlen
 267 fields.
 268 The actual value of the attribute will be copied into
 269 .Va value
 270 buffer.
 271 Note: attributes are returned in the order they appear in the Service Search
 272 Attribute Response.
 273 SDP server could return several attributes for the same record.
 274 In this case the order of the attributes will be: all attributes for the first
 275 records, then all attributes for the secord record etc.
 276 .Pp
 277 The
 278 .Fn sdp_attr2desc
 279 and
 280 .Fn sdp_uuid2desc
 281 functions each take a numeric attribute ID/UUID value and convert it to a
 282 human readable description.
 283 .Pp
 284 The
 285 .Fn sdp_register_service
 286 function
 287 is used to register service with the local SDP server.
 288 The
 289 .Fa xss
 290 parameter should point to a valid SDP session object obtained from
 291 .Fn sdp_open_local .
 292 The
 293 .Fa uuid
 294 parameter is a SDP Service Class ID for the service to be registered.
 295 The
 296 .Fa bdaddr
 297 parameter should point to a valid BD_ADDR.
 298 The service will be only advertised if request was received by the local device
 299 with
 300 .Fa bdaddr .
 301 If
 302 .Fa bdaddr
 303 is set to
 304 .Dv BDADDR_ANY
 305 then the service will be advertised to any remote devices that queries for it.
 306 The
 307 .Fa data
 308 and
 309 .Fa datalen
 310 parameters specify data and size of the data for the service.
 311 Upon successful return
 312 .Fn sdp_register_service
 313 will populate
 314 .Fa handle
 315 with the SDP record handle.
 316 This parameter is optional and can be set to
 317 .Dv NULL .
 318 .Pp
 319 The
 320 .Fn sdp_unregister_service
 321 function
 322 is used to unregister service with the local SDP server.
 323 The
 324 .Fa xss
 325 parameter should point to a valid SDP session object obtained from
 326 .Fn sdp_open_local .
 327 The
 328 .Fa handle
 329 parameter should contain a valid SDP record handle of the service to be
 330 unregistered.
 331 .Pp
 332 The
 333 .Fn sdp_change_service
 334 function is used to change data associated with the existing service on
 335 the local SDP server.
 336 The
 337 .Fa xss
 338 parameter should point to a valid SDP session object obtained from
 339 .Fn sdp_open_local .
 340 The
 341 .Fa handle
 342 parameter should contain a valid SDP record handle of the service to be changed.
 343 The
 344 .Fa data
 345 and
 346 .Fa datalen
 347 parameters specify data and size of the data for the service.
 348 .Sh CAVEAT
 349 When registering services with the local SDP server the application must
 350 keep the SDP session open.
 351 If SDP session is closed then the local SDP server will remove all services
 352 that were registered over the session.
 353 The application is allowed to change or unregister service if it was registered
 354 over the same session.
 355 .Sh EXAMPLES
 356 The following example shows how to get
 357 .Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST
 358 attribute for the
 359 .Dv SDP_SERVICE_CLASS_SERIAL_PORT
 360 service from the remote device.
 361 .Bd -literal -offset indent
 362 bdaddr_t       remote;
 363 uint8_t        buffer[1024];
 364 void          *ss    = NULL;
 365 uint16_t       serv  = SDP_SERVICE_CLASS_SERIAL_PORT;
 366 uint32_t       attr  = SDP_ATTR_RANGE(
 367                             SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST,
 368                             SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST);
 369 sdp_attr_t     proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer };
 370
 371 /* Obtain/set remote BDADDR here */
 372
 373 if ((ss = sdp_open(BDADDR_ANY, remote)) == NULL)
 374         /* exit ENOMEM */
 375 if (sdp_error(ss) != 0)
 376         /* exit sdp_error(ss) */
 377
 378 if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0)
 379         /* exit sdp_error(ss) */
 380
 381 if (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
 387 Both
 388 .Fn sdp_open
 389 and
 390 .Fn sdp_open_local
 391 will return
 392 .Dv NULL
 393 if memory allocation for the new SDP session object fails.
 394 If the new SDP object was created then caller is still expected to call
 395 .Fn sdp_error
 396 to check if there was connection error.
 397 .Pp
 398 The
 399 .Fn sdp_search ,
 400 .Fn sdp_register_service ,
 401 .Fn sdp_unregister_service
 402 and
 403 .Fn sdp_change_service
 404 functions return non-zero value on error.
 405 The caller is expected to call
 406 .Fn sdp_error
 407 to 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
 415 first appeared in
 416 .Fx ,
 417 was ported to
 418 .Nx 4.0
 419 by
 420 .An Iain Hibbert
 421 and imported into
 422 .Dx 1.11 .
 423 .Sh AUTHORS
 424 .An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com
 425 .Sh BUGS
 426 Most likely.
 427 Please report bugs if found.