Using the Bluetooth Device Selection UI
The Device Selection UI does all the work of searching for available Bluetooth devices and presenting them to users. It is provided as a plug-in to the RNotifier class. The RNotifier class is a generic class that allows the use of several plug-in UI elements provided by the OS. It is defined in the E32STD.H header file. Its public interface is shown in the following code:
class RNotifier : public RSessionBase {
public :
IMPORT_C RNotifier(); IMPORT_C TInt Connect();
IMPORT_C TInt StartNotifier(TUid aNotifierUid,const TDesC8& aBuffer, TDes8& aResponse);
IMPORT_C TInt CancelNotifier(TUid aNotifierUid);
IMPORT_C TInt UpdateNotifier(TUid aNotifierUid,const TDesC8& aBuffer, TDes8& aResponse);
IMPORT_C void StartNotifierAndGetResponse(TRequestStatus& aRs,
TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse);
IMPORT_C TInt UnloadNotifiers(TUid aNotifierUid);
IMPORT_C TInt LoadNotifiers(TUid aNotifierUid);
IMPORT_C void Notify(const TDesC& aLine1,const TDesC& aLine2, const TDesC& aBut1,const TDesC& aBut2,TInt& aButtonVal, TRequestStatus& aStatus);
IMPORT C TInt InfoPrint(const TDesC& aDes);
The RNotifier class is designed to be used with most types of client application. The RNotifier provides access to a background thread that will throw the selection dialog on the screen. This implementation issue means that is not necessary for the client application to have a GUI interface; accordingly, this means that the Bluetooth Device Selection can be used in DLLs. The RNotifier's interface will be described in more detail later in this document.
Since the RNotifier class is a generic class, it is designed to be used with different types of dialogs. A unique ID represents each type of dialog. The Bluetooth Device
Selection dialog is represented by the KDeviceselectionNotifierUid constant value. It is defined in the btextnotifiers.h header file.
The Device Selection thread uses a set of classes to transfer data and settings to and from the client application. These are briefly explained in the following paragraphs.
The TBTDeviceselectionParams class allows a client application to pass initial parameters to the selection process.
class TBTDeviceselectionParams {
public:
IMPORT_C TBTDeviceselectionParams();
IMPORT_C void setUUID(const TUUID& aUUID);
IMPORT_C void setDeviceClass(TBTDeviceClass aClass);
IMPORT_C const TUUID& UUID();
IMPORT_C TBTDeviceClass DeviceClass();
IMPORT_C TBool IsValidDeviceClass();
IMPORT_C TBool IsValidUUID(); };
The client application can set the device class to search for. By setting this value with the setDeviceClass function, the client application can limit the number and type of devices that will respond to the search request, and thus those that are displayed to the user.
It is also possible for the client application to set the UUID of the service it requires. This again will constrain the resulting list of devices presented to the user. This can be done with the setUUiD function.
To search for all available devices, no matter what type of service they provide, a client application would leave the TBTDeviceselectionParams object unaltered with its default values.
After the user has selected a preferred device, the background thread will complete. The user's selection is presented to the client application via the
TBTDeviceResponseParams class. This class is defined in the btextnotifiers.h header file. Its public interface is shown in the following code:
class TBTDeviceResponseParams {
public:
IMPORT_C TBTDeviceResponseParams();
IMPORT_C void setDeviceAddress(const TBTDevAddr& aBDAddr); IMPORT_C void setDeviceName(const TDesC& aName); IMPORT_C void setDeviceClass(TBTDeviceClass aClass); IMPORT_C const TBTDevAddr& BDAddr() const; IMPORT_C const TDesC& DeviceName() const; IMPORT_C TBTDeviceClass DeviceClass(); IMPORT_C TBool IsValidBDAddr() const; IMPORT_C TBool IsValidDeviceName() const;
IMPORT_C TBool IsValidDeviceClass(); };
The isValidxxxx functions are used to ensure that the relevant information has been set in the class; for instance, if the isValidBDAddr function returns true, the client application can expect that the Bluetooth address of the selected device has been set in the TBTDeviceResponseParams object. If the IsValidBDAddr function returns false, then this data is not present. This will happen if an error has occurred.
The client application can obtain the Bluetooth device address of the selected device via the BDAddr function, and the device name via the DeviceName function.
As stated previously, the RNotifier class provides access to a background thread that actually performs all of the hard work of searching for devices and throwing the dialog. This is implemented as a server process. Package buffers are required to communicate data over the client/server boundary. The Symbian OS API provides a set of package buffers that wrap the data types defined before. The package buffers are as follows:
■ TBTDeviceSelectionParamsPckg
■ TBTDeviceSelectionParams
■ TBTDeviceResponseParamsPckg
■ TBTDeviceResponseParams
The Symbian OS Bluetooth Discovery example provided with the SDK implements the Bluetooth Device Selection Notifier. This example is in the Series 60 SDK installation directory at <installation directory>\7.0s\Series60\series60Ex\BTDiscovery.
The following code is taken from <installation directory>\7.0s\ Series60\series60Ex\BTDiscovery\src\btdiscoverer.cpp. Examine the CBTDiscoverer::SelectDeviceL function, which is a good example of how to implement the Bluetooth Device Selection UI.
TBool CBTDiscoverer::SelectDeviceL(TBTDeviceResponseParamsPckg&
aResponse) {
As noted previously, the RNotifier provides access to a server-side process. Before the RNotifier can be used, the client application must first connect to the server.
RNotifier not;
User::LeaveifError(not.Connect());
A TBTDeviceSelectionParamsPckg object is created; this object contains an instance of the TBTDeviceSelectionParams class. Note that this class is left initialized with the default values. A Bluetooth Device Selection dialog based on this selection parameter should give the user a list of all devices available within the local piconet.
TBTDeviceSelectionParamsPckg selectionFilter;
The RNotifier is designed to use an Active Object's TRequestStatus to send a notification when the user makes a selection.
TRequestStatus status;
The RNotifier is called to display the Bluetooth Device Selection dialog. At this point, the RNotifier executes the code to search for all available devices and presents this list to the user. The first parameter is the TRequestStatus; the second is the constant integer that represents the Bluetooth Device Selection Dialog; the third parameter is the Selection Filter; and the last parameter is the response parameter, TBTDeviceResponseParamsPckg, which is populated when the user makes a selection. This is an asynchronous call: the current thread is not paused and continues to the next statement.
not.StartNotifierAndGetResponse( status,
KDeviceSelectionNotifierUid, selectionFilter, aResponse
Here the client application calls the WaitForRequest utility function to pause the current thread pending completion of the TRequestStatus passed to the RNotifier object. This means that the current application will wait until the user has made a selection from the dialog.
User::WaitForRequest(status);
The TRequestStatus object is also used to return any error states encountered during the execution of the device selection code. The following if statement checks to ensure that the code is executed without a problem and that the user has made a selection:
if (aResponse().IsValidDeviceName()) {
iReporter.Error( L("Failed to connect")); } _
else
iReporter.Error( L("No device selected")); }
The client application has now finished with the RNotifier object and shuts it down. This is accomplished by telling the RNotifier to unload the Bluetooth Device Selection dialog code, and then to close its connection with the server. If the RNotifier's server is not being used by any other application, it is unloaded from the system as well, thus freeing resources.
not.CancelNotifier(KDeviceSelectionNotifierUid);
The function completes:
return success; }
Further information on the Bluetooth Device Selection dialog is available in the help file supplied with the Series 60 SDK. It is in the SDK installation directory at <installation directory>\7.0s\Series60 \series60Doc\DevLib.chm.
Average user rating: 5 stars out of 1 votes
Post a comment