.\" $NetBSD: sdp.3,v 1.4 2012/03/15 19:04:46 njoly Exp $
.\"
.\" Copyright (c) 2009 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Iain Hibbert.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 7, 2009
.Dt SDP 3
.Os
.Sh NAME
.Nm sdp_open ,
.Nm sdp_open_local ,
.Nm sdp_close ,
.Nm sdp_service_search ,
.Nm sdp_service_attribute ,
.Nm sdp_service_search_attribute ,
.Nm sdp_record_insert ,
.Nm sdp_record_update ,
.Nm sdp_record_remove
.Nd Service Discovery Protocol session routines
.Sh LIBRARY
.Lb libbluetooth
.Sh SYNOPSIS
.In sdp.h
.Ft sdp_session_t
.Fn sdp_open "const bdaddr_t *laddr" "const bdaddr_t *raddr"
.Ft sdp_session_t
.Fn sdp_open_local "const char *control"
.Ft void
.Fn sdp_close "sdp_session_t ss"
.Ft bool
.Fo sdp_service_search
.Fa "sdp_session_t ss" "sdp_data_t *ssp" "uint32_t *handlep" "int *num"
.Fc
.Ft bool
.Fo sdp_service_attribute
.Fa "sdp_session_t ss" "uint32_t handle" "sdp_data_t *ail" "sdp_data_t *response"
.Fc
.Ft bool
.Fo sdp_service_search_attribute
.Fa "sdp_session_t ss" "sdp_data_t *ssp" "sdp_data_t *ail" "sdp_data_t *response"
.Fc
.Ft bool
.Fo sdp_record_insert
.Fa "sdp_session_t ss" "bdaddr_t *bdaddr" "uint32_t *handlep" "sdp_data_t *record"
.Fc
.Ft bool
.Fn sdp_record_update "sdp_session_t ss" "uint32_t handle" "sdp_data_t *record"
.Ft bool
.Fn sdp_record_remove "sdp_session_t ss" "uint32_t handle"
.Sh DESCRIPTION
The SDP library provides means for client programs to perform Bluetooth
Service Discovery, and to advertise Service Records on the local host.
.Pp
The Service Discovery API reflects the Bluetooth SDP specification, providing
access to complete ServiceSearch, ServiceAttribute or ServiceSearchAttribute
transactions and using SDP data element lists directly which can be
constructed and parsed with the
.Xr sdp_data 3
library functions.
.Pp
The ServiceSearchPattern is a list of UUID data elements.
The list must
contain at least one UUID and the maximum number of UUIDs is 12.
A service record will be matched when all the UUIDs from the
ServiceSearchPattern are contained in the record.
.Pp
The AttributeIDList is a list of data elements where each is either an
attribute ID encoded as an unsigned 16-bit integer, or a range of attribute
IDs encoded as an unsigned 32-bit integer where the high order 16-bits are
the start of the range and the low order 16-bits are the end of the range
.Pq inclusive .
The AttributeIDList should be arranged in ascending order and there should
be no duplicate attribute ID values.
If
.Dv NULL
is passed, all attributes
.Pq 0x0000-0xffff
will be requested.
.Pp
ServiceRecords to be registered with the local
.Xr sdpd 8
server should consist of a list of attribute ID/value pairs, where the
attribute ID is a 16-bit unsigned integer element, and the attribute value
is any data element.
The attribute IDs should be in ascending order, and the first one must be
.Dv SDP_ATTR_SERVICE_RECORD_HANDLE
.Pq 0x0000 ,
otherwise the server will reject the record.
For consistency, records should also contain a BrowseGroupList with the
PublicBrowseGroup UUID, plus at least a ServiceName string in the native
language with an associated LanguageBaseAttributeIDList although this is
not currently enforced.
.Sh FUNCTIONS
.Bl -tag -width xxxx
.It Fn sdp_open "laddr" "raddr"
Open a SDP session to a remote Bluetooth device.
.Fa laddr
refers to the local bluetooth device address and may be
.Dv NULL
in which case it will default to
.Dv BDADDR_ANY .
.It Fn sdp_open_local "control"
Open a SDP session to a server using a local socket.
The
.Fa control
socket path may be given as
.Dv NULL
in which case the default control path
.Pa /var/run/sdp
will be used.
.It Fn sdp_close ss
Close SDP session and release all resources.
.It Fn sdp_service_search "ss" "ssp" "handlep" "num"
Perform a complete ServiceSearch transaction on the SDP session.
At most
.Fa num
service record handles matching the ServiceSearchPattern
.Fa ssp
will be returned in the array pointed to by
.Fa handlep .
.It Fn sdp_service_attribute "ss" "handle" "ail" "response"
Perform a complete ServiceAttribute transaction on the SDP session.
The ServiceRecord with ServiceRecordHandle
.Fa handle
will be parsed using the AttributeIDList
.Fa ail .
If the transaction succeeds, the
.Fa response
data buffer will contain a validated data element list of attribute
ID/value pairs from the selected record.
.It Fn sdp_service_search_attribute "ss" "ssp" "ail" "response"
Perform a complete ServiceSearchAttribute transaction on the SDP session.
All ServiceRecords matching the ServiceSearchPattern
.Fa ssp
will be parsed using the AttributeIDList
.Fa ail .
If the transaction succeeds, the
.Fa response
data buffer will contain a valid data element list of sequences, where
each sequence is the attribute ID/value list from a matched record.
.It Fn sdp_record_insert "ss" "bdaddr" "handlep" "record"
Insert a ServiceRecord
.Fa record .
If
.Fa bdaddr
is given, the service record will be restricted to clients connecting
through the Bluetooth controller with that BD_ADDR.
When the
.Fa handlep
pointer is non NULL, the resulting ServiceRecordHandle will be written
to the address given.
The record will be valid while the session is active and will be
purged when the session is closed.
.It Fn sdp_record_update "ss" "handle" "record"
Update a ServiceRecord that is owned by this session.
.Fa handle
is the identifier returned by the
.Fn sdp_record_insert
call, and
.Fa record
is the updated ServiceRecord as described above.
.It Fn sdp_record_remove "ss" "handle"
Remove a ServiceRecord owned by this session.
.Fa handle
is the identifier returned by the
.Fn sdp_record_insert
call.
.El
.Pp
A single response buffer is maintained for each session, so the results
of a ServiceAttribute or ServiceSearchAttribute request will only be valid
until another request is made or the session is closed.
The SDP specifications do not mandate a limit on the size of the response
buffer but this implementation has a default limit of UINT16_MAX bytes.
This limit can be increased at runtime by setting the environment variable
.Ev SDP_RESPONSE_MAX
to a numeric value.
.Pp
Records are only allowed to be removed or updated by the session that inserted
them, and records will be removed automatically when the session is closed.
Further, manipulating service records will normally only be possible for
privileged users on a SDP session connected with a local socket.
See
.Xr sdpd 8
and your local system administrator for details.
.Sh RETURN VALUES
Session open routines will return a session handle on success and
.Dv NULL
on failure.
For service lookup and record manipulation routines, a boolean value is
returned indicating success or failure.
On failure,
.Va errno
will be set to indicate the error.
.Sh FILES
.Pa /var/run/sdp
.Sh ERRORS
In addition to errors returned by the standard C library IO functions,
the following errors may be detected by
.Nm libbluetooth :
.Bl -tag -offset indent -width ".Bq Er ENOATTR"
.It Bq Er EINVAL
A provided function argument was not valid.
.It Bq Er EIO
A response from the remote server was not understood.
.It Bq Er ENOATTR
The record
.Fa handle
did not exist on the server.
.El
.Sh SEE ALSO
.Xr sdpquery 1 ,
.Xr bluetooth 3 ,
.Xr sdp_data 3 ,
.Xr sdpd 8
.Pp
The
.Qq Service Discovery Protocol
section of the Bluetooth Core specifications, available at
.Lk http://www.bluetooth.com/
.Sh HISTORY
The first Service Discovery implementation was written for
.Fx
and was ported to
.Nx 4.0 .
This, the second version API, was designed by
.An Iain Hibbert
for
.Nx 6.0
in order to simplify the
.Xr sdpd 8
daemon and allow client code greater control over all aspects of the
service records.
The original API is still available when
.Dv SDP_COMPAT
is defined but will eventually be removed.