API Level: 9
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.
For more information, read the SIP developer guide.
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:
NfcAdapter
, which represents the NFC hardware on the device.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 fromACTION_TAG_DISCOVERED
Intents.NdefRecord
, delivered in anNdefMessage
, 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.
To look at a sample application that uses the NFC API, see NFCDemo.
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.
For API details, see Sensor
.
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.
- New
Camera.CameraInfo
class stores a camera's positional characteristics (orientation, front-facing or back-facing). - New
getNumberOfCameras()
andgetCameraInfo()
methods in theCamera
class let applications query for the cameras available and open the camera that they need. - New
get()
method lets applications retrieve aCamcorderProfile
for a specific camera. - New
getJpegEncodingQualityParameter()
lets applications obtain the still-image capture quality level for a specific camera.
To look at sample code for accessing a front-facing camera, see CameraPreview.java in the ApiDemos sample application.
The Camera API also adds:
- New parameters for cameras, including focus distance, focus mode, and
preview fps maximum/minimum. New
getFocusDistances()
,getPreviewFpsRange()
, andgetSupportedPreviewFpsRange()
for getting camera parameters, as well assetPreviewFpsRange()
for setting preview framerate.
Mixable audio effects
The platform's media framework adds support for new per-track or global audio effects, including bass boost, headphone virtualization, equalization, and reverb.
- New
android.media.audiofx
package provides the API to access audio effects. - New
AudioEffect
is the base class for controlling audio effects provided by the Android audio framework. - New audio session ID that lets an application associate a set of audio
effects with an instance of
AudioTrack
orMediaPlayer
. - New
AudioTrack
class constructor that lets you create anAudioTrack
with a specific session ID. NewattachAuxEffect()
,getAudioSessionId()
, andsetAuxEffectSendLevel()
methods. - New
attachAuxEffect()
,getAudioSessionId()
,setAudioSessionId(int)
, andsetAuxEffectSendLevel()
methods and supporting types.
To look at sample code for audio effects, see AudioFxDemo.java in the ApiDemos sample application.
The media framework also adds:
- New support for altitude tag in EXIF metadata for JPEG files. New method
getAltitude()
method to retrieve the value of the EXIF altitude tag. - New
setOrientationHint()
method lets an application tellMediaRecorder
of the orientation during video capture.
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.
- Applications can obtain an instance of the
DownloadManager
class by callinggetSystemService(String)
and passingDOWNLOAD_SERVICE
. Applications that request downloads through this API should register a broadcast receiver forACTION_NOTIFICATION_CLICKED
, to appropriately handle when the user clicks on a running download in a notification or from the Downloads UI. - 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 (seesetDestinationUri(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.StrictMode.ThreadPolicy
andStrictMode.VmPolicy
hold the policies that you define and apply to thread and VM instances.
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.
- In Widgets, applications can control overscroll characteristics such as
animation, springback, and overscroll distance. For more information, see
android.view.View
andandroid.widget.OverScroller
. ViewConfiguration
also provides methodsgetScaledOverflingDistance()
andgetScaledOverscrollDistance()
.- New
overScrollMode
,overScrollFooter
, andoverScrollHeader
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. TheKeyEvent
andMotionEvent
are subclasses ofInputEvent
. - 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.
- New base class for input events,
- 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.
- The
- Text selection controls
- A new
setComposingRegion
method lets an application mark a region of text as composing text, maintaining the current styling. AgetSelectedText
method returns the selected text to the application. The methods are available inBaseInputConnection
,InputConnection
, andInputConnectionWrapper
. - New
textSelectHandle
,textSelectHandleLeft
,textSelectHandleRight
, andtextSelectHandleWindowStyle
attributes for<TextView>
, for referencing drawables that will be used to display text-selection anchors and the style for the containing window.
- A new
- Activity controls
ActivityInfo
adds new constants for managing Activity orientation:SCREEN_ORIENTATION_FULL_SENSOR
,SCREEN_ORIENTATION_REVERSE_LANDSCAPE
,SCREEN_ORIENTATION_REVERSE_PORTRAIT
,SCREEN_ORIENTATION_SENSOR_LANDSCAPE
, andSCREEN_ORIENTATION_SENSOR_PORTRAIT
.- New constant
IMPORTANCE_PERCEPTIBLE
for theimportance
field inActivityManager.RunningAppProcessInfo
. The value indicates that a specific process is running something that is considered to be actively perceptible to the user. An example would be an application performing background music playback. - The Activity.setPersistent(boolean) method to mark an Activity as persistent is now deprecated and the implementation is a no-op.
- Notification text and icon styles
- New
TextAppearance.StatusBar.EventContent
,TextAppearance.StatusBar.EventContent.Title
,TextAppearance.StatusBar.Icon
, andTextAppearance.StatusBar.Title
for managing notification style.
- New
- Adds remaining OpenGL ES 2.0 methods
glDrawElements()
andglVertexAttribPointer()
in theandroid.opengl.GLES20
class. - Adds support for
YV12
pixel format, a planar 4:2:0 YCrCb format. - New
AlarmClock
provider class for setting an alarm or handling an alarm. The provider contains aACTION_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 theSET_ALARM
Intent should create an activity that requires the the SET_ALARM permission. Applications that wish to create a new alarm should useContext.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 newMEDIA_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.- The
Settings
provider adds the new Activity actionsAPPLICATION_DETAILS_SETTINGS
andMANAGE_ALL_APPLICATIONS_SETTINGS
, which let an application show the details screen for a specific application or show the Manage Applications screen. - The
ContactsContract
provider adds theContactsContract.CommonDataKinds.SipAddress
data kind, for storing a contact's SIP (Internet telephony) address. - The
LocationManager
now tracks application requests that result in wake locks or wifi locks according toWorkSource
, 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 aWorkSource
parameter, when setting their minimum update times. The network location provider usesWorkSource
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. - 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. - New constants for declaring hardware and software features. See the list in the New Feature Constants section, below.
PackageInfo
adds newfirstInstallTime
andlastUpdateTime
fields that store the time of the package installation and last update.- New
getProviderInfo()
method for retrieving all of the information known about a particular content provider class. - The
TelephonyManager
adds the constantNETWORK_TYPE_EVDO_B
for specifying the CDMA EVDO Rev B network type. - New
getPsc()
method returns the primary scrambling code of the serving cell on a UMTS network. NativeActivity
is a new type of Activity class, whose lifecycle callbacks are implemented directly in native code. ANativeActivity
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
InputQueue
class and callback interface lets native code manage event queueing. - New
SurfaceHolder.Callback2
interface lets native code manage aSurfaceHolder
. - New
takeInputQueue
andtakeSurface()
methods inWindow
let native code manage events and surfaces. dalvik.system
removes several classes that were previously deprecated.- Dalvik core libraries:
- New collections:
ArrayDeque
,NavigableMap
,ConcurrentSkipListMap
,LinkedBlockingDeque
- New
Arrays
utilities:binarySearch()
,copyOf()
,copyOfRange()
, and others. CookieManager
forHttpURLConnection
.- More complete network APIs:
InterfaceAddress
,NetworkInterface
andIDN
File
read and write controlsString.isEmpty()
Normalizer
andNormalizer.Form
- Improved
javax.net.ssl
server sockets.
- New collections:
- New
xlargeScreens
attribute for<supports-screens>
element, to indicate whether the application supports extra large screen form-factors. For details, see Supporting Multiple Screens. - 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).
com.android.permission.SET_ALARM
— Allows an application to broadcast an Intent to set an alarm for the user. An Activity that handles theSET_ALARM
Intent action should require this permission.android.permission.USE_SIP
— Allows an application to use theSIP API
to make or receive internet calls.android.permission.NFC
— Allows an application to use theNFC API
to read NFC tags.android.hardware.audio.low_latency
— The application uses a low-latency audio pipeline on the device and is sensitive to delays or lag in sound input or output.android.hardware.camera.front
— The application uses a front-facing camera on the device.android.hardware.nfc
— The application uses NFC radio features in the device.android.hardware.sensor.barometer
— The application uses the device's barometer.android.hardware.sensor.gyroscope
— The application uses the device's gyroscope sensor.android.software.sip
— The application uses the SIP API on the device.android.software.sip.voip
— The application uses a SIP-based VoIP service on the device.android.hardware.touchscreen.multitouch.jazzhand
— The application uses advanced multipoint multitouch capabilities on the device screen, for tracking five or more points fully independently.
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
Location
Storage
Package Manager
Telephony
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:
For full information on working with native code or to download the NDK, see the Android NDK page.
Dalvik Runtime
New manifest elements and attributes
New Permissions
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.
For full information about how to declare features and use them for
filtering, see the documentation for <uses-feature>
.
API differences report
For a detailed view of all API changes in Android 2.3 (API Level 9), see the 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.
For more information, read What is API Level?