This API is designed to allow you to query or listen for changes in the status of various capabilities of a BlackBerry device, such as the whether it has a virtual keyboard or whether the display can rotate. It is also designed to be future proof, so you can use it to check for capabilities that do not exist in BlackBerry 6.0 by passing in the value of their constant.
There are several states a capability can be in:
Supported - A capability that is "Supported" is one that a device has the ability to do in general. Whether a device can rotate or not is dependant on the presence of the hardware acceleratorometor, and unlikely to change. The "Supported" state should be something that stayes the same in the long term.
Allowed - A capability that is "Allowed" is one that the device should let you use at the time. For example, on a device with a physical keyboard ready to use, the virtual keyboard would not be allowed. You could still use it (check if it's supported), but it's not recommended. This state is likely to change frequently, so you will definitely want to check it every time you want to use it.
Avaliable - A capability that is "Avaliable" is one that is ready to use at the moment. If the virtual keyboard is currently displayed, it would be avaliable. This can change very frequently, so it should be checked every time you need it.
To find out what state a capability is in, you can either use the isSupported, isAllowedand isAvaliable methods to query the current status, or register a DeviceCapabilityListener to be notifed when a certain capability changes.
This API is designed to be forward compatible. All of the base methods take a long parameter to specify the capability they are referring to. For example: