diff options
author | Maksim Yevmenkin <emax@FreeBSD.org> | 2003-10-12 22:04:24 +0000 |
---|---|---|
committer | Maksim Yevmenkin <emax@FreeBSD.org> | 2003-10-12 22:04:24 +0000 |
commit | 0986ab12e44caea472245845f9a89ced4f137d73 (patch) | |
tree | 0ae0c2be63f9f9161693789721b96beb9cabcc77 /lib/libsdp/sdp.3 | |
parent | 907d8667501d77122c9b7016fc907f842f263bb7 (diff) | |
download | src-0986ab12e44caea472245845f9a89ced4f137d73.tar.gz src-0986ab12e44caea472245845f9a89ced4f137d73.zip |
Update Bluetooth code.
Reviewed by: M. Warner Losh <imp@bsdimp.com>; John Hay <jhay@freebsd.org>
Approved by: M. Warner Losh <imp@bsdimp.com> (mentor)
Notes
Notes:
svn path=/head/; revision=121054
Diffstat (limited to 'lib/libsdp/sdp.3')
-rw-r--r-- | lib/libsdp/sdp.3 | 309 |
1 files changed, 309 insertions, 0 deletions
diff --git a/lib/libsdp/sdp.3 b/lib/libsdp/sdp.3 new file mode 100644 index 000000000000..94ef34e9d147 --- /dev/null +++ b/lib/libsdp/sdp.3 @@ -0,0 +1,309 @@ +.\" 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 |