<?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 id="GUID-70339E6A-63CD-5A74-846C-50771FDAC763" xml:lang="en"><title>Listening
for incoming Bluetooth connections</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This document describes how a Bluetooth device can allow incoming remote
device connections. </p>
<p>Incoming Bluetooth connection examples include: </p>
<ul>
<li id="GUID-F1021810-A06F-5549-837A-3C8B2D99BC19"><p>one end of a chat application, </p> </li>
<li id="GUID-C9417947-7464-5AD2-9DF0-5EC906CF1441"><p>the Audio Gateway role
in HSP (licensee), </p> </li>
<li id="GUID-8662B773-47E0-5C38-B88C-FE18F3370757"><p>or the Gateway in DUNP
(licensee). </p> </li>
</ul>
<p>Incoming requests for a Bluetooth connection are handled through the <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref> API
(as with outgoing connections). </p>
<p>To receive an incoming connection a service must open a listening socket,
register the socket with the Bluetooth security manager, and advertise the
socket, then connection requests can be accepted. </p>
<section><title>How to set up an incoming connection</title><p>The steps are
given below:</p><p><b>Get a connection</b></p><p>Connect to the Sockets Server
and select the protocol to be used. </p><codeblock xml:space="preserve">RSocketServ socketServ;
socketServ.Connect();
_LIT(KL2Cap, "L2CAP"); // or RFCOMM as appropriate</codeblock><p><b>Open a
socket</b></p><p> Open a socket for that protocol. </p><codeblock xml:space="preserve">RSocket listen;
listen.Open(socketServ,KL2Cap);</codeblock><p><b>Create the Bluetooth socket
address</b></p><p> Create a Bluetooth socket address object (<xref href="GUID-DFE19A3C-9E18-3B27-8748-FA0DB48A599C.dita"><apiname>TBTSockAddr</apiname></xref>)
and set its port to the PSM or server channel (for L2CAP or RFCOMM respectively)
and bind the socket to this address. Note you do not have to set the local
Bluetooth device address in the address. </p><codeblock xml:space="preserve">TBTSockAddr addr;
addr.SetPort(KListeningPSM);
User::LeaveIfError(listen.Bind(addr));</codeblock><p><b>Register with the
Bluetooth security manager</b></p><p>Add the connection to the Bluetooth security
manager. Incoming
connections will not work unless they have been registered with the Bluetooth
security manager, thus allowing the incoming traffic through the security
wall,
which by default denies access to all connection attempts. 
</p><codeblock xml:space="preserve">RBTSecuritySettings secset;
TRequestStatus status;
TBTServiceSecurity serviceSecurity(aMyUid,KSolBtRFCOMM,aChannel);
serviceSecurity.SetAuthentication(EFalse);
serviceSecurity.SetEncryption(EFalse);
serviceSecurity.SetAuthorisation(EFalse);
serviceSecurity.SetDenied(EFalse);
User::LeaveIfError(secset.RegisterService(serviceSecurity, status));
User::WaitForRequest(status);
test(status.Int()==KErrNone);</codeblock><p>The security profile is created
and packaged in serviceSecurity and
applied using <xref href="GUID-D536FA83-2535-3BF2-AC0D-EA0C7CA806BA.dita#GUID-D536FA83-2535-3BF2-AC0D-EA0C7CA806BA/GUID-026CE232-E988-3C7E-A01D-6C70A3CCFC63"><apiname>RBTSecuritySettings::RegisterService()</apiname></xref>. The
 security profile overrides the default security settings thereby allowing
   incoming connections. </p><p><b>Add to the Bluetooth Service Discovery
Database</b></p><p>Enter record into the database. 
<codeblock xml:space="preserve">RSdpDatabase sdprec;
TSdpServRecordHandle recordHandle = 0;
sdprec.CreateServiceRecordL(*UUIDlist, recordHandle);
</codeblock></p><p><b>Start listening for connections</b></p>  Tell the socket
to listen for incoming connections using <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita#GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0/GUID-5360AE38-877F-3F9C-971C-4BCE781B5735"><apiname>RSocket::Listen()</apiname></xref>.

<p><codeblock xml:space="preserve">User::LeaveIfError(listen.Listen(2));</codeblock></p><p><b>Start
listening for data over a connection</b></p> Create a blank socket and pass
it to the listening socket through
<xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita#GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0/GUID-3D6737DD-447F-323D-9466-0B910A1FFC6A"><apiname>RSocket::Accept()</apiname></xref>. When this call completes, the socket
passed in a parameter is now fully connected and can be used to send and receive
data. The listening socket remains in place, ready for another socket to be
passed in when the program can handle another connection.<codeblock xml:space="preserve">RSocket accept;
TRequestStatus status;
User::LeaveIfError(accept.Open(socketServ));
listen.Accept(accept,status);
User::WaitForRequest(status);</codeblock><p><b>Shutdown remote Bluetooth connection</b></p><p>Shutdown
connection and unregister security settings. When the
receiver wishes to shutdown, it must ensure that it closes the listening socket
 as well as any connected ones. This releases the Bluetooth connection to
other
applications. 
</p><codeblock xml:space="preserve">accept.Close();
listen.Close();
secset.UnregisterService(KSolBtL2CAP, status);
socketServ.Close();</codeblock><p>The socket server is closed using the
<codeph>RHandleBase::Close()</codeph> method. It will close the handle to
the socket server and destroy it if there are no other referencing objects.

</p></section>
<section><title>Notes</title><p>If the channel is already in use, as indicated
if <codeph>Bind()</codeph> returns an error, you can find a free channel using
the <xref href="GUID-6BFA5331-7860-313B-97A8-7A61562CEE38.dita"><apiname>KRFCOMMGetAvailableServerChannel</apiname></xref> ioctl. </p><p>Also
search the Symbian DevNet for white papers and example applications. </p></section>
<section><title>Finding more...</title><p>  For more information on: </p><ul>
<li><p> setting security requirements for incoming connections to the service,
see [xref href="GUID-A035B592-F423-5980-8E7E-E726CF24CF3E"]Using Bluetooth
Security Manager[/xref]</p></li>
<li><p> advertising the service's availability, see [xref href="GUID-756D831F-F302-594C-8116-144358DD8442"]Using
Bluetooth Service Discovery Database[/xref]</p></li>
</ul></section>
<section><title>Where Next?</title> <p>This tutorial set takes you through
all the steps involved in setting up and communicating over a Bluetooth connection. </p> <ul>
<li id="GUID-3B52879B-627A-5E83-975F-3DC741739E28"><p> <b>Listening for Incoming
Bluetooth Connections</b> - This document </p> </li>
<li id="GUID-8BA24558-70C1-562C-8A18-129958685E79"><p> <xref href="GUID-834BD3BB-B39C-5EE9-8A62-9DC435930F95.dita">Handling
the Local Device Name</xref>  </p> </li>
<li id="GUID-3E74535E-235C-5DF2-9438-101BA38F8ACB"><p> <xref href="GUID-FDA7B932-B9C6-502D-8699-C18C8D86BCC6.dita">Performing
Low-level Configuration</xref>  </p> </li>
<li id="GUID-431BDE6E-163A-5F9F-93CE-B945A25AF649"><p> <xref href="GUID-5C63EF5C-826D-5838-BB7E-12FF4EA1DFCE.dita">Debugging
the Host Controller</xref>  </p> </li>
<li id="GUID-979AE36E-8A4C-500B-B600-DBB8E589C33E"><p> <xref href="GUID-01A0682A-50B1-57AB-9939-6CC8FCCD782D.dita">Disconnecting
ACL links</xref>  </p> </li>
</ul> </section>
</conbody></concept>