lib/libsdp/sdp.3

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