Cradle detection

You can detect when a BlackBerry® device is connected to a cradle (such as a car kit cradle) by using the DeviceCapability.TYPE_CRADLE capability type that is part of the Device Capability API.

You can use DeviceCapability.isSupported() and DeviceCapability.isAvailable() to detect the cradle status. Devices that are running BlackBerry® Device Software 6.0 return true for isSupported(DeviceCapability.TYPE_CRADLE). When a device that is running BlackBerry Device Software 6.0 is connected to a cradle, isAvailable(DeviceCapability.TYPE_CRADLE) returns true.

When you detect a cradle connection, you can use the CradleProtocol class to detect the cradle type and properties. CradleProtocol is provided in the net.rim.device.api.accessory package. The class provides fields for a cradle's type (such as a car kit cradle, a holster, or a charging pod) and a cradle's properties (such as whether a cradle has a light or buttons that can be changed programmatically).

CradleProtocol.getCradleType() returns the cradle type that the cradle itself provides. A cradle might not provide its precise type. For example, a car kit cradle might return CradleProtocol.TYPE_SIMPLE, instead of CradleProtocol.TYPE_CAR_KIT.

Code sample: Detecting if a device is connected to a cradle

The following code sample tests whether the device is connected to a cradle. If it is, the type of cradle is displayed.

import net.rim.device.api.accessory.CradleProtocol;
import net.rim.device.api.system.capability.DeviceCapability;
import net.rim.device.api.ui.component.RichTextField;
import net.rim.device.api.ui.container.MainScreen;

class CradleDemoScreen extends MainScreen 
{
    public CradleDemoScreen()
    {   
        setTitle("Cradle Demo");
        RichTextField statusField = new RichTextField();
        add(statusField);
        
        boolean isConnected = 
            DeviceCapability.isAvailable(DeviceCapability.TYPE_CRADLE);
        
        if (isConnected)
        {
            CradleProtocol myCradle = CradleProtocol.getInstance();
            int cradleType = myCradle.getCradleType();
            
            switch (cradleType)
            {
                case CradleProtocol.TYPE_CAR_KIT:
                    statusField.setText("Device is connected to a car kit cradle.");
                    break;
                case CradleProtocol.TYPE_AUDIO:
                    statusField.setText("Device is connected to an audio cradle.");
                    break;
                case CradleProtocol.TYPE_BEDSIDE:
                    statusField.setText("Device is connected to a charging pod cradle.");
                    break;
                case CradleProtocol.TYPE_CHARGER:
                    statusField.setText("Device is connected to a charger cradle.");
                    break;
                case CradleProtocol.TYPE_DESKTOP:
                    statusField.setText("Device is connected to a desktop cradle.");
                    break;
                case CradleProtocol.TYPE_HOLSTER:
                    statusField.setText("Device is connected to a holster cradle.");
                    break;
                case CradleProtocol.TYPE_MULTIMEDIA:
                    statusField.setText("Device is connected to a multimedia cradle.");
                    break;
                case CradleProtocol.TYPE_SIMPLE:
                    statusField.setText("Device is connected to a simple cradle.");
                    break;
                default:
                    statusField.setText("Can't determine type of cradle.");
            }
        }
        else
        {
            statusField.setText("Device is not connected.");
        }
    }            
}

Cradle handling

You can register your application as a cradle handler. A cradle handler is an application that can start when a BlackBerry® device is connected to a cradle of a specified type. For example, if your application provides local travel information, you might want to register it as a handler for a car kit cradle, so that it can start automatically when the device is connected to a car kit cradle.

To register your application as a cradle handler, use CradleHandlerRegistry.registerHandler(). The CradleHandlerRegistry class is provided in the net.rim.blackberry.api.cradle package. When you register your application, you specify the type of cradle that you want to handle and your application descriptor. Cradle types are defined as fields in the CradleProtocol class that is provided in the net.rim.device.api.accessory package.

Registration as a cradle handler is persistent. You need to register your application only once after it is installed on the device.

If any handlers are registered for a cradle type, the user is presented with a dialog box when that type of cradle is connected.

This diagram shows an example dialog box.

The user can select which handler to use, if any, and the selected handler application is started. The user can also indicate that the selected handler application should start automatically the next time the cradle of the specified type is connected.

The user can change the cradle handler settings on the device by clicking Options > Third Party Applications on the Home screen.

Code sample: Registering a cradle handler

The following code sample registers the current application as a handler for car kit cradles.

CradleHandlerRegistry.registerHandler(
   CradleProtocol.TYPE_CAR_KIT, 
   ApplicationDescriptor.currentApplicationDescriptor());
Previous topic: Device Capability API

Was this information helpful? Send us your comments.