about_bluetoothpmp_example.txt

source codes for point to multi-point Bluetooth transaction in Symbian OS. A good beginning to learn

/*
 * ============================================================================
 *  Name     : about_bluetoothpmp_example.txt
 *  Part of  : BluetoothPMPExample
 *  Created  : 14.01.2004 by Forum Nokia
 *  Description:
 *		Definition of Series 60 Developer Platform 1.0/2.0: 
 * 		Bluetooth Point-to-Multipoint Example.
 *  Version  : 1.0
 *  Copyright: Nokia Corporation
 * ============================================================================
 */
 

   0. Overview of the operating principle of this example application
   
   The Bluetooth point-to-multipoint (PMP) example is an advanced level 
   application demonstrating the use of Bluetooth technology for establishing 
   point-to-multipoint connections and communication over those connections.

   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 demonstrated
   in this example. Device discovery inquires for Bluetooth devices within
   range. Service discovery inquires the discovered bBluetooth 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 doing device/service discovery and connection
   to the slave抯 listening channel/port.
   
   When the application is started, it displays the application name on the
   screen. The functionality of the program is operated via the menu. The 
   following options are available: device discovery, service discovery, 
   connecting to devices, displaying connected devices, sending message, and 
   starting the slave mode.
   
   In this text file, the <bluetooth pmp example dir> is used to REFERENCE
   to the directory in which the example files (including this .txt file)
   have been EXTRACTED.
   
   
   1. Compatibility

   Bluetooth PMP example application is compatible with Series 60 Developer 
   Platform 1.0 and 2.0. It has been tested to work with the Nokia 3650, 
   Nokia 3660, and Nokia 6600 phone models.
   
   This example was developed using Nokia Series 60 SDK v1.2.
      

   2. Building
   
   To build the application, complete the following steps:
   
   	2a) go to: "group"

   	2b) run: "bldmake bldfiles"

	2c) run: "abld makefile thumb"

	2d) run: "abld built thumb urel"
   
   	   	
   3. Installation to a device (pkg file notes & instructions)

	3.1 installing the ready-to-use BTex.SIS file: 
	
	3.1 a) deliver (move) the BTex.SIS file into 
	       any Series 60 Developer Platform 1.0 or 2.0 compatible phone
	
	3.2 building the application from the compiled files:
	
   	3.2a) go to "install"
   	
   	3.2b) run: "makesis BTex.pkg"
   	
   	3.2c) deliver (move) the created SIS file into 
   	your phone.
   	
   	
   4. Running the example

   Launch the BluetoothPMP application on your phone. A canvas displaying the 
   application name will appear; the application is ready for use.

   The operations of the application are controlled using the options found in 
   the menu. The "start slave" option starts the application in slave mode. 
   "discover devices" inquires for Bluetooth devices within range. 
   "discover services" inquires the discovered devices for their services. 
   "connect devices" connects to the discovered devices	that offer a service 
   required. "show connected" displays the connected devices. "send message" 
   prompts the user to enter a message and send the message to the connected 
   device.  

   To run and test the example, you can have one or more devices that will
   be set to act as slaves in the application and one device that will be the
   master. The following steps outline a possible test scenario:

	4.1) Slave devices:

		4.1.1) Start the slave mode by selecting the "start slave" menu 
		option on the slave devices. The application will indicate 
		to the user that the slave mode was started and that it is 
		listening for connections. The application begins to advertise 
		its service that is available for use.

		4.1.2) The slave will await for connection requests. Once the
		master has connected to the slave, the slave will display 
		a notification that it has been connected to.  

		4.1.3) The slave is now listening for incoming messages from 
		the master. Once a message from the master is received,
		it will be displayed.

		4.1.4) The slave can also send messages to the master when
		it is connected. Select the "send message" option to send the
		message to the master. The application will prompt the user to
		enter the message text to be sent. The message	will be sent
		to the master. The master will display the received message.

	4.2) Master device:

		4.2.1) Discover the Bluetooth devices within range by selecting
		the "discover devices" menu option.

		4.2.2) Once the device discovery completes, the discovered devices
		will be displayed. Now select "discover services" to do 
		service discovery on the discovered devices.  

		4.2.3) Once the service discovery completes, the application
		will display the devices that advertise and offer the service
		we require. Now select "connect devices" to connect to 
		the devices that offer the service.

		4.2.4) Once the connections are established, the names of 
		the devices that are connected to will be displayed.

		4.2.5) Now the "send message" option can be selected to send a
		message to the connected slaves. The application will prompt
		the user to enter the message text to be sent. The message
		will be sent to all the connected slaves. The slaves will
		display the received messages.