lib/libbluetooth/sdp.3

   1 .\" $NetBSD: sdp.3,v 1.2 2009/05/12 10:32:45 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Iain Hibbert.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .Dd May 7, 2009
  31 .Dt SDP 3
  32 .Os
  33 .Sh NAME
  34 .Nm sdp_open ,
  35 .Nm sdp_open_local ,
  36 .Nm sdp_close ,
  37 .Nm sdp_service_search ,
  38 .Nm sdp_service_attribute ,
  39 .Nm sdp_service_search_attribute ,
  40 .Nm sdp_record_insert ,
  41 .Nm sdp_record_update ,
  42 .Nm sdp_record_remove
  43 .Nd Service Discovery Protocol session routines
  44 .Sh LIBRARY
  45 .Lb libbluetooth
  46 .Sh SYNOPSIS
  47 .In sdp.h
  48 .Ft sdp_session_t
  49 .Fn sdp_open "const bdaddr_t *laddr" "const bdaddr_t *raddr"
  50 .Ft sdp_session_t
  51 .Fn sdp_open_local "const char *control"
  52 .Ft void
  53 .Fn sdp_close "sdp_session_t ss"
  54 .Ft bool
  55 .Fo sdp_service_search
  56 .Fa "sdp_session_t ss" "sdp_data_t *ssp" "uint32_t *handlep" "int *num"
  57 .Fc
  58 .Ft bool
  59 .Fo sdp_service_attribute
  60 .Fa "sdp_session_t ss" "uint32_t handle" "sdp_data_t *ail" "sdp_data_t *response"
  61 .Fc
  62 .Ft bool
  63 .Fo sdp_service_search_attribute
  64 .Fa "sdp_session_t ss" "sdp_data_t *ssp" "sdp_data_t *ail" "sdp_data_t *response"
  65 .Fc
  66 .Ft bool
  67 .Fo sdp_record_insert
  68 .Fa "sdp_session_t ss" "bdaddr_t *bdaddr" "uint32_t *handlep" "sdp_data_t *record"
  69 .Fc
  70 .Ft bool
  71 .Fn sdp_record_update "sdp_session_t ss" "uint32_t handle" "sdp_data_t *record"
  72 .Ft bool
  73 .Fn sdp_record_remove "sdp_session_t ss" "uint32_t handle"
  74 .Sh DESCRIPTION
  75 The SDP library provides means for client programs to perform Bluetooth
  76 Service Discovery, and to advertise Service Records on the local host.
  77 .Pp
  78 The Service Discovery API reflects the Bluetooth SDP specification, providing
  79 access to complete ServiceSearch, ServiceAttribute or ServiceSearchAttribute
  80 transactions and using SDP data element lists directly which can be
  81 constructed and parsed with the
  82 .Xr sdp_data 3
  83 library functions.
  84 .Pp
  85 The ServiceSearchPattern is a list of UUID data elements.
  86 The list must
  87 contain at least one UUID and the maximum number of UUIDs is 12.
  88 A service record will be matched when all the UUIDs from the
  89 ServiceSearchPattern are contained in the record.
  90 .Pp
  91 The AttributeIDList is a list of data elements where each is either an
  92 attribute ID encoded as an unsigned 16-bit integer, or a range of attribute
  93 IDs encoded as an unsigned 32-bit integer where the high order 16-bits are
  94 the start of the range and the low order 16-bits are the end of the range
  95 .Pq inclusive .
  96 The AttributeIDList should be arranged in ascending order and there should
  97 be no duplicate attribute ID values.
  98 If
  99 .Dv NULL
 100 is passed, all attributes
 101 .Pq 0x0000-0xffff
 102 will be requested.
 103 .Pp
 104 ServiceRecords to be registered with the local
 105 .Xr sdpd 8
 106 server should consist of a list of attribute ID/value pairs, where the
 107 attribute ID is a 16-bit unsigned integer element, and the attribute value
 108 is any data element.
 109 The attribute IDs should be in ascending order, and the first one must be
 110 .Dv SDP_ATTR_SERVICE_RECORD_HANDLE
 111 .Pq 0x0000 ,
 112 otherwise the server will reject the record.
 113 For consistency, records should also contain a BrowseGroupList with the
 114 PublicBrowseGroup UUID, plus at least a ServiceName string in the native
 115 language with an associated LanguageBaseAttributeIDList although this is
 116 not currently enforced.
 117 .Sh FUNCTIONS
 118 .Bl -tag -width xxxx
 119 .It Fn sdp_open "laddr" "raddr"
 120 Open a SDP session to a remote Bluetooth device.
 121 .Fa laddr
 122 refers to the local bluetooth device address and may be
 123 .Dv NULL
 124 in which case it will default to
 125 .Dv BDADDR_ANY .
 126 .It Fn sdp_open_local "control"
 127 Open a SDP session to a server using a local socket.
 128 The
 129 .Fa control
 130 socket path may be given as
 131 .Dv NULL
 132 in which case the default control path
 133 .Pa /var/run/sdp
 134 will be used.
 135 .It Fn sdp_close ss
 136 Close SDP session and release all resources.
 137 .It Fn sdp_service_search "ss" "ssp" "handlep" "num"
 138 Perform a complete ServiceSearch transaction on the SDP session.
 139 At most
 140 .Fa num
 141 service record handles matching the ServiceSearchPattern
 142 .Fa ssp
 143 will be returned in the array pointed to by
 144 .Fa handlep .
 145 .It Fn sdp_service_attribute "ss" "handle" "ail" "response"
 146 Perform a complete ServiceAttribute transaction on the SDP session.
 147 The ServiceRecord with ServiceRecordHandle
 148 .Fa handle
 149 will be parsed using the AttributeIDList
 150 .Fa ail .
 151 If the transaction succeeds, the
 152 .Fa response
 153 data buffer will contain a validated data element list of attribute
 154 ID/value pairs from the selected record.
 155 .It Fn sdp_service_search_attribute "ss" "ssp" "ail" "response"
 156 Perform a complete ServiceSearchAttribute transaction on the SDP session.
 157 All ServiceRecords matching the ServiceSearchPattern
 158 .Fa ssp
 159 will be parsed using the AttributeIDList
 160 .Fa ail .
 161 If the transaction succeeds, the
 162 .Fa response
 163 data buffer will contain a valid data element list of sequences, where
 164 each sequence is the attribute ID/value list from a matched record.
 165 .It Fn sdp_record_insert "ss" "bdaddr" "handlep" "record"
 166 Insert a ServiceRecord
 167 .Fa record .
 168 If
 169 .Fa bdaddr
 170 is given, the service record will be restricted to clients connecting
 171 through the Bluetooth controller with that BD_ADDR.
 172 When the
 173 .Fa handlep
 174 pointer is non NULL, the resulting ServiceRecordHandle will be written
 175 to the address given.
 176 The record will be valid while the session is active and will be
 177 purged when the session is closed.
 178 .It Fn sdp_record_update "ss" "handle" "record"
 179 Update a ServiceRecord that is owned by this session.
 180 .Fa handle
 181 is the identifier returned by the
 182 .Fn sdp_record_insert
 183 call, and
 184 .Fa record
 185 is the updated ServiceRecord as described above.
 186 .It Fn sdp_record_remove "ss" "handle"
 187 Remove a ServiceRecord owned by this session.
 188 .Fa handle
 189 is the identifier returned by the
 190 .Fn sdp_record_insert
 191 call.
 192 .El
 193 .Pp
 194 A single response buffer is maintained for each session, so the results
 195 of a ServiceAttribute or ServiceSearchAttribute request will only be valid
 196 until another request is made or the session is closed.
 197 The SDP specifications do not mandate a limit on the size of the response
 198 buffer but this implementation has a default limit of UINT16_MAX bytes.
 199 This limit can be increased at runtime by setting the environment variable
 200 .Ev SDP_RESPONSE_MAX
 201 to a numeric value.
 202 .Pp
 203 Records are only allowed to be removed or updated by the session that inserted
 204 them, and records will be removed automatically when the session is closed.
 205 Further, manipulating service records will normally only be possible for
 206 privileged users on a SDP session connected with a local socket.
 207 See
 208 .Xr sdpd 8
 209 and your local system administrator for details.
 210 .Sh RETURN VALUES
 211 Session open routines will return a session handle on success and
 212 .Dv NULL
 213 on failure.
 214 For service lookup and record manipulation routines, a boolean value is
 215 returned indicating success or failure.
 216 On failure,
 217 .Va errno
 218 will be set to indicate the error.
 219 .Sh FILES
 220 .Pa /var/run/sdp
 221 .Sh ERRORS
 222 In addition to errors returned by the standard C library IO functions,
 223 the following errors may be detected by
 224 .Nm libbluetooth :
 225 .Bl -tag -offset indent -width ".Bq Er ENOATTR"
 226 .It Bq Er EINVAL
 227 A provided function argument was not valid.
 228 .It Bq Er EIO
 229 A response from the remote server was not understood.
 230 .It Bq Er ENOATTR
 231 The record
 232 .Fa handle
 233 did not exist on the server.
 234 .El
 235 .Sh SEE ALSO
 236 .Xr sdpquery 1 ,
 237 .Xr bluetooth 3 ,
 238 .Xr sdp_data 3 ,
 239 .Xr sdpd 8
 240 .Pp
 241 The
 242 .Qq Service Discovery Protocol
 243 section of the Bluetooth Core specifications, available at
 244 .Qq http://www.bluetooth.com/
 245 .Sh HISTORY
 246 The first Service Discovery implementation was written for
 247 .Fx
 248 and was ported to
 249 .Nx 4.0 .
 250 This, the second version API, was designed by
 251 .An Iain Hibbert
 252 for
 253 .Nx 6.0
 254 in order to simplify the
 255 .Xr sdpd 8
 256 daemon and allow client code greater control over all aspects of the
 257 service records.
 258 The original API is still available when
 259 .Dv SDP_COMPAT
 260 is defined but will eventually be removed.