<?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-91C4F00B-E241-57DC-8520-8C16A302C983"><title>Creating a Personal Area Network (PAN) </title><prolog><metadata><keywords/></metadata></prolog><conbody><p>We are looking at a two device PAN in this tutorial. So if you want to run the example it must be installed on both devices. One device will initiate a connection and the other will listen for a connection. We will refer to the listener as D1 and the initiator as D2 when necessary. </p> <p><b>Using the Tutorial </b> </p> <p>The code fragments in this tutorial are derived from the Bluetooth Example application available in <filepath>/src/COMMON/DEVELOPERLIBRARY/examples/Bluetooth/BTExample1</filepath>. Although the code has been reformatted to the requirements of the tutorial there is always enough information included with the code to find the actual example code. </p> <p><b>Intended Audience: </b> </p> <p>This tutorial is designed for Symbian licensees only. Several APIs mentioned ad used throughout this tutorial series are only available in a device creators kit environment. </p> <p><b>Basic procedure: </b> </p> <p>The high level steps to create a PAN are: </p> <ul><li id="GUID-72B7C882-CF40-5A36-A9DF-9282433F42E3"><p>Configure the Pan services extension table and the LAN services table in CommDB. </p> </li> <li id="GUID-8A972D2A-0093-59C6-9051-31B5C68BE785"><p>Load the Bluetooth Stack </p> </li> <li id="GUID-A574A7D0-7E53-5270-A912-31CD9BA31165"><p>Start the PAN connection </p> </li> </ul> <section><title>Configuring CommDB PAN IAP</title> <p>The PAN IAP (<codeph>PANServiceExtensions</codeph> table) will need to be configured for both devices. D1 will need to start a PAN listening connection. D2 will look for a listening device (D1) and connect to that device. </p> <p>To configure CommDB tables for PAN do the following: </p> <ol id="GUID-E4455A56-4DF3-5B28-B181-4B4D804BBCD0"><li id="GUID-657F3E7E-18BE-5D70-B19B-026F821D3E1B"><p>Open CommDB. </p> <codeblock id="GUID-2F0F9D67-416C-59E6-8E66-7A9A47543387" xml:space="preserve">CCommsDatabase* db = CCommsDatabase::NewL();

CleanupStack::PushL(db);</codeblock> </li> <li id="GUID-6D26A97B-290F-5C4F-B5A4-3435BA9E55F5"><p>Open a view on the <codeph>PANServiceExtensionsTable1</codeph> table. </p> <codeblock id="GUID-4C3A2F04-4F43-5A5C-B826-843794DEA4A3" xml:space="preserve">CCommsDbTableView* tableView =

db->OpenTableLC(TPtrC(PAN_SERVICE_EXTENSIONS));

TBuf<KMaxBufferSize> tableName;

tableView->GotoFirstRecord();

tableView-&gt;ReadTextL(TPtrC(COMMDB_NAME), tableName);</codeblock> <p>Check that we are looking at the correct table. </p> <codeblock id="GUID-C8DB29FE-E08E-5C99-BAE1-C5FD5D5C31C1" xml:space="preserve">if(tableName == TPtrC(_S("PANServiceExtensionsTable1")))</codeblock> <p>The above simply ensures that the table name is what was expected. </p> </li> <li id="GUID-D3729BF0-D099-54C3-A3DF-2E60185B150B"><p>Open the table for editing. </p> <codeblock id="GUID-39F9B0B6-4800-574F-A81B-194B99B2418D" xml:space="preserve">User::LeaveIfError(tableView-&gt;UpdateRecord());</codeblock> </li> <li id="GUID-FE0CE957-3F36-5F2C-8D02-C6A7D020E9CC"><p>Set the device to listen for incoming PAN connection requests if necessary. </p> <codeblock id="GUID-C0C051FD-CC78-5CAD-8F11-32918A62EA07" xml:space="preserve">tableView-&gt;WriteBoolL(TPtrC(PAN_ALLOW_INCOMING),aIsListening);</codeblock> <p>The value of <codeph>aIsListening</codeph> is <codeph>ETrue</codeph> for D1, the listening device. </p> </li> <li id="GUID-8877DB52-0D09-51B7-A70F-9A38C671C6C5"><p>Decide if the device will prompt for remote devices. </p> <codeblock id="GUID-8ED99FED-419C-595B-A255-8B6305ABA1D7" xml:space="preserve">tableView-&gt;WriteBoolL(TPtrC(PAN_PROMPT_FOR_REMOTE_DEVICES),aUsePANNotifier);</codeblock> <p>The value of <codeph>aUsePANNotifier</codeph> is <codeph>EFalse</codeph> when you do not want the user to be prompted for a device. As with step 4 above this is the configuration for D1, the listening device, which will be accepting incoming connections instead of seeking other devices. </p> </li> <li id="GUID-B158348B-A10A-5221-A092-2E76B6C31CF7"><p>Set the PeerMacAddress to the Bluetooth device address of the device joining the PAN if known or to <codeph>NULL</codeph> if not known. </p> <p>D2 will prompt for a Bluetooth device address (<codeph>aDevAddr</codeph>) when making the connection. So if <codeph>aDevAddr</codeph> exists then the device is trying to initiate a PAN with D1, the listening device. The Peer Mac Address of the listener will be returned by the notifier (see "Finding the Bluetooth Device Address") and added to the CommDB table as shown. </p> <codeblock id="GUID-952DBDCE-CBCB-5179-9500-2BD7530A5334" xml:space="preserve">if(aDevAddr)

{

 TBuf<KMaxBufferSize> buf;

 aDevAddr->GetReadable(buf);

 tableView->WriteTextL(TPtrC(PAN_PEER_MAC_ADDRESSES), buf);

}</codeblock> <p>D1 is the listener and so will not need a Bluetooth device address when creating the listening connection. </p> <codeblock id="GUID-5C8FFBDD-B575-51B9-8685-051CB7C47F05" xml:space="preserve">else

{

 tableView->WriteTextL(TPtrC(PAN_PEER_MAC_ADDRESSES), _L(""));

}</codeblock> </li> <li id="GUID-EEFDAB7B-184F-50B9-907B-2EB255BE21FF"><p>Commit the CommDB <codeph>PANServiceExtensionsTable</codeph> changes. </p> <codeblock id="GUID-8AC18999-8FF4-5720-915F-8A1C8D5BB7D2" xml:space="preserve">User::LeaveIfError(tableView-&gt;PutRecordChanges());// Finish update

User::LeaveIfError(db->CommitTransaction());

}</codeblock> </li> </ol> <p>The code above comes from <codeph>CPanConnections::ConfigureIAPL()</codeph> in "<filepath>exampleroot/src/panconnection.cpp</filepath> ". </p> <codeblock id="GUID-CFDC191E-24DA-502B-9A19-AF27101AEA41" xml:space="preserve">ConfigureIAPL(TBool aIsListening,TBTDevAddr* aDevAddr,TBool aUsePANNotifier)

{</codeblock> <p>The function is called when a connection is started. This function is called with three values: aIsListening, aDevAddr, and aUsePANNotifier. </p> <table id="GUID-974413E6-6D10-506F-B8AB-55BCB29F40A0"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Attribute</entry> <entry>Value</entry> </row> </thead> <tbody><row><entry><p> <codeph>aIsListening</codeph>  </p> </entry> <entry><p>when called from <codeph>CPanConnections::StartConnection()</codeph>: </p> <ul><li id="GUID-6DCBB16D-FD7E-5479-A4DD-87E7B4B5497D"><p> <codeph>ETrue</codeph> if the device is listening for an incoming connection. </p> </li> <li id="GUID-7FACD95C-C658-5088-A294-C39B2C1C6513"><p> <codeph>EFalse</codeph> if the device is not listening for an incoming connection. </p> </li> </ul> </entry> </row> <row><entry><p> <codeph>aDevAddr</codeph>  </p> </entry> <entry><p>The Bluetooth device address. </p> </entry> </row> <row><entry><p> <codeph>aUsePANNotifier</codeph>  </p> </entry> <entry><p>when called from <codeph>CActiveConsole::ProcessKeyPressL()</codeph>: </p> <ul><li id="GUID-509E8AC0-CF79-58BD-B4B9-D70E9C6509F4"><p> <codeph>ETrue</codeph> if the PAN notifier is needed. </p> </li> <li id="GUID-5BE885F8-2BEB-5AE9-9423-9D1D7BA66997"><p> <codeph>EFalse</codeph> if the PAN notifier is not needed. </p> </li> </ul> </entry> </row> </tbody> </tgroup> </table> <p id="GUID-DE57E5EA-1C46-5AE4-86CF-06AC92203383"><b>Finding the Bluetooth Device Address</b> </p> <p>The following code shows how to get and manipulate the Bluetooth device address: </p> <codeblock id="GUID-8C4B51E9-5CC2-5EC1-948C-A3DAD2197253" xml:space="preserve">...

TBTDevAddr devAddr; // Bluetooth device address.

//

TMenuMode = iMode; // from console.h

//

iMode = EPan;    //Ask user which device address we should connect to...

RNotifier notify; // get a notifier

User::LeaveIfError(notify.Connect()); // connect to the notifier

TBTDeviceSelectionParamsPckg pckg; // Bluetooth device parameters package

TBTDeviceResponseParamsPckg resPckg; // Response parameters package

TRequestStatus stat;

 // Start the notifier.

notify.StartNotifierAndGetResponse(stat,KDeviceSelectionNotifierUid,pckg,resPckg);

 // Wait for the notifier results.

User::WaitForRequest(stat);

notify.CancelNotifier(KDeviceSelectionNotifierUid);

 // Close the notifier now that we have the device details.

notify.Close();

User::LeaveIfError(stat.Int()); 

 // extract the Bluetooth device address from the notifier results.

devAddr = resPckg().BDAddr();

 // start the PAN connection request, send the Bluetooth device address.

iPanConnection-&gt;StartConnection(&amp;devAddr, EFalse, EFalse);</codeblock> <p> <b>Note:</b> this fragment taken from <codeph>CActiveConsole::ProcessKeyPressL()</codeph> in "<filepath>exampleroot/src/console.cpp</filepath> ". </p> </section> <section><title>Loading the Bluetooth Stack</title> <p>The Bluetooth stack will need to be loaded before a PAN is created. </p> <codeblock id="GUID-D7E947FB-72E5-528F-81C5-B5FAC48F7141" xml:space="preserve">Initialise()

{

 _LIT(KPDDName, "EUART1");        

 _LIT(KLDDName, "ECOMM");    

 TInt rerr = KErrNone;

 rerr = StartC32();// For any Serial comms

 // Load required drivers

 User::LoadPhysicalDevice(KPDDName);

 User::LoadLogicalDevice(KLDDName);

 iSockSvr.Connect();

 TProtocolDesc iProtocolInfo;

 TRequestStatus status;

 iSockSvr.FindProtocol(_L("L2CAP"), iProtocolInfo);

 // After Socket server is connected, start L2CAP protocol

 iSockSvr.StartProtocol(iProtocolInfo.iAddrFamily,

 iProtocolInfo.iSockType,iProtocolInfo.iProtocol, status);

 User::WaitForRequest(status);

}</codeblock> <p>The code above shows how to load the Bluetooth Stack using standard sockets. </p> </section> <section><title>Starting the PAN Connection</title> <p>Now that you have loaded the Bluetooth stack and configured the PAN service extensions table a PAN connection can be opened. </p> <ol id="GUID-8F3A4A6B-8363-5ADB-8A1A-217AE22B40E8"><li id="GUID-C880CE0D-67DB-5B63-92A2-57DCA637A05A"><p>Define the connection preferences. </p> <codeblock id="GUID-C88F1DF0-1AF6-50CA-9ACF-54D90A1109B1" xml:space="preserve"> // EGeneralIAP = 1

PanProfileIAPs iap(EGeneralIAP); // panconnection.h

connPref.SetIapId(iap);

iConnPref.SetDialogPreference(ECommDbDialogPrefDoNotPrompt);

TInt rerr = iSockSvr.Connect();

if(rerr == KErrNone)

{</codeblock> </li> <li id="GUID-C2CAC673-1042-567F-81AD-8D1FD6935776"><p>Load the Bluetooth stack. </p> <codeblock id="GUID-A966FFCA-2422-5472-811D-DEFBC594DC05" xml:space="preserve">Initialise();</codeblock> <p>Covered in the previous section. </p> </li> <li id="GUID-22D2273F-8029-589A-9C0B-85DBDAEB1778"><p>Open the connection </p> <codeblock id="GUID-85DE421F-9882-5BEB-8330-A5EDDE9C4A80" xml:space="preserve">rerr = iConnection.Open(iSockSvr);</codeblock> </li> <li id="GUID-08794D6C-A40C-505B-9EDC-DB012D4D7B1D"><p>Start the session if the connection opened correctly: </p> <codeblock id="GUID-9D85A068-6F17-5A4A-A03E-5292381FB60F" xml:space="preserve">if(rerr == KErrNone)

{

 iConnection.Start(iConnPref,iStat);    

 User::WaitForRequest(iStat);

}

if(iStat==KErrNone)    

{</codeblock> </li> </ol> <p>The code above is derived from <codeph>CPanConnections::StartIAP()</codeph> in "<filepath>exampleroot/src/panconnection.cpp</filepath> ". </p> <p>That's all there is to creating a PAN. </p> </section> <section><title>What's next?</title> <p>Having created a PAN you will need to add and remove devices and close the PAN. The following will help: </p> <ul><li id="GUID-9273F800-3857-51FD-A443-9AC246203FB2"><p> <b>Creating a Personal Area Network (PAN)</b> - This document </p> </li> <li id="GUID-245B7926-AA87-5B13-B46E-C8DF4DBB162C"><p> <xref href="GUID-685AD682-10DC-553B-9C3A-04D0376138C4.dita">Adding a device to the PAN</xref>  </p> </li> <li id="GUID-D070BE04-D2BB-593C-BEE4-23E0E4637E10"><p> <xref href="GUID-197648C4-A42C-5769-82B7-F8BA510631D9.dita">Removing a device from the PAN</xref>  </p> </li> <li id="GUID-FCFBE512-1321-57F0-9F5B-D13784700CD5"><p> <xref href="GUID-50CDF6E0-C352-5771-8686-B551267C6BE6.dita">Closing the PAN</xref>  </p> </li> </ul> </section> </conbody></concept>