310 lines
8.2 KiB
Groff
310 lines
8.2 KiB
Groff
|
.\" Copyright (c) 2003 Maksim Yevmenkin <m_evmenkin@yahoo.com>
|
||
|
|
.\" All rights reserved.
|
||
|
|
.\"
|
||
|
|
.\" 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.
|
||
|
|
.\"
|
||
|
|
.\" $Id: sdp.3,v 1.1 2003/09/07 20:34:19 max Exp $
|
||
|
|
.\" $FreeBSD$
|
||
|
|
.\"
|
||
|
|
.Dd September 7, 2003
|
||
|
|
.Dt SDP 3
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm SDP_GET8 ,
|
||
|
|
.Nm SDP_GET16 ,
|
||
|
|
.Nm SDP_GET32 ,
|
||
|
|
.Nm SDP_GET64 ,
|
||
|
|
.Nm SDP_GET128
|
||
|
|
.Nd get SDP integer
|
||
|
|
.Pp
|
||
|
|
.Nm SDP_PUT8 ,
|
||
|
|
.Nm SDP_PUT16 ,
|
||
|
|
.Nm SDP_PUT32 ,
|
||
|
|
.Nm SDP_PUT64 ,
|
||
|
|
.Nm SDP_PUT128
|
||
|
|
.Nd put SPD integer
|
||
|
|
.Pp
|
||
|
|
.Nm sdp_open ,
|
||
|
|
.Nm sdp_open_local ,
|
||
|
|
.Nm sdp_close
|
||
|
|
.Nm sdp_error
|
||
|
|
.Nd control SDP session
|
||
|
|
.Pp
|
||
|
|
.Nm sdp_search
|
||
|
|
.Nd perform SDP query
|
||
|
|
.Pp
|
||
|
|
.Nm sdp_attr2desc ,
|
||
|
|
.Nm sdp_uuid2desc
|
||
|
|
.Nd convert numeric SDP attribute/UUID value into human readable description
|
||
|
|
.Sh LIBRARY
|
||
|
|
.Lb libsdp
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In bluetooth.h
|
||
|
|
.In sdp.h
|
||
|
|
.Fn SDP_GET8 "b" "cp"
|
||
|
|
.Fn SDP_GET16 "s" "cp"
|
||
|
|
.Fn SDP_GET32 "l" "cp"
|
||
|
|
.Fn SDP_GET64 "l" "cp"
|
||
|
|
.Fn SDP_GET128 "l" "cp"
|
||
|
|
.Fn SDP_PUT8 "b" "cp"
|
||
|
|
.Fn SDP_PUT16 "s" "cp"
|
||
|
|
.Fn SDP_PUT32 "l" "cp"
|
||
|
|
.Fn SDP_PUT64 "l" "cp"
|
||
|
|
.Fn SDP_PUT128 "l" "cp"
|
||
|
|
.Ft void *
|
||
|
|
.Fn sdp_open "bdaddr_t const *l" "bdaddr_t const *r"
|
||
|
|
.Ft void *
|
||
|
|
.Fn sdp_open_local "void"
|
||
|
|
.Ft int32_t
|
||
|
|
.Fn sdp_close "void *xs"
|
||
|
|
.Ft int32_t
|
||
|
|
.Fn sdp_error "void *xs"
|
||
|
|
.Ft int32_t
|
||
|
|
.Fn sdp_search "void *xs" "u_int32_t plen" "u_int16_t const *pp" "u_int32_t alen" "u_int32_t const *ap" "u_int32_t vlen" "sdp_attr_t *vp"
|
||
|
|
.Ft char const * const
|
||
|
|
.Fn sdp_attr2desc "u_int16_t attr"
|
||
|
|
.Ft char const * const
|
||
|
|
.Fn sdp_uuid2desc "u_int16_t uuid"
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
The
|
||
|
|
.Fn SDP_GET8 ,
|
||
|
|
.Fn SDP_GET16 ,
|
||
|
|
.Fn SDP_GET32 ,
|
||
|
|
.Fn SDP_GET64
|
||
|
|
and
|
||
|
|
.Fn SDP_GET128
|
||
|
|
macros are used to get byte, short, long, long long and 128-bit integer
|
||
|
|
from the buffer pointed by
|
||
|
|
.Vt cp
|
||
|
|
pointer. The pointer is automatically advanced.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn SDP_PUT8 ,
|
||
|
|
.Fn SDP_PUT16 ,
|
||
|
|
.Fn SDP_PUT32 ,
|
||
|
|
.Fn SDP_PUT64
|
||
|
|
and
|
||
|
|
.Fn SDP_PUT128
|
||
|
|
macros are used to put byte, short, long, long long and 128-bit integer
|
||
|
|
into the buffer pointed by
|
||
|
|
.Vt cp
|
||
|
|
pointer. The pointer is automatically advanced.
|
||
|
|
.Pp
|
||
|
|
.Fn sdp_open
|
||
|
|
and
|
||
|
|
.Fn sdp_open_local
|
||
|
|
functions each return a pointer to an opaque object describing SDP session.
|
||
|
|
The
|
||
|
|
.Vt l
|
||
|
|
argument passed to
|
||
|
|
.Fn sdp_open
|
||
|
|
function should point to a source BD_ADDR.
|
||
|
|
If source BD_ADDR is
|
||
|
|
.Dv NULL
|
||
|
|
then source address
|
||
|
|
.Dv NG_HCI_BDADDR_ANY
|
||
|
|
is used.
|
||
|
|
The
|
||
|
|
.Vt r
|
||
|
|
argument passed to
|
||
|
|
.Fn sdp_open
|
||
|
|
function should point to a non
|
||
|
|
.Dv NULL
|
||
|
|
remote BD_ADDR.
|
||
|
|
Remote BD_ADDR can not be
|
||
|
|
.Dv NG_HCI_BDADDR_ANY .
|
||
|
|
The
|
||
|
|
.Fn sdp_open_local
|
||
|
|
function takes no arguments and opens a connection to a local SDP server.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn sdp_close
|
||
|
|
function terminates active SDP session and deletes SDP session object.
|
||
|
|
The
|
||
|
|
.Vt xs
|
||
|
|
parameter should point to a valid SDP session object created with
|
||
|
|
.Fn sdp_open
|
||
|
|
or
|
||
|
|
.Fn sdp_open_local .
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn sdp_error
|
||
|
|
function returns last error that is stored inside SDP session object.
|
||
|
|
The
|
||
|
|
.Vt xs
|
||
|
|
parameter should point to a valid SDP session object created with
|
||
|
|
.Fn sdp_open
|
||
|
|
or
|
||
|
|
.Fn sdp_open_local .
|
||
|
|
The error value returned can be converted to a human readable message by
|
||
|
|
calling
|
||
|
|
.Xr strerror 3
|
||
|
|
function.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn sdp_search
|
||
|
|
function is used to perform SDP Service Search Attribute Request.
|
||
|
|
The
|
||
|
|
.Vt xs
|
||
|
|
parameter should point to a valid SDP session object created with
|
||
|
|
.Fn sdp_open
|
||
|
|
or
|
||
|
|
.Fn sdp_open_local .
|
||
|
|
The
|
||
|
|
.Vt pp
|
||
|
|
parameter is a Service Search Pattern - an array of one or more Service
|
||
|
|
Class IDs.
|
||
|
|
The maximum number of Service Class IDs in the array is 12.
|
||
|
|
The
|
||
|
|
.Vt plen
|
||
|
|
parameter is the length of the Service Search pattern.
|
||
|
|
The
|
||
|
|
.Vt ap
|
||
|
|
parameter is a Attribute ID Range List - an array of one or more SDP Attribute
|
||
|
|
ID Range. Each attribute ID Range is encoded as a 32-bit unsigned integer data
|
||
|
|
element, where the high order 16 bits are interpreted as the beginning
|
||
|
|
attribute ID of the range and the low order 16 bits are interpreted as the
|
||
|
|
ending attribute ID of the range.
|
||
|
|
The attribute IDs contained in the Attribute ID Ranges List must be listed in
|
||
|
|
ascending order without duplication of any attribute ID values.
|
||
|
|
Note that all attributes may be requested by specifying a range of
|
||
|
|
0x0000-0xFFFF.
|
||
|
|
The
|
||
|
|
.Vt alen
|
||
|
|
parameter is the length of the Attribute ID Ranges List.
|
||
|
|
The
|
||
|
|
.Fn SDP_ATTR_RANGE "lo" "hi"
|
||
|
|
macro can be used to prepare Attribute ID Range.
|
||
|
|
The
|
||
|
|
.Vt vp
|
||
|
|
parameter should be an array of
|
||
|
|
.Vt sdp_attr_t
|
||
|
|
structures.
|
||
|
|
Each
|
||
|
|
.Vt sdp_attr_t
|
||
|
|
structure describes single SDP attribute and defined as follows:
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
struct sdp_attr {
|
||
|
|
u_int16_t flags;
|
||
|
|
#define SDP_ATTR_OK (0 << 0)
|
||
|
|
#define SDP_ATTR_INVALID (1 << 0)
|
||
|
|
#define SDP_ATTR_TRUNCATED (1 << 1)
|
||
|
|
u_int16_t attr; /* SDP_ATTR_xxx */
|
||
|
|
u_int32_t vlen; /* length of the value[] in bytes */
|
||
|
|
u_int8_t *value; /* base pointer */
|
||
|
|
};
|
||
|
|
typedef struct sdp_attr sdp_attr_t;
|
||
|
|
typedef struct sdp_attr * sdp_attr_p;
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
The caller of the
|
||
|
|
.Fn sdp_search
|
||
|
|
function is expected to prepare the array of
|
||
|
|
.Vt sdp_attr
|
||
|
|
structures and for each element of the array both
|
||
|
|
.Vt vlen
|
||
|
|
and
|
||
|
|
.Vt value
|
||
|
|
must be set.
|
||
|
|
The
|
||
|
|
.Fn sdp_search
|
||
|
|
function will fill each
|
||
|
|
.Vt sdp_attr_t
|
||
|
|
structure with attribute and value, i.e. it will set
|
||
|
|
.Vt flags ,
|
||
|
|
.Vt attr
|
||
|
|
and
|
||
|
|
.Vt vlen
|
||
|
|
fields.
|
||
|
|
The actual value of the attribute will be copied into
|
||
|
|
.Vt value
|
||
|
|
buffer.
|
||
|
|
Note: attributes are returned in the order they appear in the Service Search
|
||
|
|
Attribute Response.
|
||
|
|
SDP server could return several attributes for the same record.
|
||
|
|
In this case the order of the attributes will be: all attributes for the first
|
||
|
|
records, then all attributes for the secord record etc.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn sdp_attr2desc
|
||
|
|
and
|
||
|
|
.Fn sdp_uuid2desc
|
||
|
|
functions each take a numeric attribute ID/UUID value and convert it to a
|
||
|
|
human readable description.
|
||
|
|
.Sh EXAMPLES
|
||
|
|
The following example shows how to get
|
||
|
|
.Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST
|
||
|
|
attribute for the
|
||
|
|
.Dv SDP_SERVICE_CLASS_SERIAL_PORT
|
||
|
|
service from the remote device.
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
bdaddr_t remote;
|
||
|
|
u_int8_t buffer[1024];
|
||
|
|
void *ss = NULL;
|
||
|
|
u_int16_t serv = SDP_SERVICE_CLASS_SERIAL_PORT;
|
||
|
|
u_int32_t attr = SDP_ATTR_RANGE(
|
||
|
|
SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST,
|
||
|
|
SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST);
|
||
|
|
sdp_attr_t proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer };
|
||
|
|
|
||
|
|
/* Obtain/set remote BDADDR here */
|
||
|
|
|
||
|
|
if ((ss = sdp_open(NG_HCI_BDADDR_ANY, remote)) == NULL)
|
||
|
|
/* exit ENOMEM */
|
||
|
|
if (sdp_error(ss) != 0)
|
||
|
|
/* exit spd_error(ss) */
|
||
|
|
|
||
|
|
if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0)
|
||
|
|
/* exit sdp_error(ss) */
|
||
|
|
|
||
|
|
if (proto.flags != SDP_ATTR_OK)
|
||
|
|
/* exit see proto.flags for details */
|
||
|
|
|
||
|
|
/* If we got here then we have attribute value in proto.value */
|
||
|
|
.Ed
|
||
|
|
.Sh DIAGNOSTICS
|
||
|
|
Both
|
||
|
|
.Fn sdp_open
|
||
|
|
and
|
||
|
|
.Fn sdp_open_local
|
||
|
|
will return
|
||
|
|
.Dv NULL
|
||
|
|
if memory allocation for the new SDP session object fails.
|
||
|
|
If the new SDP object was created then caller is still expected to call
|
||
|
|
.Fn sdp_error
|
||
|
|
to check if there was connection error.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn sdp_search
|
||
|
|
function returns non-zero value on error.
|
||
|
|
The caller is expected to call
|
||
|
|
.Fn sdp_error
|
||
|
|
to find out more about error.
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr bluetooth 3 ,
|
||
|
|
.Xr strerror 3
|
||
|
|
.Sh BUGS
|
||
|
|
This is client only library for now.
|
||
|
|
Please report bugs if found.
|
||
|
|
.Sh AUTHORS
|
||
|
|
.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
|