--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-70339E6A-63CD-5A74-846C-50771FDAC763.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,117 @@
+<?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>
\ No newline at end of file