<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-5E1C24CA-2F82-5E30-8981-0F343FF2BD89"><title>Bluetooth Client Library (Bluetooth User) Overview</title><shortdesc>The Bluetooth Client Library component (Bluetooth User) provides APIs for configuring and managing Bluetooth® connections. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-9C5228B8-0D60-5107-96D5-6BAF1143EED5"><title>Purpose</title> <p>The Symbian OS Bluetooth subsystem provides developer support for creating Bluetooth aware applications. Bluetooth User is a collection of components and their corresponding DLLs that set up, configure and manage Bluetooth sockets, access the HCI, and configure Bluetooth AV sessions. </p> </section> <section><title>Key concepts and terms</title> <p>The following terms are used: </p> <dl><dlentry><dt>Bluetooth library</dt> <dd><p>Provides setup and configuration details such as device type, Bluetooth sockets and link management options. </p> </dd> </dlentry> <dlentry><dt>Bluetooth sockets</dt> <dd><p>Sockets provided by <xref href="GUID-3C8F56AE-2C48-3DC5-83E8-7B3EC8E80D50.dita"><apiname>CBluetoothSocket</apiname></xref> instead of <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref>. <xref href="GUID-3C8F56AE-2C48-3DC5-83E8-7B3EC8E80D50.dita#GUID-3C8F56AE-2C48-3DC5-83E8-7B3EC8E80D50/GUID-0628C20E-815E-351D-82DB-BC19CF01BC5C"><apiname>CBluetoothSocket::Connect()</apiname></xref> takes a <xref href="GUID-DFE19A3C-9E18-3B27-8748-FA0DB48A599C.dita"><apiname>TBTSockAddr</apiname></xref>, whose constructor <xref href="GUID-DFE19A3C-9E18-3B27-8748-FA0DB48A599C.dita#GUID-DFE19A3C-9E18-3B27-8748-FA0DB48A599C/GUID-5FD02D4D-902F-36C2-9B46-DEAAF302D0F1"><apiname>TBTSockAddr::TBTSockAddr()</apiname></xref> takes a <xref href="GUID-66228064-B6E7-3CE9-8F5E-5DED4CD9A49B.dita"><apiname>TSockAddr</apiname></xref>. </p> </dd> </dlentry> <dlentry><dt>Audio / Visual library</dt> <dd><p>Provides useful setup, configuration and error handling for Audio / Video applications. </p> </dd> </dlentry> <dlentry><dt>HCI direct access</dt> <dd><p>Used by licensees to customise HCI functionality. See <xref href="GUID-A5B36AF0-D335-3627-9142-27860325DE1F.dita"><apiname>RHCIDirectAccess</apiname></xref>. </p> </dd> </dlentry> </dl> </section> <section><title>Bluetooth Client Library Summary</title> <p>Bluetooth Client Library (Bluetooth User) is a collection of helper APIs. </p> <ul><li id="GUID-E5700CC0-A71F-50C7-9EE2-15C1D8331D97"><p>Bluetooth library </p> </li> <li id="GUID-20A70C47-E00E-5485-A6E4-1461B36BCC24"><p>Audio / Video library </p> </li> <li id="GUID-6B1C07B3-FE21-5526-B0FD-D552FB3D9BD0"><p>HCI commands </p> </li> </ul> <p>We will briefly look at each of the above components below. </p> <p><b>Bluetooth library</b> </p> <p>Primarily this component provides Bluetooth sockets. There are two kinds of sockets, they are: </p> <ol id="GUID-CA38EFFF-0198-521C-BE33-2B1E1825F4A0"><li id="GUID-C0351EE7-A66F-57DF-9FB1-19F1FFA74713"><p>ACL (<xref href="GUID-3C8F56AE-2C48-3DC5-83E8-7B3EC8E80D50.dita"><apiname>CBluetoothSocket</apiname></xref>) and </p> </li> <li id="GUID-A9FB715D-98A8-5AC7-8EDC-7548FD622154"><p>SCO (<xref href="GUID-31DE8DB6-1562-3C53-8B03-BCA82DA32E35.dita"><apiname>CBluetoothSynchronousLink</apiname></xref>) sockets. </p> </li> </ol> <table id="GUID-DE681FA8-0F5D-572F-88CC-4EAA0BA4D136"><tgroup cols="1"><colspec colname="col0"/><thead><row><entry>DLL</entry> </row> <row><entry> Library </entry> </row> <row><entry> Profile </entry> </row> <row><entry> Protocol </entry> </row> </thead> <tbody><row><entry><p> <filepath>bluetooth.dll</filepath>  </p> </entry> </row> <row><entry><p> <filepath>bluetooth.lib</filepath>  </p> </entry> </row> <row><entry><p> <xref href="GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7.dita#GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7/GUID-BCA99FAB-1825-56A0-9D06-926B30C0FFBA">GAP</xref>, <xref href="GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7.dita#GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7/GUID-74CDD0F3-3901-5F23-8FE8-B23FEB6DB243">SPP</xref>, <xref href="GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7.dita#GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7/GUID-C7894668-B9C0-5C31-BD24-8A3753DF1F6C">GOEP</xref>, <xref href="GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7.dita#GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7/GUID-85C0DABF-1EC0-5B25-9E36-72C42E5D4A97">PAN</xref>  </p> </entry> </row> <row><entry><p> <xref href="GUID-7640F878-2D99-52C8-ACBE-8B77A714E081.dita">Bluetooth protocol stack</xref>  </p> </entry> </row> </tbody> </tgroup> </table> <p><b>Bluetooth library classes </b> </p> <p>Bluetooth library provides classes to handle: </p> <ol id="GUID-C5A70630-D0AD-5D28-B0E7-D37965DC52B6"><li id="GUID-A524F934-C64F-5845-9A0B-5BF9ADA1B57C"><p>Bluetooth Sockets </p> <ul><li id="GUID-8A553351-A8F5-5C14-B824-D844E4CA62AF"><p> <xref href="GUID-3C8F56AE-2C48-3DC5-83E8-7B3EC8E80D50.dita"><apiname>CBluetoothSocket</apiname></xref>  </p> </li> <li id="GUID-A4EB20A6-9AC9-59CA-9BD2-F3FCFD68AA69"><p> <xref href="GUID-31DE8DB6-1562-3C53-8B03-BCA82DA32E35.dita"><apiname>CBluetoothSynchronousLink</apiname></xref>  </p> </li> <li id="GUID-49F0218F-A590-5B5C-AA38-0BA2706A82A7"><p> <xref href="GUID-4F2C6762-8FB1-31B2-BB6A-280BCF75F935.dita"><apiname>CBluetoothPhysicalLinks</apiname></xref>  </p> </li> </ul> </li> <li id="GUID-8413E26F-D666-5CCF-A859-776022F8E674"><p>Notifiers </p> <ul><li id="GUID-BB7D2901-9A51-521D-99E8-B0F8BA93F971"><p> <xref href="GUID-13D8E197-DFC3-3382-B8B5-C730D9FCED7A.dita"><apiname>MBluetoothPhysicalLinksNotifier</apiname></xref>  </p> </li> <li id="GUID-944C3FD5-6B7E-562F-A929-1760CB1295B2"><p> <xref href="GUID-9C1D6AA1-7006-3D2C-8B44-909E67C1655B.dita"><apiname>MBluetoothSocketNotifier</apiname></xref>  </p> </li> <li id="GUID-03732B85-0F1A-5617-8C0B-88666716002D"><p> <xref href="GUID-88678886-6677-32F2-844D-3390B6BDF2F3.dita"><apiname>MBluetoothSynchronousLinkNotifier</apiname></xref>  </p> </li> </ul> </li> <li id="GUID-280291A5-8D21-5829-9D4D-F6F4596F8452"><p>Utility classes </p> <ul><li id="GUID-5EE7CB25-3094-5528-BE04-E229BAB27341"><p> <xref href="GUID-BC537778-EFAA-358F-B0A0-1291B0DDE9C0.dita"><apiname>RBTPhysicalLinkAdapter</apiname></xref>  </p> </li> <li id="GUID-422C7839-31C2-5555-88D8-8B64D2D7C922"><p> <xref href="GUID-AB95F67F-EAC6-311B-AFE8-A21EFD811DF2.dita"><apiname>RBluetoothPowerSwitch</apiname></xref>  </p> </li> <li id="GUID-D6A543BA-27F0-53A1-A8BD-B1B358FF2850"><p> <xref href="GUID-A5B36AF0-D335-3627-9142-27860325DE1F.dita"><apiname>RHCIDirectAccess</apiname></xref>  </p> </li> </ul> </li> </ol> <p><b>Audio / Video library</b> </p> <p>The Bluetooth Audio / Video library provides API classes to configure a system as defined by the AV profile. </p> <table id="GUID-23E688FF-FF72-57B5-8553-FC65C854F04C"><tgroup cols="1"><colspec colname="col0"/><thead><row><entry>DLL</entry> </row> <row><entry> Library </entry> </row> <row><entry> Profile </entry> </row> <row><entry> Protocol </entry> </row> </thead> <tbody><row><entry><p> <filepath>bluetoothav.dll</filepath>  </p> </entry> </row> <row><entry><p> <filepath>bluetoothav.lib</filepath>  </p> </entry> </row> <row><entry><p> <xref href="GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7.dita#GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7/GUID-7251B0E5-D6B1-524B-9714-6A469F8E1CB3">AVRCP</xref> and <xref href="GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7.dita#GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7/GUID-3ABC26C2-D65A-5577-B9B2-0A613D48D49B">GAVDP</xref>  </p> </entry> </row> <row><entry><p> <xref href="GUID-7640F878-2D99-52C8-ACBE-8B77A714E081.dita#GUID-7640F878-2D99-52C8-ACBE-8B77A714E081/GUID-306539D4-B048-5A73-8ABF-A2617462ACDC">AVCTP</xref> and <xref href="GUID-7640F878-2D99-52C8-ACBE-8B77A714E081.dita#GUID-7640F878-2D99-52C8-ACBE-8B77A714E081/GUID-9AED70E1-E5B5-537C-ADB6-BEDB7F798D99">AVDTP</xref>  </p> </entry> </row> </tbody> </tgroup> </table> <p><b>Audio / Video library namespaces </b> </p> <p>The Bluetooth AV library provides the following namespaces: </p> <ul><li id="GUID-C44FB716-D52A-5C0E-A65B-281F10F141C6"><p> <xref href="GUID-5BC30072-02EC-30DA-A698-965AE4AB5A67.dita"><apiname>SymbianAvctp</apiname></xref>  </p> </li> <li id="GUID-C7F8DD0E-63B4-5EEB-A9A4-43F1CF8CD480"><p> <xref href="GUID-1A71EE7B-8A52-3903-A8F7-DBA5550A5E49.dita"><apiname>SymbianBluetoothAV</apiname></xref>  </p> </li> <li id="GUID-89567141-EAE2-5EFB-B0F9-0679CD9C6A65"><p> <xref href="GUID-DA7F0412-14E2-3E44-9D2C-FC5913FEB056.dita"><apiname>SymbianSBC</apiname></xref>  </p> </li> </ul> </section> <section><title>Typical uses</title> <p>We will look at common tasks associated with some of the Bluetooth User APIs here. </p> <p><b>Task backgrounder</b> </p> <p>Before setting up a Bluetooth connection you need to think about the kind of connection needed and how best to go about setting up the connection. These topics will get you started. </p> <ol id="GUID-59D9340C-3250-5D4F-8F0D-1AFC66A9BD1C"><li id="GUID-F05DEDC5-D414-5B3D-AC44-24E6FCB989CD"><p> <xref href="GUID-58F65411-CF08-5F46-8222-3FDB9E571FCC.dita"> Connecting to Remote Devices</xref>  </p> <p>This is a set of tutorial documents, the contents of which have been split up here according to main functionality grouping. </p> <ul><li id="GUID-68D85D8A-D947-5444-A657-335E9CB373D4"><p> <xref href="GUID-301488F8-B6D8-569A-B05E-19B740FE4C00.dita">Selecting a Remote Device</xref>  </p> <p>Discusses some of the issues about selecting a remote device that should be considered before writing any code. </p> </li> </ul> </li> </ol> <p><b>Socket tasks</b> </p> <p>The following tutorial guides deal mainly with sockets. </p> <ol id="GUID-9CF35DD6-055D-5F26-ADF3-CC5C9DCDA514"><li id="GUID-27B6B551-B004-5D6D-9A18-2A4BAF21AF19"><p> <b>Connecting to Remote Devices</b>  </p> <ul><li id="GUID-1761A972-2C81-56E9-80EB-35F666E11200"><p> <xref href="GUID-CED041C8-D68D-55D1-957E-1A48EEFFF851.dita">Inquiring About Remote Devices</xref>  </p> <p>This tutorial shows you how to create a Bluetooth socket, make an inquiry for a remote device address and establish a connection to the remote device. </p> </li> </ul> </li> <li id="GUID-5D33C242-D8DA-59E6-9D47-0BF9AD8FEB92"><p> <xref href="GUID-70339E6A-63CD-5A74-846C-50771FDAC763.dita">Listening for Incoming Bluetooth Connections</xref>  </p> <p>This tutorial shows you how to set up a Bluetooth socket to listen for a connect attempt by remote devices. </p> </li> </ol> <p><b>Notifier tasks</b> </p> <p>Notifiers are used to manage aspects of a Bluetooth connection. </p> <ol id="GUID-14C342DA-7EAC-5479-831D-B12141AF6D1E"><li id="GUID-12B970D9-57B0-5621-A79E-25E540FF1DEC"><p> <b>Connecting to Remote Devices</b>  </p> <ul><li id="GUID-70CE1084-5ED6-540C-947C-43BB35D55E06"><p> <xref href="GUID-A24D2CEF-88C9-5C63-A14D-85EFFBEF3C92.dita">Connecting and Transferring Data to a Remote Device</xref>  </p> <p>This tutorial shows you how to work with a remote device over Bluetooth once the connection is established. </p> </li> </ul> </li> </ol> <p><b>Utility tasks</b> </p> <p>These tasks show you how to do things like configure a local or remote device, access protocol level data and send HCI commands. </p> <ol id="GUID-7548657E-2617-55FD-B707-1008656F58CE"><li id="GUID-BBBB4630-3486-5407-9DD2-8DB92552562D"><p> <b>Connecting to Remote Devices</b>  </p> <ul><li id="GUID-EBF38981-0A1B-5EA1-AD62-506DFB171E3B"><p> <xref href="GUID-A13494B9-C1E4-506A-B236-8AE0A6D6D557.dita">Inquiring About Services on a Remote Device</xref>  </p> <p>This tutorial shows you how to inspect remote devices for suitability before connecting to them. </p> </li> <li id="GUID-928A85EC-A947-5A6D-A21D-3ED175769A9C"><p> <xref href="GUID-783D0B50-0E8A-5199-A07E-749D4A71E671.dita">Processing an Extended Inquiry Response</xref>  </p> <p>This tutorial shows you how to retrieve and process the data from a Bluetooth Extended Inquiry Response (EIR). </p> </li> <li id="GUID-54DEF2FF-C003-5E36-8EB8-930BDE5E876F"><p> <xref href="GUID-4F0C4B9D-AA42-59C4-900A-7045FEAAF2F4.dita">Using Security on Outgoing Sockets </xref>  </p> <p>This tutorial shows you how to configure the Bluetooth sockets for authentication or encryption based security. </p> </li> </ul> </li> <li id="GUID-9D6FF0EE-7B9E-5618-B3FE-00625C2BFDDC"><p> <xref href="GUID-834BD3BB-B39C-5EE9-8A62-9DC435930F95.dita">Handling the Local Device Name</xref>  </p> <p>This code shows you how to set and get the local device name. </p> </li> <li id="GUID-FFF19593-1341-5FC0-BFCC-C2EDC4723B91"><p> <xref href="GUID-FDA7B932-B9C6-502D-8699-C18C8D86BCC6.dita">Performing Low-level Configuration</xref>  </p> <p>This tutorial introduces you to HCI, L2CAP and RFCOMM commands and options and shows you how to read the Class of device attribute on an L2CAP socket. </p> </li> <li id="GUID-BFD12613-7CCC-5CAA-B092-D132517016CF"><p> <xref href="GUID-5C63EF5C-826D-5838-BB7E-12FF4EA1DFCE.dita">Debugging the Host Controller</xref>  </p> <p>This tutorial shows you how to issue vendor specific HCI commands via the stack. </p> </li> <li id="GUID-EBC45771-E3EA-5A94-BACE-22FF731D1700"><p> <xref href="GUID-01A0682A-50B1-57AB-9939-6CC8FCCD782D.dita">Disconnecting ACL links</xref>  </p> <p>This tutorial shows you how to drop a remote device from a connection while leaving the socket up. </p> </li> </ol> <p><b>Audio / Video tasks</b> </p> <p>Currently there are no tutorials for the Audio / Video profiles. </p> </section> </conbody><related-links><link href="GUID-7F2C1C45-43FA-5F19-81E3-4DBC0328E4A7.dita"><linktext>Bluetooth Sockets

                Overview</linktext> </link> <link href="GUID-F2A793F1-A5B5-526B-B147-771D440B13A2.dita"><linktext>Bluetooth Extended Inquiry

                Response</linktext> </link> </related-links></concept>