diff -r ebc84c812384 -r 46218c8b8afa Symbian3/PDK/Source/GUID-91C4F00B-E241-57DC-8520-8C16A302C983.dita --- a/Symbian3/PDK/Source/GUID-91C4F00B-E241-57DC-8520-8C16A302C983.dita Thu Mar 11 15:24:26 2010 +0000 +++ b/Symbian3/PDK/Source/GUID-91C4F00B-E241-57DC-8520-8C16A302C983.dita Thu Mar 11 18:02:22 2010 +0000 @@ -1,79 +1,79 @@ - - - - - -Creating a Personal Area Network (PAN)

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.

Using the Tutorial

The code fragments in this tutorial are derived from the Bluetooth Example application available in /src/COMMON/DEVELOPERLIBRARY/examples/Bluetooth/BTExample1. 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.

Intended Audience:

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.

Basic procedure:

The high level steps to create a PAN are:

Configuring CommDB PAN IAP

The PAN IAP (PANServiceExtensions 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.

To configure CommDB tables for PAN do the following:

  1. Open CommDB.

    CCommsDatabase* db = CCommsDatabase::NewL(); -CleanupStack::PushL(db);

  2. Open a view on the PANServiceExtensionsTable1 table.

    CCommsDbTableView* tableView = -db->OpenTableLC(TPtrC(PAN_SERVICE_EXTENSIONS)); -TBuf<KMaxBufferSize> tableName; -tableView->GotoFirstRecord(); -tableView->ReadTextL(TPtrC(COMMDB_NAME), tableName);

    Check that we are looking at the correct table.

    if(tableName == TPtrC(_S("PANServiceExtensionsTable1")))

    The above simply ensures that the table name is what was expected.

  3. Open the table for editing.

    User::LeaveIfError(tableView->UpdateRecord());

  4. Set the device to listen for incoming PAN connection requests if necessary.

    tableView->WriteBoolL(TPtrC(PAN_ALLOW_INCOMING),aIsListening);

    The value of aIsListening is ETrue for D1, the listening device.

  5. Decide if the device will prompt for remote devices.

    tableView->WriteBoolL(TPtrC(PAN_PROMPT_FOR_REMOTE_DEVICES),aUsePANNotifier);

    The value of aUsePANNotifier is EFalse 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.

  6. Set the PeerMacAddress to the Bluetooth device address of the device joining the PAN if known or to NULL if not known.

    D2 will prompt for a Bluetooth device address (aDevAddr) when making the connection. So if aDevAddr 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.

    if(aDevAddr) -{ - TBuf<KMaxBufferSize> buf; - aDevAddr->GetReadable(buf); - tableView->WriteTextL(TPtrC(PAN_PEER_MAC_ADDRESSES), buf); -}

    D1 is the listener and so will not need a Bluetooth device address when creating the listening connection.

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

  7. Commit the CommDB PANServiceExtensionsTable changes.

    User::LeaveIfError(tableView->PutRecordChanges());// Finish update -User::LeaveIfError(db->CommitTransaction()); -}

The code above comes from CPanConnections::ConfigureIAPL() in "exampleroot/src/panconnection.cpp ".

ConfigureIAPL(TBool aIsListening,TBTDevAddr* aDevAddr,TBool aUsePANNotifier) -{

The function is called when a connection is started. This function is called with three values: aIsListening, aDevAddr, and aUsePANNotifier.

Attribute Value

aIsListening

when called from CPanConnections::StartConnection():

  • ETrue if the device is listening for an incoming connection.

  • EFalse if the device is not listening for an incoming connection.

aDevAddr

The Bluetooth device address.

aUsePANNotifier

when called from CActiveConsole::ProcessKeyPressL():

  • ETrue if the PAN notifier is needed.

  • EFalse if the PAN notifier is not needed.

Finding the Bluetooth Device Address

The following code shows how to get and manipulate the Bluetooth device address:

... -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->StartConnection(&devAddr, EFalse, EFalse);

Note: this fragment taken from CActiveConsole::ProcessKeyPressL() in "exampleroot/src/console.cpp ".

Loading the Bluetooth Stack

The Bluetooth stack will need to be loaded before a PAN is created.

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); -}

The code above shows how to load the Bluetooth Stack using standard sockets.

Starting the PAN Connection

Now that you have loaded the Bluetooth stack and configured the PAN service extensions table a PAN connection can be opened.

  1. Define the connection preferences.

    // EGeneralIAP = 1 -PanProfileIAPs iap(EGeneralIAP); // panconnection.h -connPref.SetIapId(iap); -iConnPref.SetDialogPreference(ECommDbDialogPrefDoNotPrompt); -TInt rerr = iSockSvr.Connect(); -if(rerr == KErrNone) -{

  2. Load the Bluetooth stack.

    Initialise();

    Covered in the previous section.

  3. Open the connection

    rerr = iConnection.Open(iSockSvr);

  4. Start the session if the connection opened correctly:

    if(rerr == KErrNone) -{ - iConnection.Start(iConnPref,iStat); - User::WaitForRequest(iStat); -} -if(iStat==KErrNone) + + + + + +Creating a Personal Area Network (PAN)

    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.

    Using the Tutorial

    The code fragments in this tutorial are derived from the Bluetooth Example application available in /src/COMMON/DEVELOPERLIBRARY/examples/Bluetooth/BTExample1. 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.

    Intended Audience:

    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.

    Basic procedure:

    The high level steps to create a PAN are:

    • Configure the Pan services extension table and the LAN services table in CommDB.

    • Load the Bluetooth Stack

    • Start the PAN connection

    Configuring CommDB PAN IAP

    The PAN IAP (PANServiceExtensions 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.

    To configure CommDB tables for PAN do the following:

    1. Open CommDB.

      CCommsDatabase* db = CCommsDatabase::NewL(); +CleanupStack::PushL(db);

    2. Open a view on the PANServiceExtensionsTable1 table.

      CCommsDbTableView* tableView = +db->OpenTableLC(TPtrC(PAN_SERVICE_EXTENSIONS)); +TBuf<KMaxBufferSize> tableName; +tableView->GotoFirstRecord(); +tableView->ReadTextL(TPtrC(COMMDB_NAME), tableName);

      Check that we are looking at the correct table.

      if(tableName == TPtrC(_S("PANServiceExtensionsTable1")))

      The above simply ensures that the table name is what was expected.

    3. Open the table for editing.

      User::LeaveIfError(tableView->UpdateRecord());

    4. Set the device to listen for incoming PAN connection requests if necessary.

      tableView->WriteBoolL(TPtrC(PAN_ALLOW_INCOMING),aIsListening);

      The value of aIsListening is ETrue for D1, the listening device.

    5. Decide if the device will prompt for remote devices.

      tableView->WriteBoolL(TPtrC(PAN_PROMPT_FOR_REMOTE_DEVICES),aUsePANNotifier);

      The value of aUsePANNotifier is EFalse 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.

    6. Set the PeerMacAddress to the Bluetooth device address of the device joining the PAN if known or to NULL if not known.

      D2 will prompt for a Bluetooth device address (aDevAddr) when making the connection. So if aDevAddr 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.

      if(aDevAddr) +{ + TBuf<KMaxBufferSize> buf; + aDevAddr->GetReadable(buf); + tableView->WriteTextL(TPtrC(PAN_PEER_MAC_ADDRESSES), buf); +}

      D1 is the listener and so will not need a Bluetooth device address when creating the listening connection.

      else +{ + tableView->WriteTextL(TPtrC(PAN_PEER_MAC_ADDRESSES), _L("")); +}

    7. Commit the CommDB PANServiceExtensionsTable changes.

      User::LeaveIfError(tableView->PutRecordChanges());// Finish update +User::LeaveIfError(db->CommitTransaction()); +}

    The code above comes from CPanConnections::ConfigureIAPL() in "exampleroot/src/panconnection.cpp ".

    ConfigureIAPL(TBool aIsListening,TBTDevAddr* aDevAddr,TBool aUsePANNotifier) +{

    The function is called when a connection is started. This function is called with three values: aIsListening, aDevAddr, and aUsePANNotifier.

    Attribute Value

    aIsListening

    when called from CPanConnections::StartConnection():

    • ETrue if the device is listening for an incoming connection.

    • EFalse if the device is not listening for an incoming connection.

    aDevAddr

    The Bluetooth device address.

    aUsePANNotifier

    when called from CActiveConsole::ProcessKeyPressL():

    • ETrue if the PAN notifier is needed.

    • EFalse if the PAN notifier is not needed.

    Finding the Bluetooth Device Address

    The following code shows how to get and manipulate the Bluetooth device address:

    ... +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->StartConnection(&devAddr, EFalse, EFalse);

    Note: this fragment taken from CActiveConsole::ProcessKeyPressL() in "exampleroot/src/console.cpp ".

    Loading the Bluetooth Stack

    The Bluetooth stack will need to be loaded before a PAN is created.

    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); +}

    The code above shows how to load the Bluetooth Stack using standard sockets.

    Starting the PAN Connection

    Now that you have loaded the Bluetooth stack and configured the PAN service extensions table a PAN connection can be opened.

    1. Define the connection preferences.

      // EGeneralIAP = 1 +PanProfileIAPs iap(EGeneralIAP); // panconnection.h +connPref.SetIapId(iap); +iConnPref.SetDialogPreference(ECommDbDialogPrefDoNotPrompt); +TInt rerr = iSockSvr.Connect(); +if(rerr == KErrNone) +{

    2. Load the Bluetooth stack.

      Initialise();

      Covered in the previous section.

    3. Open the connection

      rerr = iConnection.Open(iSockSvr);

    4. Start the session if the connection opened correctly:

      if(rerr == KErrNone) +{ + iConnection.Start(iConnPref,iStat); + User::WaitForRequest(iStat); +} +if(iStat==KErrNone) {

    The code above is derived from CPanConnections::StartIAP() in "exampleroot/src/panconnection.cpp ".

    That's all there is to creating a PAN.

    What's next?

    Having created a PAN you will need to add and remove devices and close the PAN. The following will help:

    • Creating a Personal Area Network (PAN) - This document

    • Adding a device to the PAN

    • Removing a device from the PAN

    • Closing the PAN

    \ No newline at end of file