Android 2.3 APIs

In this document

Reference

For developers, the Android 2.3
(GINGERBREAD)platform is available as a
downloadable component for the Android SDK. The downloadable platform includes
an Android library and system image, as well as a set of emulator skins and
more. To get started developing or testing against Android 2.3,
use the Android SDK Manager to download the platform into your SDK.

API Overview

The sections below provide a technical overview of what's new for developers
in 2.3, including new features and changes in the framework
API since the previous version.

SIP-based VoIP

The platform now includes a SIP protocol stack and framework API that lets
developers build internet telephony applications. Using the API, applications can offer
voice calling features without having to manage sessions, transport-level
communication, or audio — these are handled
transparently by the platform's SIP API and services.

The SIP API is available in the android.net.sip
package. The key class is SipManager, which applications
use to set up and manage SIP profiles, then initiate audio calls and receive
audio calls. Once an audio call is established, applications can mute calls,
turn on speaker mode, send DTMF tones, and more. Applications can also use the
SipManager to create generic SIP connections.

The platform’s underlying SIP stack and services are available on devices at
the discretion of the manufacturer and associated carrier. For this reason,
applications should use the isApiSupported() method to check whether SIP support is available, before
exposing calling functionality to users.

To use the SIP API, applications must request permission from the user by
declaring <uses-permission
android:name="android.permission.INTERNET"> and <uses-permission
android:name="android.permission.USE_SIP"> in their manifest files.

Additionally, developers can request filtering on Google Play, such that
their applications are not discoverable to users whose devices do not include
the platform’s SIP stack and services. To request filtering, add <uses-feature
android:name="android.software.sip"
android:required="true"> and <uses-feature
android:name="android.software.sip.voip"> to the application manifest.

Near Field Communications (NFC)

Android 2.3 includes an NFC stack and framework API that lets developers
read NDEF tags that are discovered as a user touches an NFC-enabled device
to tag elements embedded in stickers, smart posters, and even other devices.

The platform provides the underlying NFC services that work with the device
hardware to discover tags when they come into range. On discovering a tag, the
platform notifies applications by broadcasting an Intent, appending the tag's
NDEF messages to the Intent as extras. Applications can create Intent filters to
recognize and handle targeted tags and messages. For example, after receiving a
tag by Intent, applications extract the NDEF messages, store them, alert the
user, or handle them in other ways.

The NFC API is available in the android.nfc package. The key classes are:

NdefMessage, which represents an NDEF data message,
the standard format in which "records" carrying data are transmitted between
devices and tags. Applications can receive these messages from ACTION_TAG_DISCOVERED Intents.

NdefRecord, delivered in an
NdefMessage, which describes the type of data being shared and
carries the data itself.

NFC communication relies on wireless technology in the device hardware, so
support for the platform's NFC features on specific devices is determined by
their manufacturers. To determine the NFC support on the current device,
applications can call isEnabled() to
query the NfcAdapter. The NFC API is always present,
however, regardless of underlying hardware support.

To use the NFC API, applications must request permission from the user by
declaring <uses-permission
android:name="android.permission.NFC"> in their manifest files.

Additionally, developers can request filtering on Google Play, such that
their applications are not discoverable to users whose devices do not support
NFC. To request filtering, add
<uses-feature android:name="android.hardware.nfc"
android:required="true"> to the application's manifest.

Gyroscope and other sensors

Android 2.3 adds platform and API support for several new sensor reading
types — gyroscope, rotation vector, linear acceleration, gravity, and barometer.
Developers can use the new sensor readings to create applications that respond
quickly and smoothly to precise changes in device position and motion. The
Sensor API reports gyroscope and other sensor changes to interested
applications, whether they are running on the application framework or in native
code.

Note that the specific set of hardware sensors available on any given device
varies at the discretion of the device manufacturer.

Developers can request filtering on Google Play, such that their
applications are not discoverable to users whose devices do not offer a
gyroscope sensor. To do so, add <uses-feature
android:name="android.hardware.sensor.gyroscope"
android:required="true"> to the application manifest.

Multiple cameras support

Applications can now make use of any cameras that are available on a device,
for either photo or video capture. The Camera lets
applications query for the number of cameras available and the unique
characteristics of each.

Download manager

The platform includes a new DownloadManager system service
that handles long-running HTTP downloads. Applications can request that a URI be
downloaded to a particular destination file. The DownloadManager
will conduct the download in the background, taking care of HTTP interactions
and retrying downloads after failures or across connectivity changes and system
reboots.

The DownloadManager.Request class lets an
application provide all the information necessary to request a new download,
such as request URI and download destination. A request URI is the only required
parameter. Note that the default download destination is a shared volume where
the system can delete your file if it needs to reclaim space for system use. For
persistent storage of a download, specify a download destination on external
storage (see setDestinationUri(Uri)).

The DownloadManager.Query class provides methods that let
an application query for and filter active downloads.

StrictMode

To help developers monitor and improve the performance of their applications,
the platform offers a new system facility called StrictMode.
When implemented in an application, StrictMode catches and notifies the
developer of accidental disk or network activity that could degrade application
performance, such as activity taking place on the application's main thread
(where UI operations are received and animations are also taking place).
Developers can evaluate the network and disk usages issues raised in StrictMode
and correct them if needed, keeping the main thread more responsive and
preventing ANR dialogs from being shown to users.

StrictMode is the core class and is the main integration
point with the system and VM. The class provides convenience methods for
managing the thread and VM policies that apply to the instance.

For more information about how to use StrictMode to optimize your
application, see the class documentation and sample code at android.os.StrictMode.

UI Framework

Support for overscroll

New support for overscroll in Views and Widgets. In Views, applications can
enable/disable overscroll for a given view, set the overscoll mode, control the
overscroll distance, and handle the results of overscrolling.

New overScrollMode, overScrollFooter, and
overScrollHeader attributes for <ListView> elements,
for controlling overscroll behavior.

Support for touch filtering

New support for touch filtering, which lets an application improve the
security of Views that provide access to sensitive functionality. For example,
touch filtering is appropriate to ensure the security of user actions such as
granting a permission request, making a purchase, or clicking on an
advertisement. For details, see the View class
documentation.

New filterTouchesWhenObscured attribute for view elements,
which declares whether to filter touches when the view's window is obscured by
another visible window. When set to "true", the view will not
receive touches whenever a toast, dialog or other window appears above the
view's window. Refer to View security
documentation for details.

To look at sample code for touch filtering, see
SecureView.java
in the ApiDemos sample application.

Improved event management

New base class for input events, InputEvent. The class
provides methods that let applications determine the meaning of the event, such
as by querying for the InputDevice from which the event orginated. The KeyEvent and MotionEvent are subclasses of
InputEvent.

New base class for input devices, InputDevice. The
class stores information about the capabilities of a particular input device and
provides methods that let applications determine how to interpret events from an
input device.

Improved motion events

The MotionEvent API is extended to include "pointer ID"
information, which lets applications to keep track of individual fingers as they
move up and down. The class adds a variety of methods that let an application
work efficiently with motion events.

The input system now has logic to generate motion events with the new
pointer ID information, synthesizing identifiers as new pointers are down. The
system tracks multiple pointer IDs separately during a motion event, and
ensures proper continuity of pointers by evaluating at the distance
between the last and next set of pointers.

Text selection controls

A new setComposingRegion method lets an application mark a
region of text as composing text, maintaining the current styling. A
getSelectedText method returns the selected text to the
application. The methods are available in BaseInputConnection, InputConnection, and InputConnectionWrapper.

New textSelectHandle, textSelectHandleLeft,
textSelectHandleRight, and textSelectHandleWindowStyle
attributes for <TextView>, for referencing drawables that will be
used to display text-selection anchors and the style for the containing
window.

Extra Large Screens

The platform now supports extra large screen sizes, such as those that might
be found on tablet devices. Developers can indicate that their applications are
designed to support extra large screen sizes by adding a <supports
screens ... android:xlargeScreens="true"> element to their manifest
files. Applications can use a new resource qualifier, xlarge, to
tag resources that are specific to extra large screens. For
details on how to support extra large and other screen sizes, see Supporting Multiple
Screens.

Graphics

Content Providers

New AlarmClock provider class for setting an alarm
or handling an alarm. The provider contains a ACTION_SET_ALARM Intent
action and extras that can be used to start an Activity to set a new alarm in an
alarm clock application. Applications that wish to receive the
SET_ALARM Intent should create an activity that requires the
the SET_ALARM permission. Applications that wish to create a new
alarm should use Context.startActivity(), so that the user has the option of choosing
which alarm clock application to use.

MediaStore supports a new Intent action, PLAY_FROM_SEARCH, that lets an application search for music media and
automatically play content from the result when possible. For example, an
application could fire this Intent as the result of a voice recognition command
to listen to music.

MediaStore also adds a new MEDIA_IGNORE_FILENAME flag that tells the media
scanner to ignore media in the containing directory and its subdirectories.
Developers can use this to avoid having graphics appear in the Gallery and
likewise prevent application sounds and music from showing up in the Music
app.

Location

The LocationManager now tracks application
requests that result in wake locks or wifi locks according to
WorkSource, a system-managed class that identifies the
application.

The LocationManager keeps track
of all clients requesting periodic updates, and tells its providers
about them as a WorkSource parameter, when setting their minimum
update times.
The network location provider uses WorkSource to track the
wake and wifi locks initiated by an application and adds it to the application's
battery usage reported in Manage Applications.

The LocationManager adds several new methods that
let an Activity register to receive periodic or one-time location updates based
on specified criteria (see below).

A new Criteria class lets an application specify a
set of criteria for selecting a location provider. For example, providers may be
ordered according to accuracy, power usage, ability to report altitude, speed,
and bearing, and monetary cost.

Storage

Android 2.3 adds a new StorageManager that
supports OBB (Opaque Binary Blob) files. Although platform support for OBB is
available in Android 2.3, development tools for creating and managing OBB files
will not be availble until early 2011.

The Android 2.3 platform adds official support for devices that do not
include SD cards (although it provides virtual SD Card partition, when no
physical SD card is available). A convenience method, isExternalStorageRemovable(), lets applications
determine whether a physical SD card is present.

Package Manager

New constants for declaring hardware and software features. See the list in
the New Feature Constants section, below.

Telephony

New getPsc() method returns
the primary scrambling code of the serving cell on a UMTS network.

Native access to Activity lifecycle, windows

Android 2.3 exposes a broad set of APIs to applications that use native
code. Framework classes of interest to such applications include:

NativeActivity is a new type of Activity class, whose
lifecycle callbacks are implemented directly in native code. A
NativeActivity and its underlying native code run in the system
just as do other Activities — specifically they run in the Android
application's system process and execute on the application's main UI thread,
and they receive the same lifecycle callbacks as do other Activities.

New manifest elements and attributes

New values for android:screenOrientation attribute of
<activity> element:

"reverseLandscape" — The Activity would like to have the
screen in landscape orientation, turned in the opposite direction from normal
landscape.

"reversePortrait" — The Activity would like to have the
screen in portrait orientation, turned in the opposite direction from normal
portrait.

"sensorLandscape" — The Activity would like to have the
screen in landscape orientation, but can use the sensor to change which
direction the screen is facing.

"sensorPortrait" — The Activity would like to have the
screen in portrait orientation, but can use the sensor to change which direction
the screen is facing.

"fullSensor" — Orientation is determined by a physical
orientation sensor: the display will rotate based on how the user moves the
device. This allows any of the 4 possible rotations, regardless of what the
device will normally do (for example some devices won't normally use 180 degree
rotation).

New Permissions

com.android.permission.SET_ALARM — Allows an application
to broadcast an Intent to set an alarm for the user. An Activity that handles
the SET_ALARM Intent action
should require this permission.

android.permission.USE_SIP — Allows an application to use
the SIP API to make or receive internet calls.

android.permission.NFC — Allows an application to use the
NFC API to read NFC tags.

New Feature Constants

The platform adds several new hardware features that developers can declare
in their application manifests as being required by their applications. This
lets developers control how their application is filtered, when published on
Google Play.

API differences report

API Level

The Android 2.3 platform delivers an updated version of
the framework API. The Android 2.3 API
is assigned an integer identifier —
9 — that is
stored in the system itself. This identifier, called the "API Level", allows the
system to correctly determine whether an application is compatible with
the system, prior to installing the application.

To use APIs introduced in Android 2.3 in your application,
you need compile the application against the Android library that is provided in
the Android 2.3 SDK platform. Depending on your needs, you might
also need to add an android:minSdkVersion="9"
attribute to the <uses-sdk> element in the application's
manifest. If your application is designed to run only on Android 2.3 and higher,
declaring the attribute prevents the application from being installed on earlier
versions of the platform.