NAME
sdp_open,
sdp_open_local,
sdp_close,
sdp_service_search,
sdp_service_attribute,
sdp_service_search_attribute,
sdp_record_insert,
sdp_record_update,
sdp_record_remove —
Service Discovery
Protocol session routines
LIBRARY
Bluetooth Library (libbluetooth, -lbluetooth)
SYNOPSIS
#include <sdp.h>
sdp_session_t
sdp_open(
const
bdaddr_t *laddr,
const
bdaddr_t *raddr);
sdp_session_t
sdp_open_local(
const
char *control);
void
sdp_close(
sdp_session_t
ss);
bool
sdp_service_search(
sdp_session_t ss,
sdp_data_t *ssp,
uint32_t
*handlep,
int *num);
bool
sdp_service_attribute(
sdp_session_t ss,
uint32_t handle,
sdp_data_t *ail,
sdp_data_t *response);
bool
sdp_service_search_attribute(
sdp_session_t
ss,
sdp_data_t *ssp,
sdp_data_t
*ail,
sdp_data_t *response);
bool
sdp_record_insert(
sdp_session_t ss,
bdaddr_t *bdaddr,
uint32_t
*handlep,
sdp_data_t *record);
bool
sdp_record_update(
sdp_session_t
ss,
uint32_t handle,
sdp_data_t *record);
bool
sdp_record_remove(
sdp_session_t
ss,
uint32_t handle);
DESCRIPTION
The SDP library provides means for client programs to perform Bluetooth Service
Discovery, and to advertise Service Records on the local host.
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
sdp_data(3) library functions.
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.
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 (inclusive). The
AttributeIDList should be arranged in ascending order and there should be no
duplicate attribute ID values. If
NULL
is passed, all
attributes (0x0000-0xffff) will be requested.
ServiceRecords to be registered with the local
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
SDP_ATTR_SERVICE_RECORD_HANDLE
(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.
FUNCTIONS
-
-
- sdp_open(laddr,
raddr)
- Open a SDP session to a remote Bluetooth device.
laddr refers to the local bluetooth device address
and may be
NULL
in which case it will default to
BDADDR_ANY
.
-
-
- sdp_open_local(control)
- Open a SDP session to a server using a local socket. The
control socket path may be given as
NULL
in which case the default control path
/var/run/sdp will be used.
-
-
- sdp_close(ss)
- Close SDP session and release all resources.
-
-
- sdp_service_search(ss,
ssp, handlep,
num)
- Perform a complete ServiceSearch transaction on the SDP
session. At most num service record handles matching
the ServiceSearchPattern ssp will be returned in the
array pointed to by handlep.
-
-
- sdp_service_attribute(ss,
handle, ail,
response)
- Perform a complete ServiceAttribute transaction on the SDP
session. The ServiceRecord with ServiceRecordHandle
handle will be parsed using the AttributeIDList
ail. If the transaction succeeds, the
response data buffer will contain a validated data
element list of attribute ID/value pairs from the selected record.
-
-
- sdp_service_search_attribute(ss,
ssp, ail,
response)
- Perform a complete ServiceSearchAttribute transaction on
the SDP session. All ServiceRecords matching the ServiceSearchPattern
ssp will be parsed using the AttributeIDList
ail. If the transaction succeeds, the
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.
-
-
- sdp_record_insert(ss,
bdaddr, handlep,
record)
- Insert a ServiceRecord record. If
bdaddr is given, the service record will be
restricted to clients connecting through the Bluetooth controller with
that BD_ADDR. When the 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.
-
-
- sdp_record_update(ss,
handle, record)
- Update a ServiceRecord that is owned by this session.
handle is the identifier returned by the
sdp_record_insert() call, and
record is the updated ServiceRecord as described
above.
-
-
- sdp_record_remove(ss,
handle)
- Remove a ServiceRecord owned by this session.
handle is the identifier returned by the
sdp_record_insert() call.
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
SDP_RESPONSE_MAX
to a numeric value.
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
sdpd(8) and your local system
administrator for details.
RETURN VALUES
Session open routines will return a session handle on success and
NULL
on failure. For service lookup and record
manipulation routines, a boolean value is returned indicating success or
failure. On failure,
errno will be set to indicate the
error.
FILES
/var/run/sdp
ERRORS
In addition to errors returned by the standard C library IO functions, the
following errors may be detected by
libbluetooth:
-
-
- [
EINVAL
]
- A provided function argument was not valid.
-
-
- [
EIO
]
- A response from the remote server was not understood.
-
-
- [
ENOATTR
]
- The record handle did not exist on
the server.
SEE ALSO
sdpquery(1),
bluetooth(3),
sdp_data(3),
sdpd(8)
The “Service Discovery Protocol” section of the Bluetooth Core
specifications, available at
http://www.bluetooth.com/
HISTORY
The first Service Discovery implementation was written for
FreeBSD and was ported to
NetBSD
4.0. This, the second version API, was designed by
Iain Hibbert for
NetBSD 6.0 in
order to simplify the
sdpd(8)
daemon and allow client code greater control over all aspects of the service
records. The original API is still available when
SDP_COMPAT
is defined but will eventually be
removed.