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