From f128275bdc229fd3c35ce25cf9518b72bc6c7790 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Thu, 18 Jul 2013 15:09:03 -0700 Subject: more details about account access in restricted profiles Change-Id: I2710c3e8736748ca3080ee88f076255a6639b1e3 --- docs/html/about/versions/android-4.3.jd | 680 ++++++++++++++++---------------- 1 file changed, 342 insertions(+), 338 deletions(-) diff --git a/docs/html/about/versions/android-4.3.jd b/docs/html/about/versions/android-4.3.jd index 0ca3bc6..135c0d2 100644 --- a/docs/html/about/versions/android-4.3.jd +++ b/docs/html/about/versions/android-4.3.jd @@ -7,7 +7,7 @@ sdk.platform.apiLevel=18
- +

In this document show more @@ -133,7 +133,7 @@ image to test your app on the An Then build your apps against the Android {@sdkPlatformVersion} platform to begin using the latest APIs.

- +

Update your target API level

To better optimize your app for devices running Android {@sdkPlatformVersion}, @@ -145,7 +145,7 @@ test it, then publish an update with this change.

You can use APIs in Android {@sdkPlatformVersion} while also supporting older versions by adding conditions to your code that check for the system API level before executing APIs not supported by your {@code minSdkVersion}. +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}. To learn more about maintaining backward compatibility, read Supporting Different Platform Versions.

@@ -172,11 +172,11 @@ be affected by changes in Android {@sdkPlatformVersion}.

Your app might misbehave in a restricted profile environment.

-

Users in a restricted profile environment might not -have all the standard Android apps available. For example, a restricted profile might have the -web browser and camera app disabled. So your app should not make assumptions about which apps are -available, because if you call {@link android.app.Activity#startActivity startActivity()} without -verifying whether an app is available to handle the {@link android.content.Intent}, +

Users in a restricted profile environment might not +have all the standard Android apps available. For example, a restricted profile might have the +web browser and camera app disabled. So your app should not make assumptions about which apps are +available, because if you call {@link android.app.Activity#startActivity startActivity()} without +verifying whether an app is available to handle the {@link android.content.Intent}, your app might crash in a restricted profile.

When using an implicit intent, you should always verify that an app is available to handle the intent by calling {@link android.content.Intent#resolveActivity resolveActivity()} or {@link android.content.pm.PackageManager#queryIntentActivities queryIntentActivities()}. For example:

@@ -197,20 +197,20 @@ if (intent.resolveActivity(getPackageManager()) != null) {

Your app might misbehave in a restricted profile environment.

Users within a restricted profile environment do not have access to user accounts by default. -If your app depends on an {@link android.accounts.Account}, then your app might crash or behave +If your app depends on an {@link android.accounts.Account}, then your app might crash or behave unexpectedly when used in a restricted profile.

If you'd like to prevent restricted profiles from using your app entirely because your -app depends on account information that's sensitive, specify the {@code -android:requiredAccountType} attribute in your manifest's {@code <application>} +app depends on account information that's sensitive, specify the {@code +android:requiredAccountType} attribute in your manifest's {@code <application>} element.

-

If you’d like to allow restricted profiles to continue using your app even though they can’t -create their own accounts, then you can either disable your app features that require an account +

If you’d like to allow restricted profiles to continue using your app even though they can’t +create their own accounts, then you can either disable your app features that require an account or allow restricted profiles to access the accounts created by the primary user. For more -information, see the section +information, see the section below about Supporting accounts in a restricted profile.

@@ -218,67 +218,67 @@ below about Supporting accounts in a restricted pro

Restricted Profiles

-

On Android tablets, users can now create restricted profiles based on the primary user. +

On Android tablets, users can now create restricted profiles based on the primary user. When users create a restricted profile, they can enable restrictions such as which apps are available to the profile. A new set of APIs in Android 4.3 also allow you to build fine-grain -restriction settings for the apps you develop. For example, by using the new APIs, you can -allow users to control what type of content is available within your app when running in a +restriction settings for the apps you develop. For example, by using the new APIs, you can +allow users to control what type of content is available within your app when running in a restricted profile environment.

-

The UI for users to control the restrictions you've built is managed by the system's +

The UI for users to control the restrictions you've built is managed by the system's Settings application. To make your app's restriction settings appear to the user, -you must declare the restrictions your app provides by creating a {@link -android.content.BroadcastReceiver} that receives the {@link android.content.Intent#ACTION_GET_RESTRICTION_ENTRIES} intent. The system invokes this intent to query -all apps for available restrictions, then builds the UI to allow the primary user to +you must declare the restrictions your app provides by creating a {@link +android.content.BroadcastReceiver} that receives the {@link android.content.Intent#ACTION_GET_RESTRICTION_ENTRIES} intent. The system invokes this intent to query +all apps for available restrictions, then builds the UI to allow the primary user to manage restrictions for each restricted profile.

-

In the {@link android.content.BroadcastReceiver#onReceive onReceive()} method of -your {@link android.content.BroadcastReceiver}, you must create a {@link -android.content.RestrictionEntry} for each restriction your app provides. Each {@link -android.content.RestrictionEntry} defines a restriction title, description, and one of the +

In the {@link android.content.BroadcastReceiver#onReceive onReceive()} method of +your {@link android.content.BroadcastReceiver}, you must create a {@link +android.content.RestrictionEntry} for each restriction your app provides. Each {@link +android.content.RestrictionEntry} defines a restriction title, description, and one of the following data types:

    -
  • {@link android.content.RestrictionEntry#TYPE_BOOLEAN} for a restriction that is +
  • {@link android.content.RestrictionEntry#TYPE_BOOLEAN} for a restriction that is either true or false. -
  • {@link android.content.RestrictionEntry#TYPE_CHOICE} for a restriction that has +
  • {@link android.content.RestrictionEntry#TYPE_CHOICE} for a restriction that has multiple choices that are mutually exclusive (radio button choices). -
  • {@link android.content.RestrictionEntry#TYPE_MULTI_SELECT} for a restriction that +
  • {@link android.content.RestrictionEntry#TYPE_MULTI_SELECT} for a restriction that has multiple choices that are not mutually exclusive (checkbox choices).
-

You then put all the {@link android.content.RestrictionEntry} objects into an {@link -java.util.ArrayList} and put it into the broadcast receiver's result as the value for the +

You then put all the {@link android.content.RestrictionEntry} objects into an {@link +java.util.ArrayList} and put it into the broadcast receiver's result as the value for the {@link android.content.Intent#EXTRA_RESTRICTIONS_LIST} extra.

-

The system creates the UI for your app's restrictions in the Settings app and saves each -restriction with the unique key you provided for each {@link android.content.RestrictionEntry} -object. When the user opens your app, you can query for any current restrictions by -calling {@link android.os.UserManager#getApplicationRestrictions getApplicationRestrictions()}. +

The system creates the UI for your app's restrictions in the Settings app and saves each +restriction with the unique key you provided for each {@link android.content.RestrictionEntry} +object. When the user opens your app, you can query for any current restrictions by +calling {@link android.os.UserManager#getApplicationRestrictions getApplicationRestrictions()}. This returns a {@link android.os.Bundle} containing the key-value pairs for each restriction you defined with the {@link android.content.RestrictionEntry} objects.

-

If you want to provide more specific restrictions that can't be handled by boolean, single -choice, and multi-choice values, then you can create an activity where the user can specify the -restrictions and allow users to open that activity from the restriction settings. In your -broadcast receiver, include the {@link android.content.Intent#EXTRA_RESTRICTIONS_INTENT} extra +

If you want to provide more specific restrictions that can't be handled by boolean, single +choice, and multi-choice values, then you can create an activity where the user can specify the +restrictions and allow users to open that activity from the restriction settings. In your +broadcast receiver, include the {@link android.content.Intent#EXTRA_RESTRICTIONS_INTENT} extra in the result {@link android.os.Bundle}. This extra must specify an {@link android.content.Intent} -indicating the {@link android.app.Activity} class to launch (use the -{@link android.os.Bundle#putParcelable putParcelable()} method to pass {@link +indicating the {@link android.app.Activity} class to launch (use the +{@link android.os.Bundle#putParcelable putParcelable()} method to pass {@link android.content.Intent#EXTRA_RESTRICTIONS_INTENT} with the intent). -When the primary user enters your activity to set custom restrictions, your -activity must then return a result containing the restriction values in an extra using either -the {@link android.content.Intent#EXTRA_RESTRICTIONS_LIST} or {@link +When the primary user enters your activity to set custom restrictions, your +activity must then return a result containing the restriction values in an extra using either +the {@link android.content.Intent#EXTRA_RESTRICTIONS_LIST} or {@link android.content.Intent#EXTRA_RESTRICTIONS_BUNDLE} key, depending on whether you specify {@link android.content.RestrictionEntry} objects or key-value pairs, respectively.

Supporting accounts in a restricted profile

-

Any accounts added to the primary user are available to a restricted profile, but the -accounts are not accessible from the {@link android.accounts.AccountManager} APIs by default. +

Any accounts added to the primary user are available to a restricted profile, but the +accounts are not accessible from the {@link android.accounts.AccountManager} APIs by default. If you attempt to add an account with {@link android.accounts.AccountManager} while in a restricted -profile, you will get a failure result. Due to these restrictions, you have the following +profile, you will get a failure result. Due to these restrictions, you have the following three options:

  • Allow access to the owner’s accounts from a restricted profile. @@ -289,21 +289,25 @@ href="{@docRoot}guide/topics/manifest/application-element.html"><application> android:restrictedAccountType="com.example.account.type" > -

    Caution: Enabling this attribute provides your -app access to the primary user's accounts from restricted profiles. So you should allow this +

    Caution: Enabling this attribute provides your +app access to the primary user's accounts from restricted profiles. So you should allow this only if the information displayed by your app does not reveal personally identifiable -information (PII) that’s considered sensitive.

    +information (PII) that’s considered sensitive. The system settings will inform the primary +user that your app grants restricted profiles to their accounts, so it should be clear to the user +that account access is important for your app's functionality. If possible, you should also +provide adequate restriction controls for the primary user that define how much account access +is allowed in your app.

  • Disable certain functionality when unable to modify accounts. -

    If you want to use accounts, but don’t actually require them for your app’s primary -functionality, you can check for account availability and disable features when not available. -You should first check if there is an existing account available. If not, then query whether -it’s possible to create a new account by calling {@link -android.os.UserManager#getUserRestrictions()} and check the {@link -android.os.UserManager#DISALLOW_MODIFY_ACCOUNTS} extra in the result. If it is {@code true}, -then you should disable whatever functionality of your app requires access to accounts. +

    If you want to use accounts, but don’t actually require them for your app’s primary +functionality, you can check for account availability and disable features when not available. +You should first check if there is an existing account available. If not, then query whether +it’s possible to create a new account by calling {@link +android.os.UserManager#getUserRestrictions()} and check the {@link +android.os.UserManager#DISALLOW_MODIFY_ACCOUNTS} extra in the result. If it is {@code true}, +then you should disable whatever functionality of your app requires access to accounts. For example:

     UserManager um = (UserManager) context.getSystemService(Context.USER_SERVICE);
@@ -312,15 +316,15 @@ if (restrictions.getBoolean(UserManager.DISALLOW_MODIFY_ACCOUNTS, false)) {
    // cannot add accounts, disable some functionality
 }
    -

    Note: In this scenario, you should not declare +

    Note: In this scenario, you should not declare any new attributes in your manifest file.

  • Disable your app when unable to access private accounts. -

    If it’s instead important that your app not be available to restricted profiles because -your app depends on sensitive personal information in an account (and because restricted profiles +

    If it’s instead important that your app not be available to restricted profiles because +your app depends on sensitive personal information in an account (and because restricted profiles currently cannot add new accounts), add -the {@code +the {@code android:requiredAccountType} attribute to the <application> tag:

    @@ -338,11 +342,11 @@ because the owner's personal email should not be available to restricted profile
 
 
    Bluetooth Low Energy (Smart Ready)
    
 
-
    Android now supports Bluetooth Low Energy (LE) with new APIs in {@link android.bluetooth}. 
-With the new APIs, you can build Android apps that communicate with Bluetooth Low Energy 
+
    Android now supports Bluetooth Low Energy (LE) with new APIs in {@link android.bluetooth}.
+With the new APIs, you can build Android apps that communicate with Bluetooth Low Energy
 peripherals such as heart rate monitors and pedometers.
    
 
-
    Because Bluetooth LE is a hardware feature that is not available on all 
+
    Because Bluetooth LE is a hardware feature that is not available on all
 Android-powered devices, you must declare in your manifest file a {@code <uses-feature>}
 element for {@code "android.hardware.bluetooth_le"}:
    
@@ -350,11 +354,11 @@ element for {@code "android.hardware.bluetooth_le"}:
    
 <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
    -

    If you're already familiar with Android's Classic Bluetooth APIs, notice that using the -Bluetooth LE APIs has some differences. Most importantly is that there's now a {@link -android.bluetooth.BluetoothManager} class that you should use for some high level operations -such as acquiring a {@link android.bluetooth.BluetoothAdapter}, getting a list of connected -devices, and checking the state of a device. For example, here's how you should now get the +

    If you're already familiar with Android's Classic Bluetooth APIs, notice that using the +Bluetooth LE APIs has some differences. Most importantly is that there's now a {@link +android.bluetooth.BluetoothManager} class that you should use for some high level operations +such as acquiring a {@link android.bluetooth.BluetoothAdapter}, getting a list of connected +devices, and checking the state of a device. For example, here's how you should now get the {@link android.bluetooth.BluetoothAdapter}:

     final BluetoothManager bluetoothManager =
@@ -362,32 +366,32 @@ final BluetoothManager bluetoothManager =
 mBluetoothAdapter = bluetoothManager.getAdapter();
    -

    To discover Bluetooth LE peripherals, call {@link android.bluetooth.BluetoothAdapter#startLeScan -startLeScan()} on the {@link android.bluetooth.BluetoothAdapter}, passing it an implementation -of the {@link android.bluetooth.BluetoothAdapter.LeScanCallback} interface. When the Bluetooth -adapter detects a Bluetooth LE peripheral, your {@link -android.bluetooth.BluetoothAdapter.LeScanCallback} implementation receives a call to the -{@link android.bluetooth.BluetoothAdapter.LeScanCallback#onLeScan onLeScan()} method. This -method provides you with a {@link android.bluetooth.BluetoothDevice} object representing the -detected device, the RSSI value for the device, and a byte array containing the device's +

    To discover Bluetooth LE peripherals, call {@link android.bluetooth.BluetoothAdapter#startLeScan +startLeScan()} on the {@link android.bluetooth.BluetoothAdapter}, passing it an implementation +of the {@link android.bluetooth.BluetoothAdapter.LeScanCallback} interface. When the Bluetooth +adapter detects a Bluetooth LE peripheral, your {@link +android.bluetooth.BluetoothAdapter.LeScanCallback} implementation receives a call to the +{@link android.bluetooth.BluetoothAdapter.LeScanCallback#onLeScan onLeScan()} method. This +method provides you with a {@link android.bluetooth.BluetoothDevice} object representing the +detected device, the RSSI value for the device, and a byte array containing the device's advertisement record.

    -

    If you want to scan for only specific types of peripherals, you can instead call {@link -android.bluetooth.BluetoothAdapter#startLeScan startLeScan()} and include an array of {@link +

    If you want to scan for only specific types of peripherals, you can instead call {@link +android.bluetooth.BluetoothAdapter#startLeScan startLeScan()} and include an array of {@link java.util.UUID} objects that specify the GATT services your app supports.

    -

    Note: You can only scan for Bluetooth LE devices or -scan for Classic Bluetooth devices using previous APIs. You cannot scan for both LE and Classic +

    Note: You can only scan for Bluetooth LE devices or +scan for Classic Bluetooth devices using previous APIs. You cannot scan for both LE and Classic Bluetooth devices at once.

    -

    To then connect to a Bluetooth LE peripheral, call {@link -android.bluetooth.BluetoothDevice#connectGatt connectGatt()} on the corresponding -{@link android.bluetooth.BluetoothDevice} object, passing it an implementation of -{@link android.bluetooth.BluetoothGattCallback}. Your implementation of {@link -android.bluetooth.BluetoothGattCallback} receives callbacks regarding the connectivity -state with the device and other events. It's during the {@link -android.bluetooth.BluetoothGattCallback#onConnectionStateChange onConnectionStateChange()} -callback that you can begin communicating with the device if the method passes {@link +

    To then connect to a Bluetooth LE peripheral, call {@link +android.bluetooth.BluetoothDevice#connectGatt connectGatt()} on the corresponding +{@link android.bluetooth.BluetoothDevice} object, passing it an implementation of +{@link android.bluetooth.BluetoothGattCallback}. Your implementation of {@link +android.bluetooth.BluetoothGattCallback} receives callbacks regarding the connectivity +state with the device and other events. It's during the {@link +android.bluetooth.BluetoothGattCallback#onConnectionStateChange onConnectionStateChange()} +callback that you can begin communicating with the device if the method passes {@link android.bluetooth.BluetoothProfile#STATE_CONNECTED} as the new state.

    Accessing Bluetooth features on a device also requires that your app request certain @@ -397,39 +401,39 @@ href="{@docRoot}guide/topics/connectivity/bluetooth-le.html">Bluetooth Low Energ

    Wi-Fi scan-only mode

    -

    When attempting to identify the user's location, Android may use Wi-Fi to help determine -the location by scanning nearby access points. However, users often keep Wi-Fi turned off to -conserve battery, resulting in location data that's less accurate. Android now includes a -scan-only mode that allows the device Wi-Fi to scan access points to help obtain the location +

    When attempting to identify the user's location, Android may use Wi-Fi to help determine +the location by scanning nearby access points. However, users often keep Wi-Fi turned off to +conserve battery, resulting in location data that's less accurate. Android now includes a +scan-only mode that allows the device Wi-Fi to scan access points to help obtain the location without connecting to an access point, thus greatly reducing battery usage.

    -

    If you want to acquire the user's location but Wi-Fi is currently off, you can request the -user to enable Wi-Fi scan-only mode by calling {@link android.content.Context#startActivity -startActivity()} with the action {@link +

    If you want to acquire the user's location but Wi-Fi is currently off, you can request the +user to enable Wi-Fi scan-only mode by calling {@link android.content.Context#startActivity +startActivity()} with the action {@link android.net.wifi.WifiManager#ACTION_REQUEST_SCAN_ALWAYS_AVAILABLE}.

    Wi-Fi configuration

    -

    New {@link android.net.wifi.WifiEnterpriseConfig} APIs allow enterprise-oriented services to +

    New {@link android.net.wifi.WifiEnterpriseConfig} APIs allow enterprise-oriented services to automate Wi-Fi configuration for managed devices.

    Quick response for incoming calls

    -

    Since Android 4.0, a feature called "Quick response" allows users to respond to incoming -calls with an immediate text message without needing to pick up the call or unlock the device. -Until now, these quick messages were always handled by the default Messaging app. Now any app -can declare its capability to handle these messages by creating a {@link android.app.Service} +

    Since Android 4.0, a feature called "Quick response" allows users to respond to incoming +calls with an immediate text message without needing to pick up the call or unlock the device. +Until now, these quick messages were always handled by the default Messaging app. Now any app +can declare its capability to handle these messages by creating a {@link android.app.Service} with an intent filter for {@link android.telephony.TelephonyManager#ACTION_RESPOND_VIA_MESSAGE}.

    -

    When the user responds to an incoming call with a quick response, the Phone app sends -the {@link android.telephony.TelephonyManager#ACTION_RESPOND_VIA_MESSAGE} intent with a URI -describing the recipient (the caller) and the {@link android.content.Intent#EXTRA_TEXT} extra -with the message the user wants to send. When your service receives the intent, it should deliver +

    When the user responds to an incoming call with a quick response, the Phone app sends +the {@link android.telephony.TelephonyManager#ACTION_RESPOND_VIA_MESSAGE} intent with a URI +describing the recipient (the caller) and the {@link android.content.Intent#EXTRA_TEXT} extra +with the message the user wants to send. When your service receives the intent, it should deliver the message and immediately stop itself (your app should not show an activity).

    -

    In order to receive this intent, you must declare the {@link +

    In order to receive this intent, you must declare the {@link android.Manifest.permission#SEND_RESPOND_VIA_MESSAGE} permission.

    @@ -438,120 +442,120 @@ android.Manifest.permission#SEND_RESPOND_VIA_MESSAGE} permission.

    MPEG DASH support

    -

    Android now supports Dynamic Adaptive Streaming over HTTP (DASH) in accordance with the -ISO/IEC 23009-1 standard, using existing APIs in {@link android.media.MediaCodec} and {@link -android.media.MediaExtractor}. The framework underlying these APIs has been updated to support -parsing of fragmented MP4 files, but your app is still responsible for parsing the MPD metadata +

    Android now supports Dynamic Adaptive Streaming over HTTP (DASH) in accordance with the +ISO/IEC 23009-1 standard, using existing APIs in {@link android.media.MediaCodec} and {@link +android.media.MediaExtractor}. The framework underlying these APIs has been updated to support +parsing of fragmented MP4 files, but your app is still responsible for parsing the MPD metadata and passing the individual streams to {@link android.media.MediaExtractor}.

    -

    If you want to use DASH with encrypted content, notice that the {@link android.media.MediaExtractor#getSampleCryptoInfo getSampleCryptoInfo()} method returns the {@link -android.media.MediaCodec.CryptoInfo} metadata describing the structure of each encrypted media -sample. Also, the {@link android.media.MediaExtractor#getPsshInfo()} method has been added to -{@link android.media.MediaExtractor} so you can access the PSSH metadata for your DASH media. -This method returns a map of {@link java.util.UUID} objects to bytes, with the -{@link java.util.UUID} specifying the crypto scheme, and the bytes being the data specific +

    If you want to use DASH with encrypted content, notice that the {@link android.media.MediaExtractor#getSampleCryptoInfo getSampleCryptoInfo()} method returns the {@link +android.media.MediaCodec.CryptoInfo} metadata describing the structure of each encrypted media +sample. Also, the {@link android.media.MediaExtractor#getPsshInfo()} method has been added to +{@link android.media.MediaExtractor} so you can access the PSSH metadata for your DASH media. +This method returns a map of {@link java.util.UUID} objects to bytes, with the +{@link java.util.UUID} specifying the crypto scheme, and the bytes being the data specific to that scheme.

    Media DRM

    The new {@link android.media.MediaDrm} class provides a modular solution for digital rights -management (DRM) with your media content by separating DRM concerns from media playback. For -instance, this API separation allows you to play back Widevine-encrypted content without having -to use the Widevine media format. This DRM solution also supports DASH Common Encryption so you +management (DRM) with your media content by separating DRM concerns from media playback. For +instance, this API separation allows you to play back Widevine-encrypted content without having +to use the Widevine media format. This DRM solution also supports DASH Common Encryption so you can use a variety of DRM schemes with your streaming content.

    -

    You can use {@link android.media.MediaDrm} to obtain opaque key-request messages and process -key-response messages from the server for license acquisition and provisioning. Your app is -responsible for handling the network communication with the servers; the {@link +

    You can use {@link android.media.MediaDrm} to obtain opaque key-request messages and process +key-response messages from the server for license acquisition and provisioning. Your app is +responsible for handling the network communication with the servers; the {@link android.media.MediaDrm} class provides only the ability to generate and process the messages.

    -

    The {@link android.media.MediaDrm} APIs are intended to be used in conjunction with the -{@link android.media.MediaCodec} APIs that were introduced in Android 4.1 (API level 16), -including {@link android.media.MediaCodec} for encoding and decoding your content, {@link -android.media.MediaCrypto} for handling encrypted content, and {@link android.media.MediaExtractor} +

    The {@link android.media.MediaDrm} APIs are intended to be used in conjunction with the +{@link android.media.MediaCodec} APIs that were introduced in Android 4.1 (API level 16), +including {@link android.media.MediaCodec} for encoding and decoding your content, {@link +android.media.MediaCrypto} for handling encrypted content, and {@link android.media.MediaExtractor} for extracting and demuxing your content.

    -

    You must first construct {@link android.media.MediaExtractor} and -{@link android.media.MediaCodec} objects. You can then access the DRM-scheme-identifying -{@link java.util.UUID}, typically from metadata in the content, and use it to construct an +

    You must first construct {@link android.media.MediaExtractor} and +{@link android.media.MediaCodec} objects. You can then access the DRM-scheme-identifying +{@link java.util.UUID}, typically from metadata in the content, and use it to construct an instance of a {@link android.media.MediaDrm} object with its constructor.

    Video encoding from a Surface

    -

    Android 4.1 (API level 16) added the {@link android.media.MediaCodec} class for low-level -encoding and decoding of media content. When encoding video, Android 4.1 required that you provide -the media with a {@link java.nio.ByteBuffer} array, but Android 4.3 now allows you to use a {@link -android.view.Surface} as the input to an encoder. For instance, this allows you to encode input +

    Android 4.1 (API level 16) added the {@link android.media.MediaCodec} class for low-level +encoding and decoding of media content. When encoding video, Android 4.1 required that you provide +the media with a {@link java.nio.ByteBuffer} array, but Android 4.3 now allows you to use a {@link +android.view.Surface} as the input to an encoder. For instance, this allows you to encode input from an existing video file or using frames generated from OpenGL ES.

    -

    To use a {@link android.view.Surface} as the input to your encoder, first call {@link -android.media.MediaCodec#configure configure()} for your {@link android.media.MediaCodec}. -Then call {@link android.media.MediaCodec#createInputSurface()} to receive the {@link +

    To use a {@link android.view.Surface} as the input to your encoder, first call {@link +android.media.MediaCodec#configure configure()} for your {@link android.media.MediaCodec}. +Then call {@link android.media.MediaCodec#createInputSurface()} to receive the {@link android.view.Surface} upon which you can stream your media.

    -

    For example, you can use the given {@link android.view.Surface} as the window for an OpenGL -context by passing it to {@link android.opengl.EGL14#eglCreateWindowSurface -eglCreateWindowSurface()}. Then while rendering the surface, call {@link -android.opengl.EGL14#eglSwapBuffers eglSwapBuffers()} to pass the frame to the {@link +

    For example, you can use the given {@link android.view.Surface} as the window for an OpenGL +context by passing it to {@link android.opengl.EGL14#eglCreateWindowSurface +eglCreateWindowSurface()}. Then while rendering the surface, call {@link +android.opengl.EGL14#eglSwapBuffers eglSwapBuffers()} to pass the frame to the {@link android.media.MediaCodec}.

    -

    To begin encoding, call {@link android.media.MediaCodec#start()} on the {@link -android.media.MediaCodec}. When done, call {@link android.media.MediaCodec#signalEndOfInputStream} -to terminate encoding, and call {@link android.view.Surface#release()} on the +

    To begin encoding, call {@link android.media.MediaCodec#start()} on the {@link +android.media.MediaCodec}. When done, call {@link android.media.MediaCodec#signalEndOfInputStream} +to terminate encoding, and call {@link android.view.Surface#release()} on the {@link android.view.Surface}.

    Media muxing

    -

    The new {@link android.media.MediaMuxer} class enables multiplexing between one audio stream -and one video stream. These APIs serve as a counterpart to the {@link android.media.MediaExtractor} +

    The new {@link android.media.MediaMuxer} class enables multiplexing between one audio stream +and one video stream. These APIs serve as a counterpart to the {@link android.media.MediaExtractor} class added in Android 4.2 for de-multiplexing (demuxing) media.

    -

    Supported output formats are defined in {@link android.media.MediaMuxer.OutputFormat}. Currently, -MP4 is the only supported output format and {@link android.media.MediaMuxer} currently supports +

    Supported output formats are defined in {@link android.media.MediaMuxer.OutputFormat}. Currently, +MP4 is the only supported output format and {@link android.media.MediaMuxer} currently supports only one audio stream and/or one video stream at a time.

    -

    {@link android.media.MediaMuxer} is mostly designed to work with {@link android.media.MediaCodec} -so you can perform video processing through {@link android.media.MediaCodec} then save the -output to an MP4 file through {@link android.media.MediaMuxer}. You can also use {@link -android.media.MediaMuxer} in combination with {@link android.media.MediaExtractor} to perform +

    {@link android.media.MediaMuxer} is mostly designed to work with {@link android.media.MediaCodec} +so you can perform video processing through {@link android.media.MediaCodec} then save the +output to an MP4 file through {@link android.media.MediaMuxer}. You can also use {@link +android.media.MediaMuxer} in combination with {@link android.media.MediaExtractor} to perform media editing without the need to encode or decode.

    Playback progress and scrubbing for RemoteControlClient

    -

    In Android 4.0 (API level 14), the {@link android.media.RemoteControlClient} was added to -enable media playback controls from remote control clients such as the controls available on the -lock screen. Android 4.3 now provides the ability for such controllers to display the playback -position and controls for scrubbing the playback. If you've enabled remote control for your -media app with the {@link android.media.RemoteControlClient} APIs, then you can allow playback +

    In Android 4.0 (API level 14), the {@link android.media.RemoteControlClient} was added to +enable media playback controls from remote control clients such as the controls available on the +lock screen. Android 4.3 now provides the ability for such controllers to display the playback +position and controls for scrubbing the playback. If you've enabled remote control for your +media app with the {@link android.media.RemoteControlClient} APIs, then you can allow playback scrubbing by implementing two new interfaces.

    -

    First, you must enable the {@link -android.media.RemoteControlClient#FLAG_KEY_MEDIA_POSITION_UPDATE} flag by passing it to -{@link android.media.RemoteControlClient#setTransportControlFlags setTransportControlsFlags()}.

    +

    First, you must enable the {@link +android.media.RemoteControlClient#FLAG_KEY_MEDIA_POSITION_UPDATE} flag by passing it to +{@link android.media.RemoteControlClient#setTransportControlFlags setTransportControlsFlags()}.

    Then implement the following two new interfaces:

    {@link android.media.RemoteControlClient.OnGetPlaybackPositionListener}
    -
    This includes the callback {@link android.media.RemoteControlClient.OnGetPlaybackPositionListener#onGetPlaybackPosition}, which requests the current position +
    This includes the callback {@link android.media.RemoteControlClient.OnGetPlaybackPositionListener#onGetPlaybackPosition}, which requests the current position of your media when the remote control needs to update the progress in its UI.
    {@link android.media.RemoteControlClient.OnPlaybackPositionUpdateListener}
    -
    This includes the callback {@link android.media.RemoteControlClient.OnPlaybackPositionUpdateListener#onPlaybackPositionUpdate onPlaybackPositionUpdate()}, which - tells your app the new time code for your media when the user scrubs the playback with the +
    This includes the callback {@link android.media.RemoteControlClient.OnPlaybackPositionUpdateListener#onPlaybackPositionUpdate onPlaybackPositionUpdate()}, which + tells your app the new time code for your media when the user scrubs the playback with the remote control UI. -

    Once you update your playback with the new position, call {@link - android.media.RemoteControlClient#setPlaybackState setPlaybackState()} to indicate the +

    Once you update your playback with the new position, call {@link + android.media.RemoteControlClient#setPlaybackState setPlaybackState()} to indicate the new playback state, position, and speed.

    -

    With these interfaces defined, you can set them for your {@link -android.media.RemoteControlClient} by calling {@link android.media.RemoteControlClient#setOnGetPlaybackPositionListener setOnGetPlaybackPositionListener()} and -{@link android.media.RemoteControlClient#setPlaybackPositionUpdateListener +

    With these interfaces defined, you can set them for your {@link +android.media.RemoteControlClient} by calling {@link android.media.RemoteControlClient#setOnGetPlaybackPositionListener setOnGetPlaybackPositionListener()} and +{@link android.media.RemoteControlClient#setPlaybackPositionUpdateListener setPlaybackPositionUpdateListener()}, respectively.

    @@ -560,7 +564,7 @@ setPlaybackPositionUpdateListener()}, respectively.

    Support for OpenGL ES 3.0

    -

    Android 4.3 adds Java interfaces and native support for OpenGL ES 3.0. Key new functionality +

    Android 4.3 adds Java interfaces and native support for OpenGL ES 3.0. Key new functionality provided in OpenGL ES 3.0 includes:

    • Acceleration of advanced visual effects
      • @@ -570,8 +574,8 @@ provided in OpenGL ES 3.0 includes:

    • Broader standardization of texture size and render-buffer formats
    -

    The Java interface for OpenGL ES 3.0 on Android is provided with {@link android.opengl.GLES30}. -When using OpenGL ES 3.0, be sure that you declare it in your manifest file with the +

    The Java interface for OpenGL ES 3.0 on Android is provided with {@link android.opengl.GLES30}. +When using OpenGL ES 3.0, be sure that you declare it in your manifest file with the <uses-feature> tag and the {@code android:glEsVersion} attribute. For example:

    @@ -586,16 +590,16 @@ tag and the {@code android:glEsVersion} attribute. For example:
    
 
 
    Mipmapping for drawables
    
 
-
    Using a mipmap as the source for your bitmap or drawable is a simple way to provide a 
-quality image and various image scales, which can be particularly useful if you expect your 
+
    Using a mipmap as the source for your bitmap or drawable is a simple way to provide a
+quality image and various image scales, which can be particularly useful if you expect your
 image to be scaled during an animation.
    
 
-
    Android 4.2 (API level 17) added support for mipmaps in the {@link android.graphics.Bitmap} 
-class—Android swaps the mip images in your {@link android.graphics.Bitmap} when you've 
-supplied a mipmap source and have enabled {@link android.graphics.Bitmap#setHasMipMap 
-setHasMipMap()}. Now in Android 4.3, you can enable mipmaps for a {@link 
-android.graphics.drawable.BitmapDrawable} object as well, by providing a mipmap asset and 
-setting the {@code android:mipMap} attribute in a bitmap resource file or by calling {@link 
+
    Android 4.2 (API level 17) added support for mipmaps in the {@link android.graphics.Bitmap}
+class—Android swaps the mip images in your {@link android.graphics.Bitmap} when you've
+supplied a mipmap source and have enabled {@link android.graphics.Bitmap#setHasMipMap
+setHasMipMap()}. Now in Android 4.3, you can enable mipmaps for a {@link
+android.graphics.drawable.BitmapDrawable} object as well, by providing a mipmap asset and
+setting the {@code android:mipMap} attribute in a bitmap resource file or by calling {@link
 android.graphics.drawable.BitmapDrawable#hasMipMap hasMipMap()}.
 
    
 
@@ -605,36 +609,36 @@ android.graphics.drawable.BitmapDrawable#hasMipMap hasMipMap()}.
 
 
    View overlays
    
 
-
    The new {@link android.view.ViewOverlay} class provides a transparent layer on top of 
-a {@link android.view.View} on which you can add visual content and which does not affect 
-the layout hierarchy. You can get a {@link android.view.ViewOverlay} for any {@link 
-android.view.View} by calling {@link android.view.View#getOverlay}. The overlay 
-always has the same size and position as its host view (the view from which it was created), 
-allowing you to add content that appears in front of the host view, but which cannot extend 
+
    The new {@link android.view.ViewOverlay} class provides a transparent layer on top of
+a {@link android.view.View} on which you can add visual content and which does not affect
+the layout hierarchy. You can get a {@link android.view.ViewOverlay} for any {@link
+android.view.View} by calling {@link android.view.View#getOverlay}. The overlay
+always has the same size and position as its host view (the view from which it was created),
+allowing you to add content that appears in front of the host view, but which cannot extend
 the bounds of that host view.
 
    
 
-
    Using a {@link android.view.ViewOverlay} is particularly useful when you want to create 
-animations such as sliding a view outside of its container or moving items around the screen 
-without affecting the view hierarchy. However, because the usable area of an overlay is 
-restricted to the same area as its host view, if you want to animate a view moving outside 
-its position in the layout, you must use an overlay from a parent view that has the desired 
+
    Using a {@link android.view.ViewOverlay} is particularly useful when you want to create
+animations such as sliding a view outside of its container or moving items around the screen
+without affecting the view hierarchy. However, because the usable area of an overlay is
+restricted to the same area as its host view, if you want to animate a view moving outside
+its position in the layout, you must use an overlay from a parent view that has the desired
 layout bounds.
    
 
-
    When you create an overlay for a widget view such as a {@link android.widget.Button}, you 
-can add {@link android.graphics.drawable.Drawable} objects to the overlay by calling 
-{@link android.view.ViewOverlay#add(Drawable)}. If you call {@link 
+
    When you create an overlay for a widget view such as a {@link android.widget.Button}, you
+can add {@link android.graphics.drawable.Drawable} objects to the overlay by calling
+{@link android.view.ViewOverlay#add(Drawable)}. If you call {@link
 android.view.ViewGroup#getOverlay} for a layout view, such as {@link android.widget.RelativeLayout},
 the object returned is a {@link android.view.ViewGroupOverlay}. The
-{@link android.view.ViewGroupOverlay} class is a subclass 
-of {@link android.view.ViewOverlay} that  also allows you to add {@link android.view.View} 
+{@link android.view.ViewGroupOverlay} class is a subclass
+of {@link android.view.ViewOverlay} that  also allows you to add {@link android.view.View}
 objects by calling {@link android.view.ViewGroupOverlay#add(View)}.
 
    
 
-
    Note: All drawables and views that you add to an overlay 
+
    Note: All drawables and views that you add to an overlay
 are visual only. They cannot receive focus or input events.
    
 
-
    For example, the following code animates a view sliding to the right by placing the view 
+
    For example, the following code animates a view sliding to the right by placing the view
 in the parent view's overlay, then performing a translation animation on that view:
    
 
     View view = findViewById(R.id.view_to_remove);
@@ -647,17 +651,17 @@ anim.start();
 
 
    Optical bounds layout
    
 
-
    For views that contain nine-patch background images, you can now specify that they should 
-be aligned with neighboring views based on the "optical" bounds of the background image rather 
+
    For views that contain nine-patch background images, you can now specify that they should
+be aligned with neighboring views based on the "optical" bounds of the background image rather
 than the "clip" bounds of the view.
    
 
-
    For example, figures 1 and 2 each show the same layout, but the version in figure 1 is 
-using clip bounds (the default behavior), while figure 2 is using optical bounds. Because the 
-nine-patch images used for the button and the photo frame include padding around the edges, 
+
    For example, figures 1 and 2 each show the same layout, but the version in figure 1 is
+using clip bounds (the default behavior), while figure 2 is using optical bounds. Because the
+nine-patch images used for the button and the photo frame include padding around the edges,
 they don’t appear to align with each other or the text when using clip bounds.
    
 
-
    Note: The screenshot in figures 1 and 2 have the "Show 
-layout bounds" developer setting enabled. For each view, red lines indicate the optical 
+
    Note: The screenshot in figures 1 and 2 have the "Show
+layout bounds" developer setting enabled. For each view, red lines indicate the optical
 bounds, blue lines indicate the clip bounds, and pink indicates margins.