1.\" $NetBSD: sdp.3,v 1.3 2009/05/20 17:22:56 plunky 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 75The SDP library provides means for client programs to perform Bluetooth 76Service Discovery, and to advertise Service Records on the local host. 77.Pp 78The Service Discovery API reflects the Bluetooth SDP specification, providing 79access to complete ServiceSearch, ServiceAttribute or ServiceSearchAttribute 80transactions and using SDP data element lists directly which can be 81constructed and parsed with the 82.Xr sdp_data 3 83library functions. 84.Pp 85The ServiceSearchPattern is a list of UUID data elements. 86The list must 87contain at least one UUID and the maximum number of UUIDs is 12. 88A service record will be matched when all the UUIDs from the 89ServiceSearchPattern are contained in the record. 90.Pp 91The AttributeIDList is a list of data elements where each is either an 92attribute ID encoded as an unsigned 16-bit integer, or a range of attribute 93IDs encoded as an unsigned 32-bit integer where the high order 16-bits are 94the start of the range and the low order 16-bits are the end of the range 95.Pq inclusive . 96The AttributeIDList should be arranged in ascending order and there should 97be no duplicate attribute ID values. 98If 99.Dv NULL 100is passed, all attributes 101.Pq 0x0000-0xffff 102will be requested. 103.Pp 104ServiceRecords to be registered with the local 105.Xr sdpd 8 106server should consist of a list of attribute ID/value pairs, where the 107attribute ID is a 16-bit unsigned integer element, and the attribute value 108is any data element. 109The attribute IDs should be in ascending order, and the first one must be 110.Dv SDP_ATTR_SERVICE_RECORD_HANDLE 111.Pq 0x0000 , 112otherwise the server will reject the record. 113For consistency, records should also contain a BrowseGroupList with the 114PublicBrowseGroup UUID, plus at least a ServiceName string in the native 115language with an associated LanguageBaseAttributeIDList although this is 116not currently enforced. 117.Sh FUNCTIONS 118.Bl -tag -width xxxx 119.It Fn sdp_open "laddr" "raddr" 120Open a SDP session to a remote Bluetooth device. 121.Fa laddr 122refers to the local bluetooth device address and may be 123.Dv NULL 124in which case it will default to 125.Dv BDADDR_ANY . 126.It Fn sdp_open_local "control" 127Open a SDP session to a server using a local socket. 128The 129.Fa control 130socket path may be given as 131.Dv NULL 132in which case the default control path 133.Pa /var/run/sdp 134will be used. 135.It Fn sdp_close ss 136Close SDP session and release all resources. 137.It Fn sdp_service_search "ss" "ssp" "handlep" "num" 138Perform a complete ServiceSearch transaction on the SDP session. 139At most 140.Fa num 141service record handles matching the ServiceSearchPattern 142.Fa ssp 143will be returned in the array pointed to by 144.Fa handlep . 145.It Fn sdp_service_attribute "ss" "handle" "ail" "response" 146Perform a complete ServiceAttribute transaction on the SDP session. 147The ServiceRecord with ServiceRecordHandle 148.Fa handle 149will be parsed using the AttributeIDList 150.Fa ail . 151If the transaction succeeds, the 152.Fa response 153data buffer will contain a validated data element list of attribute 154ID/value pairs from the selected record. 155.It Fn sdp_service_search_attribute "ss" "ssp" "ail" "response" 156Perform a complete ServiceSearchAttribute transaction on the SDP session. 157All ServiceRecords matching the ServiceSearchPattern 158.Fa ssp 159will be parsed using the AttributeIDList 160.Fa ail . 161If the transaction succeeds, the 162.Fa response 163data buffer will contain a valid data element list of sequences, where 164each sequence is the attribute ID/value list from a matched record. 165.It Fn sdp_record_insert "ss" "bdaddr" "handlep" "record" 166Insert a ServiceRecord 167.Fa record . 168If 169.Fa bdaddr 170is given, the service record will be restricted to clients connecting 171through the Bluetooth controller with that BD_ADDR. 172When the 173.Fa handlep 174pointer is non NULL, the resulting ServiceRecordHandle will be written 175to the address given. 176The record will be valid while the session is active and will be 177purged when the session is closed. 178.It Fn sdp_record_update "ss" "handle" "record" 179Update a ServiceRecord that is owned by this session. 180.Fa handle 181is the identifier returned by the 182.Fn sdp_record_insert 183call, and 184.Fa record 185is the updated ServiceRecord as described above. 186.It Fn sdp_record_remove "ss" "handle" 187Remove a ServiceRecord owned by this session. 188.Fa handle 189is the identifier returned by the 190.Fn sdp_record_insert 191call. 192.El 193.Pp 194A single response buffer is maintained for each session, so the results 195of a ServiceAttribute or ServiceSearchAttribute request will only be valid 196until another request is made or the session is closed. 197The SDP specifications do not mandate a limit on the size of the response 198buffer but this implementation has a default limit of UINT16_MAX bytes. 199This limit can be increased at runtime by setting the environment variable 200.Ev SDP_RESPONSE_MAX 201to a numeric value. 202.Pp 203Records are only allowed to be removed or updated by the session that inserted 204them, and records will be removed automatically when the session is closed. 205Further, manipulating service records will normally only be possible for 206privileged users on a SDP session connected with a local socket. 207See 208.Xr sdpd 8 209and your local system administrator for details. 210.Sh RETURN VALUES 211Session open routines will return a session handle on success and 212.Dv NULL 213on failure. 214For service lookup and record manipulation routines, a boolean value is 215returned indicating success or failure. 216On failure, 217.Va errno 218will be set to indicate the error. 219.Sh FILES 220.Pa /var/run/sdp 221.Sh ERRORS 222In addition to errors returned by the standard C library IO functions, 223the following errors may be detected by 224.Nm libbluetooth : 225.Bl -tag -offset indent -width ".Bq Er ENOATTR" 226.It Bq Er EINVAL 227A provided function argument was not valid. 228.It Bq Er EIO 229A response from the remote server was not understood. 230.It Bq Er ENOATTR 231The record 232.Fa handle 233did 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 241The 242.Qq Service Discovery Protocol 243section of the Bluetooth Core specifications, available at 244.Qq http://www.bluetooth.com/ 245.Sh HISTORY 246The first Service Discovery implementation was written for 247.Fx 248and was ported to 249.Nx 4.0 . 250This, the second version API, was designed by 251.An Iain Hibbert 252for 253.Nx 6.0 254in order to simplify the 255.Xr sdpd 8 256daemon and allow client code greater control over all aspects of the 257service records. 258The original API is still available when 259.Dv SDP_COMPAT 260is defined but will eventually be removed. 261