261 lines
8.9 KiB
Groff
261 lines
8.9 KiB
Groff
.\" $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.
|