--------------------------------------------------------------------------------
S60 Platform: Bluetooth Point-to-Multipoint Example v2.2
--------------------------------------------------------------------------------

This C++ example application demonstrates the use of Bluetooth technology: device and service
discovery, connection establishment to one or more devices, communication between
devices, and disconnection. The Bluetooth RFCOMM protocol (RS-232 serial port
emulation) is used as the transport protocol.


BLUETOOTH BASICS
--------------------------------------------------------------------------------

The difference between a master and a slave needs to be distinguished first
in order to understand this example. A master is a device that establishes
the connections to remote devices, slaves. A slave cannot establish any
connections; it will act as a listener to incoming connections from the
master device. The master discovers slave devices and their services and
is capable of connecting to multiple slaves and holding these connections
active simultaneously. In essence, the point-to-multipoint connectivity
defined here is a single master device (point) connecting to multiple slave
devices (multiple points).

A number of Bluetooth APIs provide the following capabilities that are
demonstrated in this example. Device discovery inquires for Bluetooth
devices within range. Service discovery inquires the discovered Bluetooth
devices for the services they offer, filtering the service discovery query to
return only the service class required; in this way, the service discovery
query will only return the service entries that match the service class of our
service. Connection will then be established to all the remote Bluetooth
devices found to be offering the service we require. Once the connections
are established, messages can be sent from the master device to the
connected slaves, and vice versa, from a slave to its master device.

The slave mode initiates the application to act as a slave. In the slave
mode, the application listens to incoming connections and advertises its
available service. The master device will then be able to find the service
offered by the slave by performing device/service discovery and connection
establishment to the slaves listening channel/port.

Master is the inquiring device and the Slave is a scanning device.

There are many Bluetooth protocols over which the connection can be accomplished.
RFCOMM is used in this example but also OBEX and L2CAP, among others, are suitable
for third-party applications.

Limited Device Status can be enabled on S60 3rd Edition or higher. 
This feature is referred to as LIAC in this example application. 

In the Bluetooth Specification there are two different inquiry access codes for 
different use cases. The default case is that the inquiring device finds all the 
devices that are discoverable in the neighbourhood. In this case the searching 
device is inquiring with the Generic Inquiry Access Code (GIAC). However, this
can take a considerably long time to complete. Therefore, developers can also 
set the scanning devices into Limited-Discoverable mode. When making a device
inquiry with Limited Inquiry Access Code (LIAC), they can find these devices
because the other normal discoverable devices are filtered out, and they only
find the devices that are in the limited-discoverable mode.

LIAC is useful in cases where an application is running on two or more devices
and connection is desired to these devices only.
Devices scanning with LIAC can be found by devices inquiring with LIAC or GIAC
(LIAC inquiries are prioritised).
Devices inquiring with LIAC can only find devices scanning with LIAC.
For an application to fully take advantage of the faster LIAC inquiry, it is
crucial that the device performing the device inquiry is also set to LIAC mode.


PREREQUISITES
--------------------------------------------------------------------------------

Symbian C++ basics
Understanding the Bluetooth technology basics


IMPORTANT FILES/CLASSES
--------------------------------------------------------------------------------

CBluetoothPMPExampleEngine:
    Acts as an engine and handles the connections.
CDeviceDiscoverer:
    Is used in device discovery.
CServiceDiscoverer:
    Is used in service discovery.
CConnector:
    Wraps a socket connection. CListener sets up a listening channel.

Main Symbian classes used:
RSocketServ:
  Socket Server
RHostResolver:
  Provides an interface to host name resolution services, such as DNS,
    that may be provided by particular protocol modules.
CSdpAgent:
  Service discovery agent.
SdpSearchPattern:
  Service discovery search pattern.
RSdp:
  Service discovery protocol session.


REQUIRED CAPABILITIES
--------------------------------------------------------------------------------
If LIAC is enabled (ENABLE_LIAC):
Open Signed Offline: LocalServices UserEnvironment ReadUserData WriteUserData 
NetworkServices NetworkControl WriteDeviceData

Without LIAC:
User Grantable: LocalServices UserEnvironment ReadUserData WriteUserData 
NetworkServices


KNOWN ISSUES
--------------------------------------------------------------------------------

The application is intended to be used on real devices, not on the emulator.
However, with an S60bt driver it can also be used on the emulator.

Problems may occur if many Bluetooth devices are in range. It will at least
take a lot longer for device and service discovery to complete. Thus it is recommended 
to use Limited Inquiry (LIAC).


RUNNING THE EXAMPLE
--------------------------------------------------------------------------------

Launch the application on your device. A canvas displaying the application
name will appear; the application is ready for use. The Options menu
provides the following functionality:

Common operations:
------------------
    Turn Limited Discoverable Status On/Off. It can make device discovery faster if
    both ends use this method. LIAC default value is set to On.


Slave operations:
-----------------
Start slave:
    Select this command to set the desired device(s) to listen for the incoming
    connection. The application begins to advertise its available service.

    Once the master has connected to the slaves, the slaves will display a
    notification that they have been connected.

    Connected slaves are able to send and receive messages.


Master operations:
------------------
Discover devices:
    Discover the Bluetooth devices within range. Once the device discovery
    completes, the discovered devices will be displayed.

Discover services:
    Perform service discovery on the discovered devices. Once the service
    discovery completes, the application will display the devices that advertise
    and offer the service we require.

Connect devices:
    Connect to the listening channel/port of the devices that offer the required
    service. Once the connections are established, the names of the connected
    devices are displayed.

    Note that when the application is already connected to remote device(s), the
    menu option "Connect Devices" actually disconnects the current connections
    before creating new connections.

Show connected:
    Displays the connected devices.


Common operations for slave and master:
---------------------------------------

Send message:
    Prompts the user to enter a message and send it to the connected device.
    When sent from the master device, the message will be sent to all connected
    slaves. When sent from any of the slave devices, the message will first
    be sent to the master which then echoes it to the other slaves (note that there
    is no direct connection between the slaves and the echo functionality has to be
    implemented into the application logic).

Clear screen:
    Clears the log information on the screen.

LIAC on/off: Limited Discovery Status can be enabled. Note that only LIAC-enabled devices
    can be discovered if LIAC is enabled.

When the application is running, the log shows the current situation. It shows what
devices are found, which of them have the specified service, and what messages are
sent between devices. The log is written to the top of the screen.


BUILD & INSTALLATION INSTRUCTIONS
--------------------------------------------------------------------------------

Mobile device: S60 3rd Edition and later
----------------------------------------

go to \group
Check that the correct MMP (BluetoothPMPExample_3rd.mmp) is selected in the bld.inf file.

Uncomment two ENABLE_LIAC flags in BluetoothPMPExample_3rd.mmp if you want to use LIAC
functionality.

run bldmake bldfiles
run abld build gcce urel
go to \sis
run makesis -d%EPOCROOT% BluetoothPMP_S60.pkg

Sign the SIS package file, either by self-signing (LIAC disabled) it or using 
Open Signed Offline certificate (LIAC enabled).
For further information on self-signing, see the "How to sign .sis" document in the SDK.
run signsis BluetoothPMP_S60.sis

Install the created and signed SIS file to your device.


Emulator (WINSCW)
-----------------
    go to \group
    bldmake bldfiles
    abld build winscw udeb

    Start the emulator.


COMPATIBILITY
--------------------------------------------------------------------------------

S60 5th Edition
S60 3rd Edition, Feature Pack 2
S60 3rd Edition, Feature Pack 1
S60 3rd Edition

Tested with Nokia 5800, Nokia E90 Communicator, Nokia N95, Nokia N97.

Created and tested with 
S60 3rd Edition, MR SDK
S60 5th Edition SDK v0.9


VERSION HISTORY
--------------------------------------------------------------------------------
2.2   Scrollbars enabled. S60 5th Edition support checked. 
      S60 2nd Edition support removed.

2.1.2 LIAC is disabled on application shutdown.
      Disconnect functionality for Slave mode. Closes connection to the Master 
      device.
      Disconnect devices functionality for Master mode. Closes connections
      to the all slave devices.
      Menu item states fixed.
      Slave notices if master disconnect it.
      Master notices if slave disconnect connection.
      Master and slave notices if bluetooth  goes "out of range".

2.1.1 LIAC implementaion fixed and tested now with E90,N95.
      Added more stack size because CAknTextQueryDialog dialog seems to need it.
      icons_aif.mk paths fixed.
      Added WriteDeviceData capability because RProperty::Define need it when
      defining LIAC functionality.

2.1 Ported to S60 3rd Edition Feature Pack 1.
    -Added support of Limited Discovery Status on S60 3rd Edition.
    - Due to Symbian platform security, the following user-granted capabilities
      are needed:
      LocalServices, UserEnvironment, ReadUserData, WriteUserData, NetworkServices and 
      NetworkControl if Limited Discovery Status is enabled (compile time from mmp file ).

2.0 Ported from S60 2nd to S60 3rd Edition. Because of changes in the Symbian Bluetooth
    architecture in Symbian OS v8.0a and major changes in Symbian OS v9.1,
    three different buiLIAC of the example are needed:
    Bluetooth_PMP_1st:
    - Supports S60 1st Edition, S60 2nd Edition, and S60 2nd Edition, Feature Pack 1.

    Bluetooth_PMP_2ndFP2:
    - Supports S60 2nd Edition, Feature Packs 2 and 3.

    Bluetooth_PMP_3rd:
    - Supports S60 3rd Edition and later releases.


1.0 First release. Supports S60 1st Edition, S60 2nd Edition, and S60 2nd Edition, Feature Pack 1.


RELATED DOCUMENTATION
--------------------------------------------------------------------------------

S60 Platform: Bluetooth API Developer's Guide, published at www.forum.nokia.com
S60 Platform: Bluetooth OBEX Example, published at www.forum.nokia.com





