diff options
26 files changed, 1613 insertions, 134 deletions
@@ -438,6 +438,8 @@ web_docs_sample_code_flags := \ resources/samples/TicTacToeLib "TicTacToeLib" \ -samplecode $(sample_dir)/TicTacToeMain \ resources/samples/TicTacToeMain "TicTacToeMain" \ + -samplecode $(sample_dir)/USB \ + resources/samples/USB "USB" \ -samplecode $(sample_dir)/WeatherListWidget \ resources/samples/WeatherListWidget "Weather List Widget" \ -samplecode $(sample_dir)/Wiktionary \ @@ -451,7 +453,7 @@ web_docs_sample_code_flags := \ ## SDK version identifiers used in the published docs # major[.minor] version for current SDK. (full releases only) -framework_docs_SDK_VERSION:=3.0 +framework_docs_SDK_VERSION:=3.1 # release version (ie "Release x") (full releases only) framework_docs_SDK_REL_ID:=1 diff --git a/docs/html/guide/developing/building/building-cmdline.jd b/docs/html/guide/developing/building/building-cmdline.jd index 5f193bc..ec918dc 100644 --- a/docs/html/guide/developing/building/building-cmdline.jd +++ b/docs/html/guide/developing/building/building-cmdline.jd @@ -6,16 +6,27 @@ parent.link=index.html <div id="qv-wrapper"> <div id="qv"> <h2>In this document</h2> - <ol> - <li><a href="#DebugMode">Building in debug mode</a></li> - - <li><a href="#ReleaseMode">Building in release mode</a></li> - - <li><a href="#RunningOnEmulator">Running on an emulator</a></li> - - <li><a href="#RunningOnDevice">Running on a device</a></li> + <li><a href="#DebugMode">Building in Debug Mode</a></li> + <li><a href="#ReleaseMode">Building in Release Mode</a> + <ol> + <li><a href="#ManualReleaseMode">Build unsigned</a></li> + <li><a href="#AutoReleaseMode">Build signed and aligned</a></li> + <li><a href="#OnceBuilt">Once built and signed in release mode</a></li> + </ol> + </li> + <li><a href="#RunningOnEmulator">Running on the Emulator</a></li> + <li><a href="#RunningOnDevice">Running on a Device</a></li> + <li><a href="#Signing">Application Signing</a></li> </ol> + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing AVDs from +the Command Line</a></li> + <li><a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android +Emulator</a></li> + <li><a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a></li> + </ol> </div> </div> @@ -54,7 +65,7 @@ parent.link=index.html <pre>c:\java\jdk1.6.0_02</pre> - <h2 id="DebugMode">Building in debug mode</h2> + <h2 id="DebugMode">Building in Debug Mode</h2> <p>For immediate application testing and debugging, you can build your application in debug mode and immediately install it on an emulator. In debug mode, the build tools automatically sign your @@ -83,7 +94,7 @@ ant debug <p>To install and run your application on an emulator, see the following section about <a href= "#RunningOnEmulator">Running on the Emulator</a>.</p> - <h2 id="ReleaseMode">Building in release mode</h2> + <h2 id="ReleaseMode">Building in Release Mode</h2> <p>When you're ready to release and distribute your application to end-users, you must build your application in release mode. Once you have built in release mode, it's a good idea to perform @@ -172,7 +183,7 @@ ant release been signed with the private key specified in {@code build.properties} and aligned with {@code zipalign}. It's ready for installation and distribution.</p> - <h3>Once built and signed in release mode</h3> + <h3 id="OnceBuilt">Once built and signed in release mode</h3> <p>Once you have signed your application with a private key, you can install and run it on an <a href="#RunningOnEmulator">emulator</a> or <a href="#RunningOnDevice">device</a>. You can @@ -181,7 +192,7 @@ ant release installation. (On your device, be sure you have enabled <em>Settings > Applications > Unknown sources</em>.)</p> - <h2 id="RunningOnEmulator">Running on the emulator</h2> + <h2 id="RunningOnEmulator">Running on the Emulator</h2> <p>Before you can run your application on the Android Emulator, you must <a href= "{@docRoot}guide/developing/devices/managing-avds.html">create an AVD</a>.</p> @@ -243,7 +254,7 @@ adb -s emulator-5554 install <em>path/to/your/app</em>.apk install</code>. This will build your application, sign it with the debug key, and install it on the currently running emulator.</p> - <h2 id="RunningOnDevice">Running on a device</h2> + <h2 id="RunningOnDevice">Running on a Device</h2> <p>Before you can run your application on a device, you must perform some basic setup for your device:</p> @@ -297,7 +308,7 @@ adb -d install <em>path/to/your/app</em>.apk <p>The ADT plugin helps you get started quickly by signing your .apk files with a debug key, prior to installing them on an emulator or development device. This means that you can quickly run your application from Eclipse without having to generate your own private key. No specific - action on your part is needed, provided ADT has access to Keytool.However, please note that if + action on your part is needed, provided ADT has access to Keytool. However, please note that if you intend to publish your application, you <strong>must</strong> sign the application with your own private key, rather than the debug key generated by the SDK tools.</p> diff --git a/docs/html/guide/developing/devices/managing-avds-cmdline.jd b/docs/html/guide/developing/devices/managing-avds-cmdline.jd index 6feeeb6..8674334 100644 --- a/docs/html/guide/developing/devices/managing-avds-cmdline.jd +++ b/docs/html/guide/developing/devices/managing-avds-cmdline.jd @@ -7,12 +7,25 @@ parent.link=index.html <div id="qv"> <h2>In this document</h2> <ol> - <li><a href="#listingtargets">Listing targets</a></li> - <li><a href="#AVDCmdLine">Creating AVDs</a></li> + <li><a href="#listingtargets">Listing Targets</a></li> + <li><a href="#AVDCmdLine">Creating AVDs</a> + <ol> + <li><a href="#CustomDensity">Customize the device resolution or density</a></li> + <li><a href="#DefaultLocation">Default location of AVD files</a></li> + <li><a href="#hardwareopts">Setting hardware emulation options</a></li> + </ol> + </li> <li><a href="#moving">Moving an AVD</a></li> <li><a href="#updating">Updating an AVD</a></li> <li><a href="#deleting">Deleting an AVD</a></li> </ol> + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/developing/building/building-cmdline.html">Building and Running +from the Command Line</a></li> + <li><a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android +Emulator</a></li> + </ol> </div> </div> @@ -23,7 +36,7 @@ of the command line options that you can use, see the reference for the -<h2 id="listingtargets">Listing targets</h2> +<h2 id="listingtargets">Listing Targets</h2> <p>To generate a list of system image targets, use this command: </p> @@ -67,7 +80,10 @@ id: 5 or "android-9" Skins: HVGA (default), WVGA800, WQVGA432, QVGA, WVGA854, WQVGA400 </pre> -<h2 id="AVDCmdLine">Creating AVDs</h2> + + +<h2 id="AVDCmdLine">Creating AVDs</h2> + <p>In addition to creating AVDs with the <a href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">AVD Manager user interface</a>, you can also create them by passing in command line arguments to the <code>android</code> tool. @@ -92,8 +108,9 @@ general characteristics offered by the AVD. The target ID is an integer assigned <code>android</code> tool. The target ID is not derived from the system image name, version, or API Level, or other attribute, so you need to run the <code>android list targets</code> command to list the target ID of each system image. You should do this <em>before</em> you run -the <code>android create avd</code> command. See the <a href="{@docRoot}guide/developing/tools/android.html">android</a></p> -tool documentation for more information on the command line options. +the <code>android create avd</code> command. See the <a +href="{@docRoot}guide/developing/tools/android.html">android</a> +tool documentation for more information on the command line options.</p> <p>When you've selected the target you want to use and made a note of its ID, @@ -124,7 +141,45 @@ appropriately for the device that the add-on is modeling, and so prevents you from resetting the options. </p> -<h3>Default location of AVD files</h3> +<h3 id="CustomDensity">Customize the device resolution or density</h3> + +<p>When testing your application, we recommend that you test your application in several different +AVDs, using different screen configurations (different combinations of size and density). In +addition, you should set up the AVDs to run at a physical size that closely matches an actual +device.</p> + +<p>To set up your AVDs for a specific resolution or density, follow these steps:</p> + +<ol> + <li>Use the <code>create avd</code> command to create a new AVD, specifying +the <code>--skin</code> option with a value that references either a default +skin name (such as "WVGA800") or a custom skin resolution (such as 240x432). +Here's an example: + <pre>android create avd -n <name> -t <targetID> --skin WVGA800</pre> + </li> + <li>To specify a custom density for the skin, answer "yes" when asked whether +you want to create a custom hardware profile for the new AVD.</li> + <li>Continue through the various profile settings until the tool asks you to +specify "Abstracted LCD density" (<em>hw.lcd.density</em>). Enter an appropriate +value, such as "120" for a low-density screen, "160" for a medium density screen, +or "240" for a high-density screen.</li> + <li>Set any other hardware options and complete the AVD creation.</li> +</ol> + +<p>In the example above (WVGA medium density), the new AVD will emulate a 5.8" +WVGA screen.</p> + +<p>As an alternative to adjusting the emulator skin configuration, you can use +the emulator skin's default density and add the <code>-dpi-device</code> option +to the <a href="{@docRoot}guide/developing/tools/emulator.html">emulator</a> command line when +starting the AVD. For example:</p> + +<pre>emulator -avd WVGA800 -scale 96dpi -dpi-device 160</pre> + + + +<h3 id="DefaultLocation">Default location of AVD files</h3> + <p>When you create an AVD, the <code>android</code> tool creates a dedicated directory for it on your development computer. The directory contains the AVD configuration file, the user data image and SD card image (if available), and any other files @@ -153,7 +208,7 @@ The AVD's .ini file remains in the .android directory on the network drive, regardless of the location of the AVD directory. -<h3 id="hardwareopts">Setting Hardware Emulation Options</h3> +<h3 id="hardwareopts">Setting hardware emulation options</h3> <p>When you are creating a new AVD that uses a standard Android system image ("Type: platform"), the <code>android</code> tool lets you set hardware emulation diff --git a/docs/html/guide/developing/projects/projects-cmdline.jd b/docs/html/guide/developing/projects/projects-cmdline.jd index 7c3e40e..90f88fb 100644 --- a/docs/html/guide/developing/projects/projects-cmdline.jd +++ b/docs/html/guide/developing/projects/projects-cmdline.jd @@ -9,13 +9,20 @@ parent.link=index.html <ol> <li><a href="#CreatingAProject">Creating an Android Project</a></li> - <li><a href="#UpdatingAProject">Updating a Project</a></li> - - <li><a href="#SettingUpLibraryProject">Setting up a Library Project</a></li> - - <li><a href="#ReferencingLibraryProject">Referencing a Library Project from an - Application</a></li> + <li><a href="#SettingUpLibraryProject">Setting up a Library Project</a> + <ol> + <li><a href="#CreatingManifestFile">Creating the manifest file</a></li> + <li><a href="#UpdatingLibraryProject">Updating a library project</a></li> + </ol> + </li> + <li><a href="#ReferencingLibraryProject">Referencing a Library Project</a> + <ol> + <li><a href="#DeclaringLibrary">Declaring library components in the manifest +file</a></li> + <li><a href="#depAppBuild">Building a dependent application</a></li> + </ol> + </li> </ol> <h2>See also</h2> @@ -108,7 +115,7 @@ android create project \ SDK directory, because this will break the build scripts. (They will need to be manually updated to reflect the new SDK location before they will work again.)</p> - <h2 id="UpdatingAProject">Updating a project</h2> + <h2 id="UpdatingAProject">Updating a Project</h2> <p>If you're upgrading a project from an older version of the Android SDK or want to create a new project from existing code, use the <code>android update project</code> command to update the @@ -142,7 +149,7 @@ android update project --name <project_name> --target <target_ID> android update project --name MyApp --target 2 --path ./MyAppProject </pre> - <h2 id="SettingUpLibraryProject">Setting up a library project</h2> + <h2 id="SettingUpLibraryProject">Setting up a Library Project</h2> <p>A library project is a standard Android project, so you can create a new one in the same way as you would a new application project. Specifically, you can use the <code>android</code> tool @@ -171,7 +178,7 @@ android.library=true applications can use it, you can do so by adding a the <code>android.library=true</code> property to the application's <code>default.properties</code> file.</p> - <h4>Creating the manifest file</h4> + <h3 id="CreatingManifestFile">Creating the manifest file</h3> <p>A library project's manifest file must declare all of the shared components that it includes, just as would a standard Android application. For more information, see the documentation for @@ -191,7 +198,7 @@ android.library=true </manifest> </pre> - <h4>Updating a library project</h4> + <h3 id="UpdatingLibraryProject">Updating a library project</h3> <p>If you want to update the build properties (build target, location) of the library project, use this command:</p> @@ -249,7 +256,7 @@ android.library.reference.1=path/to/library_projectC that, at build time, libraries are not merged with each other before being merged with the application.</p> - <h3>Declaring library components in the the manifest file</h3> + <h3 id="DeclaringLibrary">Declaring library components in the manifest file</h3> <p>In the manifest file of the application project, you must add declarations of all components that the application will use that are imported from a library project. For example, you must diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 46763c2..35acdd7 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -60,14 +60,14 @@ <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/fundamentals/activities.html"> <span class="en">Activities</span> - </a> <span class="new-child">new!</span></div> + </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/fundamentals/fragments.html"> <span class="en">Fragments</span> - </a> <span class="new">new!</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/topics/fundamentals/loaders.html"> <span class="en">Loaders</span> - </a> <span class="new">new!</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/topics/fundamentals/tasks-and-back-stack.html"> <span class="en">Tasks and Back Stack</span></a></li> </ul> @@ -98,8 +98,7 @@ <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/ui/index.html"> <span class="en">User Interface</span> - </a> - <span class="new-child">new!</span></div> + </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/ui/declaring-layout.html"> <span class="en">Declaring Layout</span> @@ -109,7 +108,7 @@ </a></li> <li><a href="<?cs var:toroot ?>guide/topics/ui/actionbar.html"> <span class="en">Using the Action Bar</span> - </a> <span class="new">new!</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/topics/ui/dialogs.html"> <span class="en">Creating Dialogs</span> </a></li> @@ -131,8 +130,7 @@ </li> <li><a href="<?cs var:toroot ?>guide/topics/ui/drag-drop.html"> <span class="en">Dragging and Dropping</span> - </a> <span class="new">new!</span> - </li> + </a></li> <li><a href="<?cs var:toroot ?>guide/topics/ui/themes.html"> <span class="en">Applying Styles and Themes</span> </a></li> @@ -238,8 +236,7 @@ <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/graphics/index.html"> <span class="en">Graphics</span> - </a> - <span class="new-child">new!</span></div> + </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/graphics/2d-graphics.html"> <span class="en">2D Graphics</span> @@ -249,10 +246,10 @@ </a></li> <li><a href="<?cs var:toroot ?>guide/topics/graphics/renderscript.html"> <span class="en">3D with Renderscript</span> - </a> <span class="new">new!</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/topics/graphics/animation.html"> <span class="en">Property Animation</span> - </a> <span class="new">new!</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/topics/graphics/view-animation.html"> <span class="en">View Animation</span> </a></li> @@ -264,9 +261,7 @@ <li> <a href="<?cs var:toroot ?>guide/topics/clipboard/copy-paste.html"> <span class="en">Copy and Paste</span> - </a> - <span class="new">new!</span> - </li> + </a></li> <!--<li class="toggle-list"> <div><a style="color:gray;">Sensors</a></div> <ul> @@ -299,12 +294,22 @@ <span class="en">Bluetooth</span> </a></li> <li><a href="<?cs var:toroot?>guide/topics/nfc/index.html"> - <span class="en">Near Field Communication</span></a> - <span class="new">new!</span></li> - <li><a href="<?cs var:toroot?>guide/topics/network/sip.html"> - <span class="en">Session Initiation Protocol</span></a> + <span class="en">Near Field Communication</span> + </a></li> + <li class="toggle-list"> + <div><a href="<?cs var:toroot?>guide/topics/usb/index.html"> + <span class="en">USB</span></a> <span class="new">new!</span> + </div> + <ul> + <li><a href="<?cs var:toroot ?>guide/topics/usb/accessory.html">Accessory</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/usb/host.html">Host</a></li> + </ul> </li> + + <li><a href="<?cs var:toroot?>guide/topics/network/sip.html"> + <span class="en">Session Initiation Protocol</span> + </a></li> <li class="toggle-list"> <div><a href="<?cs var:toroot?>guide/topics/search/index.html"> <span class="en">Search</span> @@ -347,7 +352,6 @@ <a href="<?cs var:toroot ?>guide/topics/testing/what_to_test.html"> <span class="en">What To Test</span></a> </li> - </ul> </li> </ul> @@ -364,7 +368,6 @@ <li class="toggle-list"> <div><a href="<?cs var:toroot?>guide/market/billing/index.html"> <span class="en">In-app Billing</span></a> - <span class="new">updated</span> </div> <ul> <li><a href="<?cs var:toroot?>guide/market/billing/billing_about.html"> @@ -654,7 +657,7 @@ </a></li> <li><a href="<?cs var:toroot ?>guide/practices/optimizing-for-3.0.html"> <span class="en">Optimizing Apps for Android 3.0</span> - </a> <span class="new">new!</span></li> + </a></li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/index.html"> <span class="en">UI Guidelines</span> @@ -700,7 +703,7 @@ <ul> <li><a href="<?cs var:toroot ?>guide/practices/design/accessibility.html"> <span class="en">Designing for Accessibility</span> - </a> <span class="new">new!</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/practices/design/performance.html"> <span class="en">Designing for Performance</span> </a></li> @@ -754,7 +757,7 @@ </a></li> <li><a href="<?cs var:toroot ?>guide/appendix/media-formats.html"> <span class="en">Supported Media Formats</span> - </a> <span class="new">updated</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/appendix/g-app-intents.html"> <span class="en">Intents List: Google Apps</span> </a></li> diff --git a/docs/html/guide/market/billing/billing_integrate.jd b/docs/html/guide/market/billing/billing_integrate.jd index 59344ba..1a1f02a 100755 --- a/docs/html/guide/market/billing/billing_integrate.jd +++ b/docs/html/guide/market/billing/billing_integrate.jd @@ -299,7 +299,9 @@ onto a device to run it. To run the sample application, do the following:</p> purchases will show up as actual payouts to your merchant account.</p> </ol> -<p class="note"><strong>Note</strong>: Debug log messages are turned off by default in the sample application. You can turn them on by setting the variable <code>DEBUG</code> to <code>true</code> in the <code>Consts.java</code> file.</p> +<p class="note"><strong>Note</strong>: Debug log messages are turned off by default in the +sample application. You can turn them on by setting the variable <code>DEBUG</code> +to <code>true</code> in the <code>Consts.java</code> file.</p> <h2 id="billing-add-aidl">Adding the AIDL file to your project</h2> @@ -598,7 +600,7 @@ to the Bundle prior to invoking the <code>sendBillingRequest()</code> method.</p <code>PURCHASE_INTENT</code> key provides you with a {@link android.app.PendingIntent}, which you can use to launch the checkout UI.</p> -<h5>Launching the pending intent</h5> +<h5>Using the pending intent</h5> <p>How you use the pending intent depends on which version of Android a device is running. On Android 1.6, you must use the pending intent to launch the checkout UI in its own separate task @@ -649,16 +651,58 @@ application.</p> <p>A <code>REQUEST_PURCHASE</code> request also triggers two asynchronous responses (broadcast intents). First, the Android Market application sends a <code>RESPONSE_CODE</code> broadcast intent, -which provides error information about the request. Next, if the request was successful, the Android -Market application sends an <code>IN_APP_NOTIFY</code> broadcast intent. This message contains a -notification ID, which you can use to retrieve the transaction details for the -<code>REQUEST_PURCHASE</code> request.</p> - -<p>Keep in mind, the Android Market application also sends an <code>IN_APP_NOTIFY</code> for -refunds. For more information, see <a +which provides error information about the request. If the request does not generate an +error, the <code>RESPONSE_CODE</code> broadcast intent returns <code>RESULT_OK</code>, which +indicates that the request was successfully sent. (To be clear, a <code>RESULT_OK</code> response +does not indicate that the requested purchase was successful; it indicates that the request was sent +successfully to Android Market.)</p> + +<p>Next, when the requested transaction changes state (for example, the purchase is successfully +charged to a credit card or the user cancels the purchase), the Android Market application sends an +<code>IN_APP_NOTIFY</code> broadcast intent. This message contains a notification ID, which you can +use to retrieve the transaction details for the <code>REQUEST_PURCHASE</code> request.</p> + +<p class="note"><strong>Note:</strong> The Android Market application also sends +an <code>IN_APP_NOTIFY</code> for refunds. For more information, see <a href="{@docRoot}guide/market/billing/billing_overview.html#billing-action-notify">Handling IN_APP_NOTIFY messages</a>.</p> +<p>Because the purchase process is not instantaneous and can take several seconds (or more), you +must assume that a purchase request is pending from the time you receive a <code>RESULT_OK</code> +message until you receive an <code>IN_APP_NOTIFY</code> message for the transaction. While the +transaction is pending, the Android Market checkout UI displays an "Authorizing purchase..." +notification; however, this notification is dismissed after 60 seconds and you should not rely on +this notification as your primary means of conveying transaction status to users. Instead, we +recommend that you do the following:</p> + +<ul> + <li>Add an {@link android.app.Activity} to your application that shows users the status of pending +and completed in-app purchases.</li> + <li>Use a <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">status +bar notification</a> to keep users informed about the progress of a purchase.</li> +</ul> + +<p>To use these two UI elements, you could invoke a status bar notification with a ticker-text +message that says "Purchase pending" when your application receives a <code>RESULT_OK</code> +message. Then, when your application receives an <code>IN_APP_NOTIFY</code> message, you could +update the notification with a new message that says "Purchase succeeded" or "Purchase failed." When +a user touches the expanded status bar notification, you could launch the activity that shows the +status of pending and completed in-app purchases.</p> + +<p>If you use some other UI technique to inform users about the state of a pending transaction, +be sure that your pending status UI does not block your application. For example, you should avoid +using a hovering progress wheel to convey the status of a pending transaction because a pending +transaction could last a long time, particularly if a device loses network connectivity and cannot +receive transaction updates from Android Market.</p> + +<p class="caution"><strong>Important:</strong> If a user purchases a managed item, you must prevent +the user from purchasing the item again while the original transaction is pending. If a user +attempts to purchase a managed item twice, and the first transaction is still pending, Android +Market will display an error to the user; however, Android Market will not send an error to your +application notifying you that the second purchase request was canceled. This might cause your +application to get stuck in a pending state while it waits for an <code>IN_APP_NOTIFY</code> message +for the second purchase request.</p> + <h4>Retrieving transaction information for a purchase or refund (GET_PURCHASE_INFORMATION)</h4> <p>You retrieve transaction information in response to an <code>IN_APP_NOTIFY</code> broadcast diff --git a/docs/html/guide/topics/admin/device-admin.jd b/docs/html/guide/topics/admin/device-admin.jd index b86a5f0..7dddd9a 100644 --- a/docs/html/guide/topics/admin/device-admin.jd +++ b/docs/html/guide/topics/admin/device-admin.jd @@ -128,6 +128,60 @@ can require PIN or passwords to have at least six characters. </td> </tr> combination of letters and numbers. They may include symbolic characters. </td> </tr> + + <tr> + <td>Complex password required</td> + <td>Requires that passwords must contain at least a letter, a numerical digit, and a special symbol. Introduced in Android 3.0. + </td> + </tr> + +<tr> + <td>Minimum letters required in password</td> <td>The minimum number of +letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +</tr> + + + <tr> + <td>Minimum lowercase letters required in password</td> + <td>The minimum number of lowercase +letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +</tr> + + <tr> + <td>Minimum non-letter characters required in password</td> + <td>The minimum number of +non-letter characters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +</tr> + +<tr> + <td>Minimum numerical digits required in password</td> + <td>The minimum number of numerical digits required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +</tr> + +<tr> + <td>Minimum symbols required in password</td> + <td>The minimum number of symbols required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +</tr> + +<tr> + <td>Minimum uppercase letters required in password</td> + <td>The minimum number of uppercase letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +</tr> + +<tr> + <td>Password expiration timeout</td> + <td>When the password will expire, expressed as a delta in milliseconds from when a device admin sets the expiration timeout. Introduced in Android 3.0.</td> +</tr> + +<tr> + <td>Password history restriction</td> + <td>This policy prevents users from reusing the last <em>n</em> unique passwords. + This policy is typically used in conjunction with +{@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()}, which forces +users to update their passwords after a specified amount of time has elapsed. +Introduced in Android 3.0.</td> +</tr> + <tr> <td>Maximum failed password attempts </td> <td>Specifies how many times a user can enter the wrong password before the @@ -141,6 +195,12 @@ device is lost or stolen.</td> pressed a button before the device locks the screen. When this happens, users need to enter their PIN or passwords again before they can use their devices and access data. The value can be between 1 and 60 minutes.</td> </tr> + +<tr> +<td>Require storage encryption</td> +<td>Specifies that the storage area should be encrypted, if the device supports it. +Introduced in Android 3.0.</td> </tr> + </table> <h4>Other features</h4> @@ -172,18 +232,28 @@ they've enabled the application, they can use the buttons in the user interface to do the following:</p> <ul> <li>Set password quality.</li> - <li>Specify the minimum length for the user's password.</li> + <li>Specify requirements for the user's password, such as minimum length, the minimum number of + numeric characters it must contain, and so on.</li> <li>Set the password. If the password does not conform to the specified policies, the system returns an error.</li> <li>Set how many failed password attempts can occur before the device is wiped (that is, restored to factory settings).</li> +<li>Set how long from now the password will expire.</li> +<li>Set the password history length (<em>length</em> refers to number of old passwords stored in the history). +This prevents users from reusing +one of the last <em>n</em> passwords they previously used.</li> +<li>Specify that the storage area should be encrypted, if the device supports it.</li> <li>Set the maximum amount of inactive time that can elapse before the device locks.</li> <li>Make the device lock immediately.</li> <li>Wipe the device's data (that is, restore factory settings).</li> + </ul> + + <img src="{@docRoot}images/admin/device-admin-app.png"/> + <p class="img-caption"><strong>Figure 1.</strong> Screenshot of the Sample Application</p> @@ -469,7 +539,13 @@ password containing at least <em>both</em> numeric <em>and</em> alphabetic (or other symbol) characters.</dd> <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_NUMERIC}</dt><dd>The user must enter a password containing at least numeric characters.</dd> - <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_SOMETHING}</dt><dd>The policy requires some kind +<dt>{@link +android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_COMPLEX}</dt><dd>The user +must have entered a password containing at least a letter, a numerical digit and +a special symbol.</dd> +<dt>{@link +android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_SOMETHING}</dt><dd>The +policy requires some kind of password, but doesn't care what it is.</dd> <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_UNSPECIFIED}</dt><dd> The policy has no requirements for the password. </dd> @@ -482,6 +558,36 @@ ComponentName mDeviceAdminSample; mDPM.setPasswordQuality(mDeviceAdminSample, DevicePolicyManager.PASSWORD_QUALITY_ALPHANUMERIC); </pre> +<h5>Set password content requirements</h5> + +<p>Beginning with Android 3.0, the {@link android.app.admin.DevicePolicyManager} class +includes methods that let you fine-tune the contents of the password. For +example, you could set a policy that states that passwords must contain at least +<em>n</em> uppercase letters. Here are the methods for fine-tuning a password's +contents:</p> +<ul> + +<li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumLetters(android.content.ComponentName,int) setPasswordMinimumLetters()}</li> + +<li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumLowerCase(android.content.ComponentName,int) setPasswordMinimumLowerCase()}</li> + +<li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumUpperCase(android.content.ComponentName,int) setPasswordMinimumUpperCase()}</li> + +<li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumNonLetter(android.content.ComponentName,int) setPasswordMinimumNonLetter()}</li> + +<li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumNumeric(android.content.ComponentName,int) setPasswordMinimumNumeric()}</li> + +<li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumSymbols(android.content.ComponentName,int) setPasswordMinimumSymbols()}</li> +</ul> +<p>For example, this snippet states that the password must have at least 2 uppercase letters:</p> +<pre> +DevicePolicyManager mDPM; +ComponentName mDeviceAdminSample; +int pwMinUppercase = 2; +... +mDPM.setPasswordMinimumUpperCase(mDeviceAdminSample, pwMinUppercase);</pre> + + <h5>Set the minimum password length</h5> <p>You can specify that a password must be at least the specified minimum length. For example:</p> @@ -501,7 +607,86 @@ int maxFailedPw; ... mDPM.setMaximumFailedPasswordsForWipe(mDeviceAdminSample, maxFailedPw);</pre> -<h4 id="lock">Set device lock</h4> +<h5 id="expiration">Set password expiration timeout</h5> +<p>Beginning with Android 3.0, you can use the +{@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()} +method to set when a password will expire, expressed as a delta in milliseconds from when a device admin sets the expiration timeout. For example:</p> + +<pre>DevicePolicyManager mDPM; +ComponentName mDeviceAdminSample; +long pwExpiration; +... +mDPM.setPasswordExpirationTimeout(mDeviceAdminSample, pwExpiration); +</pre> + +<p>From the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ +DeviceAdminSample.html"> Device Administration API sample</a>, here is the code +that updates the password expiration status:</p> + +<pre> +DevicePolicyManager mDPM; +ComponentName mDeviceAdminSample; +private TextView mPasswordExpirationStatus; +... +void updatePasswordExpirationStatus() { + boolean active = mDPM.isAdminActive(mDeviceAdminSample); + String statusText; + if (active) { + long now = System.currentTimeMillis(); + // Query the DevicePolicyManager twice - first for the expiration values + // set by the sample app, and later, for the system values (which may be different + // if there is another administrator active.) + long expirationDate = mDPM.getPasswordExpiration(mDeviceAdminSample); + long mSecUntilExpiration = expirationDate - now; + if (mSecUntilExpiration >= 0) { + statusText = "Expiration in " + countdownString(mSecUntilExpiration); + } else { + statusText = "Expired " + countdownString(-mSecUntilExpiration) + " ago"; + } + + // expirationTimeout is the cycle time between required password refresh + long expirationTimeout = mDPM.getPasswordExpirationTimeout(mDeviceAdminSample); + statusText += " / timeout period " + countdownString(expirationTimeout); + + // Now report the aggregate (global) expiration time + statusText += " / Aggregate "; + expirationDate = mDPM.getPasswordExpiration(null); + mSecUntilExpiration = expirationDate - now; + if (mSecUntilExpiration >= 0) { + statusText += "expiration in " + countdownString(mSecUntilExpiration); + } else { + statusText += "expired " + countdownString(-mSecUntilExpiration) + " ago"; + } + } else { + statusText = "<inactive>"; + } + mPasswordExpirationStatus.setText(statusText);</pre> + +<h5 id="history">Restrict password based on history</h5> + +<p>Beginning with Android 3.0, you can use the +{@link android.app.admin.DevicePolicyManager#setPasswordHistoryLength(android.content.ComponentName,int) setPasswordHistoryLength()} +method to limit users' +ability to reuse old passwords. This method takes a <em>length</em> +parameter, which specifies how many old +passwords are stored. When this policy is active, users cannot enter a new +password that matches the last <em>n</em> passwords. This prevents +users from using the same password over and over. This policy is typically used +in conjunction with +{@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()}, +which forces users +to update their passwords after a specified amount of time has elapsed. </p> + +<p>For example, this snippet prohibits users from reusing any of their last 5 passwords:</p> + +<pre>DevicePolicyManager mDPM; +ComponentName mDeviceAdminSample; +int pwHistoryLength = 5; +... +mDPM.setPasswordHistoryLength(mDeviceAdminSample, pwHistoryLength); +</pre> + +<h4 id="lock">Set device lock</h4> <p>You can set the maximum period of user inactivity that can occur before the device locks. For example:</p> <pre> @@ -516,6 +701,8 @@ mDPM.setMaximumTimeToLock(mDeviceAdminSample, timeMs); DevicePolicyManager mDPM; mDPM.lockNow();</pre> + + <h4 id="wipe">Perform data wipe</h4> <p>You can use the {@link android.app.admin.DevicePolicyManager} method @@ -530,3 +717,20 @@ DevicePolicyManager mDPM; mDPM.wipeData(0);</pre> <p>The {@link android.app.admin.DevicePolicyManager#wipeData wipeData()} method takes as its parameter a bit mask of additional options. Currently the value must be 0. </p> + +<h4 id=storage">Storage encryption</h4> +<p>Beginning with Android 3.0, you can use the +{@link android.app.admin.DevicePolicyManager#setStorageEncryption(android.content.ComponentName,boolean) setStorageEncryption()} +method to set a policy requiring encryption of the storage area, where supported.</p> + +<p>For example:</p> + +<pre> +DevicePolicyManager mDPM; +ComponentName mDeviceAdminSample; +... +mDPM.setStorageEncryption(mDeviceAdminSample, true); +</pre> +<p> +See the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> Device Administration API sample</a> for a complete +example of how to enable storage encryption.</p> diff --git a/docs/html/guide/topics/resources/menu-resource.jd b/docs/html/guide/topics/resources/menu-resource.jd index 5c1eed0..5b90ce2 100644 --- a/docs/html/guide/topics/resources/menu-resource.jd +++ b/docs/html/guide/topics/resources/menu-resource.jd @@ -49,14 +49,14 @@ In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code> android:alphabeticShortcut="<em>string</em>" android:numericShortcut="<em>string</em>" android:checkable=["true" | "false"] - android:visible=["visible" | "invisible" | "gone"] - android:enabled=["enabled" | "disabled"] + android:visible=["true" | "false"] + android:enabled=["true" | "false"] android:menuCategory=["container" | "system" | "secondary" | "alternative"] android:orderInCategory="<em>integer</em>" /> <<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>" android:checkableBehavior=["none" | "all" | "single"] - android:visible=["visible" | "invisible" | "gone"] - android:enabled=["enabled" | "disabled"] + android:visible=["true" | "false"] + android:enabled=["true" | "false"] android:menuCategory=["container" | "system" | "secondary" | "alternative"] android:orderInCategory="<em>integer</em>" > <<a href="#item-element">item</a> /> diff --git a/docs/html/guide/topics/usb/accessory.jd b/docs/html/guide/topics/usb/accessory.jd new file mode 100644 index 0000000..b0f4881 --- /dev/null +++ b/docs/html/guide/topics/usb/accessory.jd @@ -0,0 +1,461 @@ +page.title=USB Accessory +@jd:body + + <div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li> + <a href="#choosing">Choosing the Right USB Accessory APIs</a> + + <ol> + <li><a href="#installing">Installing the Google APIs add-on library</a></li> + </ol> + </li> + + <li> + <a href="#api">API Overview</a> + + <ol> + <li><a href="#usage">Usage differences between the add-on library and the platform + APIs</a></li> + </ol> + </li> + + <li><a href="#manifest">Android Manifest Requirements</a></li> + + <li> + <a href="#working-a">Working with accessories</a> + + <ol> + <li><a href="#discovering-a">Discovering an accessory</a></li> + + <li><a href="#permission-a">Obtaining permission to communicate with an + accessory</a></li> + + <li><a href="#communicating-a">Communicating with an accessory</a></li> + + <li><a href="#terminating-a">Terminating communication with an accessory</a></li> + </ol> + </li> + </ol> + + <h2>See also</h2> + + <ol> + <li><a href="http://accessories.android.com/demokit">Android USB Accessory Development + Kit</a></li> + </ol> + </div> + </div> + + <p>USB accessory mode allows users to connect + USB host hardware specifically designed for Android-powered devices. The accessories must adhere + to the Android accessory protocol outlined in the <a href= + "http://accessories.android.com/demokit">Android Accessory Development Kit</a> documentation. + This allows Android-powered devices that cannot act as a USB host to still interact with USB + hardware. When an Android-powered device is in USB accessory mode, the attached Android USB + accessory acts as the host, provides power to the USB bus, and enumerates connected devices. + Android 3.1 (API level 12) supports USB accessory mode and the feature is also backported to + Android 2.3.4 (API level 10) to enable support for a broader range of devices.</p> + + <h2 id="choosing">Choosing the Right USB Accessory APIs</h2> + + <p>Although the USB accessory APIs were introduced to the platform in Android 3.1, they are also + available in Android 2.3.4 using the Google APIs add-on library. Because these APIs were + backported using an external library, there are two packages that you can import to support USB + accessory mode. Depending on what Android-powered devices you want to support, you might have to + use one over the other:</p> + + <ul> + <li><code>com.android.future.usb</code>: To support USB accessory mode in Android 2.3.4, the + <a href="http://code.google.com/android/add-ons/google-apis/index.html">Google APIs add-on + library</a> includes the backported USB accessory APIs and they are contained in this + namespace. Android 3.1 also supports importing and calling the classes within this namespace to + support applications written with the add-on library. This add-on library is a thin wrapper + around the {@link android.hardware.usb} accessory APIs and does not support USB host mode. If + you want to support the widest range of devices that support USB accessory mode, use the add-on + library and import this package. It is important to note that not all Android 2.3.4 devices are + required to support the USB accessory feature. Each individual device manufacturer decides + whether or not to support this capability, which is why you must declare it in your manifest + file.</li> + + <li>{@link android.hardware.usb}: This namespace contains the classes that support USB + accessory mode in Android 3.1. This package is included as part of the framework APIs, so + Android 3.1 supports USB accessory mode without the use of an add-on library. Use this package + if you only care about Android 3.1 or newer devices that have hardware support for USB + accessory mode, which you can declare in your manifest file.</li> + </ul> + + <h3 id="installing">Installing the Google APIs add-on library</h3> + + <p>If you want to install the add-on, you can do so by installing the Google APIs Android API 10 + package with the SDK Manager. See <a href= + "http://code.google.com/android/add-ons/google-apis/installing.html">Installing the Google APIs + Add-on</a> for more information on installing the add-on library.</p> + + <h2 id="api">API Overview</h2> + + <p>Because the add-on library is a wrapper for the framework APIs, the classes that support the + USB accessory feature are similar. You can use the reference documentation for the {@link + android.hardware.usb} even if you are using the add-on library.</p> + + <p class="note"><strong>Note:</strong> There is, however, a minor <a href="#usage">usage + difference</a> between the add-on library and framework APIs that you should be aware of.</p> + + <p>The following table describes the classes that support the USB accessory APIs:</p> + + <table> + <tr> + <th>Class</th> + + <th>Description</th> + </tr> + + <tr> + <td>{@link android.hardware.usb.UsbManager}</td> + + <td>Allows you to enumerate and communicate with connected USB accessories.</td> + </tr> + + <tr> + <td>{@link android.hardware.usb.UsbAccessory}</td> + + <td>Represents a USB accessory and contains methods to access its identifying + information.</td> + </tr> + </table> + + <h3 id="usage">Usage differences between the add-on library and platform APIs</h3> + + <p>There are two usage differences between using the Google APIs add-on library and the platform + APIs.</p> + + <p>If you are using the add-on library, you must obtain the {@link + android.hardware.usb.UsbManager} object in the following manner:</p> + <pre> +UsbManager manager = UsbManager.getInstance(this); +</pre> + + <p>If you are not using the add-on library, you must obtain the {@link + android.hardware.usb.UsbManager} object in the following manner:</p> + <pre> +UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); +</pre> + + <p>When you filter for a connected accessory with an intent filter, the {@link + android.hardware.usb.UsbAccessory} object is contained inside the intent that is passed to your + application. If you are using the add-on library, you must obtain the {@link + android.hardware.usb.UsbAccessory} object in the following manner:</p> + <pre> +UsbAccessory accessory = UsbManager.getAccessory(intent); +</pre> + + <p>If you are not using the add-on library, you must obtain the {@link + android.hardware.usb.UsbAccessory} object in the following manner:</p> + <pre> +UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); +</pre> + + <h2 id="manifest">Android Manifest requirements</h2> + + <p>The following list describes what you need to add to your application's manifest file before + working with the USB accesory APIs. The <a href="#manifest-example">manifest and resource file + examples</a> show how to declare these items:</p> + + <ul> + <li>Because not all Android-powered devices are guaranteed to support the USB accessory APIs, + include a <code><uses-feature></code> element that declares that your application uses + the <code>android.hardware.usb.accessory</code> feature.</li> + + <li>If you are using the <a href="addon">add-on library</a>, add the + <code><uses-library></code> element specifying + <code>com.android.future.usb.accessory</code> for the library.</li> + + <li>Set the minimum SDK of the application to API Level 10 if you are using the add-on library + or 12 if you are using the {@link android.hardware.usb} package.</li> + + <li> + <p>If you want your application to be notified of an attached USB accessory, specify an + <code><intent-filter></code> and <code><meta-data></code> element pair for the + <code>android.hardware.usb.action.USB_ACCESSORY_ATTACHED</code> intent in your main activity. + The <code><meta-data></code> element points to an external XML resource file that + declares identifying information about the accessory that you want to detect.</p> + + <p>In the XML resource file, declare <code><usb-accessory></code> elements for the + accessories that you want to filter. Each <code><usb-accessory></code> can have the + following attributes:</p> + + <ul> + <li><code>manufacturer</code></li> + + <li><code>model</code></li> + + <li><code>version</code></li> + </ul> + + <p>Save the resource file in the <code>res/xml/</code> directory. The resource file name + (without the .xml extension) must be the same as the one you specified in the + <code><meta-data></code> element. The format for the XML resource file is also shown in + the <a href="#example">example</a> below.</p> + </li> + </ul> + + <h3 id="manifest-example">Manifest and resource file examples</h3> + + <p>The following example shows a sample manifest and its corresponding resource file:</p> + <pre> +<manifest ...> + <uses-feature android:name="android.hardware.usb.accessory" /> + <!-- version must be either 10 or 12 --> + <uses-sdk android:minSdkVersion="<<em>version</em>>" /> + ... + <application> + <uses-library android:name="com.android.future.usb.accessory" /> + <activity ...> + ... + <intent-filter> + <action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" /> + </intent-filter> + + <meta-data android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" + android:resource="@xml/accessory_filter" /> + </activity> + </application> +</manifest> +</pre> + + <p>In this case, the following resource file should be saved in + <code>res/xml/accessory_filter.xml</code> and specifies that any accessory that has the + corresponding model, manufacturer, and version should be filtered. The accessory sends these + attributes the Android-powered device:</p> + <pre> +<?xml version="1.0" encoding="utf-8"?> + +<resources> + <usb-accessory model="DemoKit" manufacturer="Google" version="1.0"/> +</resources> +</pre> + + <h2 id="working-a">Working with Accessories</h2> + + <p>When users connect USB accessories to an Android-powered device, the Android system can + determine whether your application is interested in the connected accessory. If so, you can set + up communication with the accessory if desired. To do this, your application has to:</p> + + <ol> + <li>Discover connected accessories by using an intent filter that filters for accessory + attached events or by enumerating connected accessories and finding the appropriate one.</li> + + <li>Ask the user for permission to communicate with the accessory, if not already + obtained.</li> + + <li>Communicate with the accessory by reading and writing data on the appropriate interface + endpoints.</li> + </ol> + + <h3 id="discovering-a">Discovering an accessory</h3> + + <p>Your application can discover accessories by either using an intent filter to be notified when + the user connects an accessory or by enumerating accessories that are already connected. Using an + intent filter is useful if you want to be able to have your application automatically detect a + desired accessory. Enumerating connected accessories is useful if you want to get a list of all + connected accessories or if your application did not filter for an intent.</p> + + <h4 id="discover-a-intent">Using an intent filter</h4> + + <p>To have your application discover a particular USB accessory, you can specify an intent filter + to filter for the <code>android.hardware.usb.action.USB_ACCESSORY_ATTACHED</code> intent. Along + with this intent filter, you need to specify a resource file that specifies properties of the USB + accessory, such as manufacturer, model, and version. When users connect an accessory that matches + your accessory filter,</p> + + <p>The following example shows how to declare the intent filter:</p> + <pre> +<activity ...> + ... + <intent-filter> + <action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" /> + </intent-filter> + + <meta-data android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" + android:resource="@xml/accessory_filter" /> +</activity> +</pre> + + <p>The following example shows how to declare the corresponding resource file that specifies the + USB accessories that you're interested in:</p> + <pre> +<?xml version="1.0" encoding="utf-8"?> + +<resources> + <usb-accessory manufacturer="Google, Inc." model="DemoKit" version="1.0" /> +</resources> +</pre> + + <p>In your activity, you can obtain the {@link android.hardware.usb.UsbAccessory} that represents + the attached accessory from the intent like this (with the add-on library):</p> + <pre> +UsbAccessory accessory = UsbManager.getAccessory(intent); +</pre> + + <p>or like this (with the platform APIs):</p> + <pre> +UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); +</pre> + + <h4 id="discover-a-enumerate">Enumerating accessories</h4> + + <p>You can have your application enumerate accesories that have identified themselves while your + application is running.</p> + + <p>Use the {@link android.hardware.usb.UsbManager#getAccessoryList() getAccessoryList()} method + to get an array all the USB accessories that are connected:</p> + <pre> +UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); +UsbAccessory[] accessoryList = manager.getAcccessoryList(); +</pre> + + <p class="note"><strong>Note:</strong> Currently, only one connected accessory is supported at + one time, but the API is designed to support multiple accessories in the future.</p> + + <h3 id="permission-a">Obtaining permission to communicate with an accessory</h3> + + <p>Before communicating with the USB accessory, your applicaton must have permission from your + users.</p> + + <p class="note"><strong>Note:</strong> If your application <a href="#using-intents">uses an + intent filter</a> to discover accessories as they're connected, it automatically receives + permission if the user allows your application to handle the intent. If not, you must request + permission explicitly in your application before connecting to the accessory.</p> + + <p>Explicitly asking for permission might be neccessary in some situations such as when your + application enumerates accessories that are already connected and then wants to communicate with + one. You must check for permission to access an accessory before trying to communicate with it. + If not, you will receive a runtime error if the user denied permission to access the + accessory.</p> + + <p>To explicitly obtain permission, first create a broadcast receiver. This receiver listens for + the intent that gets broadcast when you call {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()}. The call to {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()} displays a dialog to the + user asking for permission to connect to the accessory. The following sample code shows how to + create the broadcast receiver:</p> + <pre> +private static final String ACTION_USB_PERMISSION = + "com.android.example.USB_PERMISSION"; +private final BroadcastReceiver mUsbReceiver = new BroadcastReceiver() { + + public void onReceive(Context context, Intent intent) { + String action = intent.getAction(); + if (ACTION_USB_PERMISSION.equals(action)) { + synchronized (this) { + UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); + + if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) { + if(accessory != null){ + //call method to set up accessory communication + } + } + else { + Log.d(TAG, "permission denied for accessory " + accessory); + } + } + } + } +}; +</pre> + + <p>To register the broadcast receiver, put this in your <code>onCreate()</code> method in your + activity:</p> + <pre> +UsbManager mUsbManager = (UsbManager) getSystemService(Context.USB_SERVICE); +private static final String ACTION_USB_PERMISSION = + "com.android.example.USB_PERMISSION"; +... +mPermissionIntent = PendingIntent.getBroadcast(this, 0, new Intent(ACTION_USB_PERMISSION), 0); +IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION); +registerReceiver(mUsbReceiver, filter); +</pre> + + <p>To display the dialog that asks users for permission to connect to the accessory, call the + {@link android.hardware.usb.UsbManager#requestPermission requestPermission()} method:</p> + <pre> +UsbAccessory accessory; +... +mUsbManager.requestPermission(accessory, mPermissionIntent); +</pre> + + <p>When users reply to the dialog, your broadcast receiver receives the intent that contains the + {@link android.hardware.usb.UsbManager#EXTRA_PERMISSION_GRANTED} extra, which is a boolean + representing the answer. Check this extra for a value of true before connecting to the + accessory.</p> + + <h3 id="communicating-a">Communicating with an accessory</h3> + + <p>You can communicate with the accessory by using the {@link android.hardware.usb.UsbManager} to + obtain a file descriptor that you can set up input and output streams to read and write data to + descriptor. The streams represent the accessory's input and output bulk endpoints. You should set + up the communication between the device and accessory in another thread, so you don't lock the + main UI thread. The following example shows how to open an accessory to communicate with:</p> + <pre> +UsbAccessory mAccessory; +ParcelFileDescriptor mFileDescriptor; +FileInputStream mInputStream; +FileOutputStream mOutputStream; + +... + +private void openAccessory() { + Log.d(TAG, "openAccessory: " + accessory); + mFileDescriptor = mUsbManager.openAccessory(mAccessory); + if (mFileDescriptor != null) { + FileDescriptor fd = mFileDescriptor.getFileDescriptor(); + mInputStream = new FileInputStream(fd); + mOutputStream = new FileOutputStream(fd); + Thread thread = new Thread(null, this, "AccessoryThread"); + thread.start(); + } +} +</pre> + + <p>In the thread's <code>run()</code> method, you can read and write to the accessory by using + the {@link java.io.FileInputStream} or {@link java.io.FileOutputStream} objects. When reading + data from an accessory with a {@link java.io.FileInputStream} object, ensure that the buffer that + you use is big enough to store the USB packet data. The Android accessory protocol supports + packet buffers up to 16384 bytes, so you can choose to always declare your buffer to be of this + size for simplicity.</p> + + <p class="note"><strong>Note:</strong> At a lower level, the packets are 64 bytes for USB + full-speed accessories and 512 bytes for USB high-speed accessories. The Android accessory + protocol bundles the packets together for both speeds into one logical packet for simplicity.</p> + + <p>For more information about using threads in Android, see <a href= + "{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes and + Threads</a>.</p> + + <h3 id="terminating-a">Terminating communication with an accessory</h3> + + <p>When you are done communicating with an accessory or if the accessory was detached, close the + file descriptor that you opened by calling {@link android.os.ParcelFileDescriptor#close close()}. + To listen for detached events, create a broadcast receiver like below:</p> + <pre> +BroadcastReceiver mUsbReceiver = new BroadcastReceiver() { + public void onReceive(Context context, Intent intent) { + String action = intent.getAction(); + + if (UsbManager.ACTION_USB_ACCESSORY_DETACHED.equals(action)) { + UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); + if (accessory != null) { + // call your method that cleans up and closes communication with the accessory + } + } + } +}; +</pre> + + <p>Creating the broadcast receiver within the application, and not the manifest, allows your + application to only handle detached events while it is running. This way, detached events are + only sent to the application that is currently running and not broadcast to all applications.</p> + diff --git a/docs/html/guide/topics/usb/host.jd b/docs/html/guide/topics/usb/host.jd new file mode 100644 index 0000000..942708d --- /dev/null +++ b/docs/html/guide/topics/usb/host.jd @@ -0,0 +1,443 @@ +page.title=USB Host +@jd:body + + <div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li><a href="#api">API Overview</a></li> + + <li><a href="#usage">Android Manifest Requirements</a></li> + + <li> + <a href="#working-d">Working with devices</a> + + <ol> + <li><a href="#discovering-d">Discovering a device</a></li> + + <li><a href="#permission-d">Obtaining permission to communicate with a device</a></li> + + <li><a href="#communicating-d">Communicating with a device</a></li> + + <li><a href="#terminating-d">Terminating communication with a device</a></li> + </ol> + </li> + </ol> + + <h2>Related Samples</h2> + + <ol> + <li><a href="{@docRoot}resources/samples/USB/AdbTest/index.html">AdbTest</a></li> + + <li><a href= + "{@docRoot}resources/samples/USB/MissileLauncher/index.html">MissleLauncher</a></li> + </ol> + </div> + </div> + + <p>When your Android-powered device is in USB host mode, it acts as the USB host, powers the bus, + and enumerates connected USB devices. USB host mode is supported in Android 3.1 and higher.</p> + + <h2 id="api">API Overview</h2> + + <p>Before you begin, it is important to understand the classes that you need to work with. The + following table describes the USB host APIs in the {@link android.hardware.usb} package.</p> + + <p class="table-caption"><strong>Table 1.</strong> USB Host APIs</p> + + <table> + <tr> + <th>Class</th> + + <th>Description</th> + </tr> + + <tr> + <td>{@link android.hardware.usb.UsbManager}</td> + + <td>Allows you to enumerate and communicate with connected USB devices.</td> + </tr> + + <tr> + <td>{@link android.hardware.usb.UsbDevice}</td> + + <td>Represents a connected USB device and contains methods to access its identifying + information, interfaces, and endpoints.</td> + </tr> + + <tr> + <td>{@link android.hardware.usb.UsbInterface}</td> + + <td>Represents an interface of a USB device, which defines a set of functionality for the + device. A device can have one or more interfaces on which to communicate on.</td> + </tr> + + <tr> + <td>{@link android.hardware.usb.UsbEndpoint}</td> + + <td>Represents an interface endpoint, which is a communication channel for this interface. An + interface can have one or more endpoints, and usually has input and output endpoints for + two-way communication with the device.</td> + </tr> + + <tr> + <td>{@link android.hardware.usb.UsbDeviceConnection}</td> + + <td>Represents a connection to the device, which transfers data on endpoints. This class + allows you to send data back and forth sychronously or asynchronously.</td> + </tr> + + <tr> + <td>{@link android.hardware.usb.UsbRequest}</td> + + <td>Represents an asynchronous request to communicate with a device through a {@link + android.hardware.usb.UsbDeviceConnection}.</td> + </tr> + + <tr> + <td>{@link android.hardware.usb.UsbConstants}</td> + + <td>Defines USB constants that correspond to definitions in linux/usb/ch9.h of the Linux + kernel.</td> + </tr> + </table> + + <p>In most situations, you need to use all of these classes ({@link + android.hardware.usb.UsbRequest} is only required if you are doing asynchronous communication) + when communicating with a USB device. In general, you obtain a {@link + android.hardware.usb.UsbManager} to retrieve the desired {@link android.hardware.usb.UsbDevice}. + When you have the device, you need to find the appropriate {@link + android.hardware.usb.UsbInterface} and the {@link android.hardware.usb.UsbEndpoint} of that + interface to communicate on. Once you obtain the correct endpoint, open a {@link + android.hardware.usb.UsbDeviceConnection} to communicate with the USB device.</p> + + <h2 id="manifest">Android Manifest Requirements</h2> + + <p>The following list describes what you need to add to your application's manifest file before + working with the USB host APIs:</p> + + <ul> + <li>Because not all Android-powered devices are guaranteed to support the USB host APIs, + include a <code><uses-feature></code> element that declares that your application uses + the <code>android.hardware.usb.host</code> feature.</li> + + <li>Set the minimum SDK of the application to API Level 12 or higher. The USB host APIs are not + present on earlier API levels.</li> + + <li>If you want your application to be notified of an attached USB device, specify an + <code><intent-filter></code> and <code><meta-data></code> element pair for the + <code>android.hardware.usb.action.USB_DEVICE_ATTACHED</code> intent in your main activity. The + <code><meta-data></code> element points to an external XML resource file that declares + identifying information about the device that you want to detect. + + <p>In the XML resource file, declare <code><usb-device></code> elements for the USB + devices that you want to filter. The following list describes the attributes of + <code><usb-device></code>. In general, use vendor and product ID if you want to filter + for a specific device and use class, subclass, and protocol if you want to filter for a group + of USB devices, such as mass storage devices or digital cameras.</p> + + <ul> + <li><code>vendor-id</code></li> + + <li><code>product-id</code></li> + + <li><code>class</code></li> + + <li><code>subclass</code></li> + + <li><code>protocol</code> (device or interface)</li> + </ul> + + <p>Save the resource file in the <code>res/xml/</code> directory. The resource file name + (without the .xml extension) must be the same as the one you specified in the + <code><meta-data></code> element. The format for the XML resource file is in the + <a href="#example">example</a> below.</p> + </li> + </ul> + + <h3 id="manifest-example">Manifest and resource file examples</h3> + + <p>The following example shows a sample manifest and its corresponding resource file:</p> + <pre> +<manifest ...> + <uses-feature android:name="android.hardware.usb.host" /> + <uses-sdk android:minSdkVersion="12" /> + ... + <application> + <activity ...> + ... + <intent-filter> + <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" /> + </intent-filter> + + <meta-data android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" + android:resource="@xml/device_filter" /> + </activity> + </application> +</manifest> +</pre> + + <p>In this case, the following resource file should be saved in + <code>res/xml/device_filter.xml</code> and specifies that any USB device with the corresponding + vendor ID and product ID should be filtered. These IDs are specific to the device and are + specified by the device's manufacturer:</p> + <pre> +<?xml version="1.0" encoding="utf-8"?> + +<resources> + <usb-device vendor-id="1234" product-id="5678" /> +</resources> +</pre> + + <h2 id="working-d">Working with Devices</h2> + + <p>When users connect USB devices to an Android-powered device, the Android system can determine + whether your application is interested in the connected device. If so, you can set up + communication with the device if desired. To do this, your application has to:</p> + + <ol> + <li>Discover connected USB devices by using an intent filter to be notified when the user + connects a USB device or by enumerating USB devices that are already connected.</li> + + <li>Ask the user for permission to connect to the USB device, if not already obtained.</li> + + <li>Communicate with the USB device by reading and writing data on the appropriate interface + endpoints.</li> + </ol> + + <h3 id="discovering-d">Discovering a device</h3> + + <p>Your application can discover USB devices by either using an intent filter to be notified when + the user connects a device or by enumerating USB devices that are already connected. Using an + intent filter is useful if you want to be able to have your application automatically detect a + desired device. Enumerating connected USB devices is useful if you want to get a list of all + connected devices or if your application did not filter for an intent.</p> + + <h4 id="using-intents">Using an intent filter</h4> + + <p>To have your application discover a particular USB device, you can specify an intent filter to + filter for the <code>android.hardware.usb.action.USB_DEVICE_ATTACHED</code> intent. Along with + this intent filter, you need to specify a resource file that specifies properties of the USB + device, such as product and vendor ID. When users connect a device that matches your device + filter, the system presents them with a dialog that asks if they want to start your application. + If users accept, your application automatically has permission to access the device until the + device is disconnected.</p> + + <p>The following example shows how to declare the intent filter:</p> + <pre> +<activity ...> +... + <intent-filter> + <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" /> + </intent-filter> + + <meta-data android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" + android:resource="@xml/device_filter" /> +</activity> +</pre> + + <p>The following example shows how to declare the corresponding resource file that specifies the + USB devices that you're interested in:</p> + <pre> +<?xml version="1.0" encoding="utf-8"?> + +<resources> + <usb-device vendor-id="1234" product-id="5678" /> +</resources> +</pre><!-- REMEMBER TO ADD PROTOCOL, and device class and subclass, if applicable --> + + <p>In your activity, you can obtain the {@link android.hardware.usb.UsbDevice} that represents + the attached device from the intent like this:</p> + <pre> +UsbDevice device = (UsbDevice) intent.getParcelableExtra(UsbManager.EXTRA_DEVICE); +</pre> + + <h4>Enumerating devices</h4> + + <p>If your application is interested in inspecting all of the USB devices currently connected + while your application is running, it can enumerate devices on the bus. Use the {@link + android.hardware.usb.UsbManager#getDeviceList() getDeviceList()} method to get a hash map of all + the USB devices that are connected. The hash map is keyed by the USB device's name if you want to + obtain a device from the map.</p> + <pre> +UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); +... +HashMap<String, UsbDevice> deviceList = manager.getDeviceList(); +Iterator<UsbDevice> deviceIterator = deviceList.values().iterator(); +while(deviceIterator.hasNext()){ + UsbDevice device = deviceIterator.next(); + // your code +} +</pre> + + <p>If desired, you can also just obtain an iterator from the hash map and process each device one + by one:</p> + <pre> +UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); +... +HashMap<String, UsbDevice> deviceList = manager.getDeviceList(); +Iterator<UsbDevice> deviceIterator = deviceList.values().iterator(); +while(deviceIterator.hasNext()){ + UsbDevice device = deviceIterator.next() + //your code +} +</pre> + + <h3 id="permission-d">Obtaining permission to communicate with a device</h3> + + <p>Before communicating with the USB device, your applicaton must have permission from your + users.</p> + + <p class="note"><strong>Note:</strong> If your application <a href="#using-intents">uses an + intent filter</a> to discover USB devices as they're connected, it automatically receives + permission if the user allows your application to handle the intent. If not, you must request + permission explicitly in your application before connecting to the device.</p> + + <p>Explicitly asking for permission might be neccessary in some situations such as when your + application enumerates USB devices that are already connected and then wants to communicate with + one. You must check for permission to access a device before trying to communicate with it. If + not, you will receive a runtime error if the user denied permission to access the device.</p> + + <p>To explicitly obtain permission, first create a broadcast receiver. This receiver listens for + the intent that gets broadcast when you call {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()}. The call to {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()} displays a dialog to the + user asking for permission to connect to the device. The following sample code shows how to + create the broadcast receiver:</p> + <pre> +private static final String ACTION_USB_PERMISSION = + "com.android.example.USB_PERMISSION"; +private final BroadcastReceiver mUsbReceiver = new BroadcastReceiver() { + + public void onReceive(Context context, Intent intent) { + String action = intent.getAction(); + if (ACTION_USB_PERMISSION.equals(action)) { + synchronized (this) { + UsbDevice device = (UsbDevice)intent.getParcelableExtra(UsbManager.EXTRA_DEVICE); + + if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) { + if(device != null){ + //call method to set up device communication + } + } + else { + Log.d(TAG, "permission denied for device " + device); + } + } + } + } +}; +</pre> + + <p>To register the broadcast receiver, add this in your <code>onCreate()</code> method in your + activity:</p> + <pre> +UsbManager mUsbManager = (UsbManager) getSystemService(Context.USB_SERVICE); +private static final String ACTION_USB_PERMISSION = + "com.android.example.USB_PERMISSION"; +... +mPermissionIntent = PendingIntent.getBroadcast(this, 0, new Intent(ACTION_USB_PERMISSION), 0); +IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION); +registerReceiver(mUsbReceiver, filter); +</pre> + + <p>To display the dialog that asks users for permission to connect to the device, call the {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()} method:</p> + <pre> +UsbDevice device; +... +mUsbManager.requestPermission(device, mPermissionIntent); +</pre> + + <p>When users reply to the dialog, your broadcast receiver receives the intent that contains the + {@link android.hardware.usb.UsbManager#EXTRA_PERMISSION_GRANTED} extra, which is a boolean + representing the answer. Check this extra for a value of true before connecting to the + device.</p> + + <h3 id="communicating-d">Communicating with a device</h3> + + <p>Communication with a USB device can be either synchronous or asynchronous. In either case, you + should create a new thread on which to carry out all data transmissions, so you don't block the + UI thread. To properly set up communication with a device, you need to obtain the appropriate + {@link android.hardware.usb.UsbInterface} and {@link android.hardware.usb.UsbEndpoint} of the + device that you want to communicate on and send requests on this endpoint with a {@link + android.hardware.usb.UsbDeviceConnection}. In general, your code should:</p> + + <ul> + <li>Check a {@link android.hardware.usb.UsbDevice} object's attributes, such as product ID, + vendor ID, or device class to figure out whether or not you want to communicate with the + device.</li> + + <li>When you are certain that you want to communicate with the device, find the appropriate + {@link android.hardware.usb.UsbInterface} that you want to use to communicate along with the + appropriate {@link android.hardware.usb.UsbEndpoint} of that interface. Interfaces can have one + or more endpoints, and commonly will have an input and output endpoint for two-way + communication.</li> + + <li>When you find the correct endpoint, open a {@link android.hardware.usb.UsbDeviceConnection} + on that endpoint.</li> + + <li>Supply the data that you want to transmit on the endpoint with the {@link + android.hardware.usb.UsbDeviceConnection#bulkTransfer bulkTransfer()} or {@link + android.hardware.usb.UsbDeviceConnection#controlTransfer controlTransfer()} method. You should + carry out this step in another thread to prevent blocking the main UI thread. For more + information about using threads in Android, see <a href= + "{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes and + Threads</a>.</li> + </ul> + + <p>The following code snippet is a trivial way to do a synchronous data transfer. Your code + should have more logic to correctly find the correct interface and endpoints to communicate on + and also should do any transferring of data in a different thread than the main UI thread:</p> + <pre> +private Byte[] bytes +private static int TIMEOUT = 0; +private boolean forceClaim = true; + +... + +UsbInterface intf = device.getInterface(0); +UsbEndpoint endpoint = intf.getEndpoint(0); +UsbDeviceConnection connection = mUsbManager.openDevice(device); +connection.claimInterface(intf, forceClaim); +connection.bulkTransfer(endpoint, bytes, bytes.length, TIMEOUT); //do in another thread +</pre> + + <p>To send data asynchronously, use the {@link android.hardware.usb.UsbRequest} class to {@link + android.hardware.usb.UsbRequest#initialize initialize} and {@link + android.hardware.usb.UsbRequest#queue queue} an asynchronous request, then wait for the result + with {@link android.hardware.usb.UsbDeviceConnection#requestWait requestWait()}.</p> + + <p>For more information, see the <a href= + "{@docRoot}resources/samples/USB/AdbTest/index.html">AdbTest sample</a>, which shows how to do + asynchronous bulk transfers, and the <a href= + "{@docRoot}resources/samples/USB/MissileLauncher/index.html">MissleLauncher sample</a>, which + shows how to listen on an interrupt endpoint asynchronously.</p> + + <h3 id="terminating-d">Terminating communication with a device</h3> + + <p>When you are done communicating with a device or if the device was detached, close the {@link + android.hardware.usb.UsbInterface} and {@link android.hardware.usb.UsbDeviceConnection} by + calling {@link android.hardware.usb.UsbDeviceConnection#releaseInterface releaseInterface()} and + {@link android.hardware.usb.UsbDeviceConnection#close() close()}. To listen for detached events, + create a broadcast receiver like below:</p> + <pre> +BroadcastReceiver mUsbReceiver = new BroadcastReceiver() { + public void onReceive(Context context, Intent intent) { + String action = intent.getAction(); + + if (UsbManager.ACTION_USB_DEVICE_DETACHED.equals(action)) { + UsbDevice device = (UsbDevice)intent.getParcelableExtra(UsbManager.EXTRA_DEVICE); + if (device != null) { + // call your method that cleans up and closes communication with the device + } + } + } +}; +</pre> + + <p>Creating the broadcast receiver within the application, and not the manifest, allows your + application to only handle detached events while it is running. This way, detached events are + only sent to the application that is currently running and not broadcast to all applications.</p> + diff --git a/docs/html/guide/topics/usb/index.jd b/docs/html/guide/topics/usb/index.jd new file mode 100644 index 0000000..18af06a --- /dev/null +++ b/docs/html/guide/topics/usb/index.jd @@ -0,0 +1,67 @@ +page.title=USB Host and Accessory +@jd:body + + <div id="qv-wrapper"> + <div id="qv"> + <h2>Topics</h2> + + <ol> + <li><a href="{@docRoot}/guide/topics/USB/accessory.jd">USB Accessory</a></li> + + <li><a href="{@docRoot}/guide/topics/USB/host.jd">USB Host</a></li> + </ol> + </div> + </div> + + <p>Android supports a variety of USB peripherals and Android USB accessories (hardware that + implements the Android accessory protocol) through two modes: USB accessory and USB host. In USB + accessory mode, the external USB hardware act as the USB hosts. Examples of accessories might + include robotics controllers; docking stations; diagnostic and musical equipment; kiosks; card + readers; and much more. This gives Android-powered devices that do not have host capabilities the + ability to interact with USB hardware. Android USB accessories must be designed to work with + Android-powered devices and must adhere to the <a href= + "http://accessories.android.com/demokit">Android accessory communication protocol</a>. In USB + host mode, the Android-powered device acts as the host. Examples of devices include digital + cameras, keyboards, mice, and game controllers. USB devices that are designed for a wide range of + applications and environments can still interact with Android applications that can correctly + communicate with the device.</p> + + <p>Figure 1 shows the differences between the two modes. When the Android-powered device is in + host mode, it acts as the USB host and powers the bus. When the Android-powered device is in USB + accessory mode, the connected USB hardware (an Android USB accessory in this case) acts as the + host and powers the bus.</p><img src="{@docRoot}images/usb-host-accessory.png" alt=""> + + <p class="img-caption"><strong>Figure 1.</strong> USB Host and Accessory Modes</p> + + <p>USB accessory and host modes are directly supported in Android 3.1 (API level 12) or newer + platforms. USB accessory mode is also backported to Android 2.3.4 (API level 10) as an add-on + library to support a broader range of devices. Device manufacturers can choose whether or not to + include the add-on library on the device's system image.</p> + + <p class="note"><strong>Note:</strong> Support for USB host and accessory modes are ultimately + dependant on the device's hardware, regardless of platform level. You can filter for devices that + support USB host and accessory through a <a href= + "{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> element. See + the USB <a href="{@docRoot}guide/topics/USB/accessory.html">accessory</a> and <a href= + "{@docRoot}guide/topics/USB/host.html">host</a> documentation for more details.</p> + + <h2>Debugging considerations</h2> + + <p>When debugging applications that use USB accessory or host features, you most likely will have + USB hardware connected to your Android-powered device. This will prevent you from having an + <code>adb</code> connection to the Android-powered device via USB. You can still access + <code>adb</code> over a network connection. To enable <code>adb</code> over a network + connection:</p> + + <ol> + <li>Connect the Android-powered device via USB to your computer.</li> + + <li>From your SDK <code>platform-tools/</code> directory, enter <code>adb tcpip 5555</code> at + the command prompt.</li> + + <li>Enter <code>adb connect <device-ip-address>:5555</code> You should now be connected + to the Android-powered device and can issue the usual <code>adb</code> commands like <code>adb + logcat</code>.</li> + + <li>To set your device to listen on USB, enter <code>adb usb</code>.</li> + </ol> diff --git a/docs/html/images/admin/device-admin-activate-prompt.png b/docs/html/images/admin/device-admin-activate-prompt.png Binary files differindex fd001bd..2851194 100755..100644 --- a/docs/html/images/admin/device-admin-activate-prompt.png +++ b/docs/html/images/admin/device-admin-activate-prompt.png diff --git a/docs/html/images/admin/device-admin-app.png b/docs/html/images/admin/device-admin-app.png Binary files differindex d966a28..c96defc 100755..100644 --- a/docs/html/images/admin/device-admin-app.png +++ b/docs/html/images/admin/device-admin-app.png diff --git a/docs/html/images/usb-host-accessory.png b/docs/html/images/usb-host-accessory.png Binary files differnew file mode 100644 index 0000000..f82fd6f --- /dev/null +++ b/docs/html/images/usb-host-accessory.png diff --git a/docs/html/index.jd b/docs/html/index.jd index 78f71ac..d5f19a1 100644 --- a/docs/html/index.jd +++ b/docs/html/index.jd @@ -129,17 +129,20 @@ href="{@docRoot}resources/dashboard/platform-versions.html">Learn more »</ 'sdk': { 'layout':"imgLeft", 'icon':"sdk-small.png", - 'name':"Android 3.0", + 'name':"Android 3.1", 'img':"honeycomb-android.png", - 'title':"Android 3.0 is here!", - 'desc': "<p>Android 3.0 is now available for the Android SDK. It offers a redesigned UI and " -+ "all new developer APIs for an optimized experience on tablets and similar devices. " -+ "For more information about what's in Android 3.0, read the " -+ "<a href='{@docRoot}sdk/android-3.0.html'>version notes</a>.</p>" + 'title':"Android 3.1 now available!", + 'desc': "<p>Android 3.1 includes new developer features such as APIs for USB " ++ "accessories, MTP/PTP, and RTP, as well as new input events from mice, trackballs, joysticks, " ++ "and more.</p>" ++ "<p>For more information about all the new APIs in Android 3.1, read the " ++ "<a href='{@docRoot}sdk/android-3.1.html'>version notes</a>.</p>" +/* + "<p>If you have an existing SDK, add Android 3.0 as an " + "<a href='{@docRoot}sdk/adding-components.html'>SDK " + "component</a>. If you're new to Android, install the " + "<a href='{@docRoot}sdk/index.html'>SDK starter package</a>." +*/ }, 'tv': { @@ -152,8 +155,7 @@ href="{@docRoot}resources/dashboard/platform-versions.html">Learn more »</ + "for television built on Android. Google " + "has partnered with Sony and Logitech to integrate " + "this platform into TVs, blu-ray players, and companion " - + "boxes. An add-on for the Android SDK will be " - + "available early next year. </p>" + + "boxes. </p>" + "<p><a href='http://www.google.com/tv/'>Learn more about " + "Google TV »</a></p>" }, diff --git a/docs/html/resources/dashboard/opengl.jd b/docs/html/resources/dashboard/opengl.jd new file mode 100644 index 0000000..dac8ce5 --- /dev/null +++ b/docs/html/resources/dashboard/opengl.jd @@ -0,0 +1,79 @@ +page.title=OpenGL ES Versions +@jd:body + +<style type="text/css"> + +div.dashboard-panel { + max-width:1000px; + margin:0 0 2em 0; + padding:20px 20px 0 20px; + border:1px solid #d3ecf5; + border-radius:7px; + -moz-border-radius:7px; + -webkit-border-radius:7px; + background-color: #DAF3FC; + box-shadow:2px 3px 1px #eee; + -moz-box-shadow:2px 3px 1px #eee; + -webkit-box-shadow:2px 3px 1px #eee; + overflow:hidden; +} +#jd-content div.dashboard-panel img { + margin:0 20px 20px 0; + padding:0; + border:1px solid #ccc; + float:left; +} +#jd-content div.dashboard-panel table { + margin:0 0 20px 0; + float:left; + background-color:#fff; +} +div.dashboard-panel p { + clear:left; +} +div.dashboard-panel th { + white-space:nowrap; +} +</style> + +<p>This page provides data about the relative number of active devices that support a particular +version of OpenGL ES. Note that support for one particular version of OpenGL ES also implies +support for any lower version (for example, support for version 2.0 also implies support for +1.1).</p> + +<p>To declare which version of OpenGL ES your application requires, you should use the {@code +android:glEsVersion} attribute of the <a +href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +element. You can also use the <a +href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code +<supports-gl-texture>}</a> element to declare the GL compression formats that your application +uses.</p> + +<p class="note"><strong>Note:</strong> This data is based on the number +of Android devices that have accessed Android Market within a 7-day period +ending on the data collection date noted below.</p> + + +<div class="dashboard-panel"> + +<img alt="" width="400" height="250" +src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=GL%20ES%201.1|GL%20ES%202.0&chd=t%3A8.9,91.1" /> + +<table> +<tr> +<th scope="col">OpenGL ES Version</th> +<th scope="col">Distribution</th> +</tr> +<tr> +<td>1.1</th> +<td>8.9%</td> +</tr> +<tr> +<td>2.0</th> +<td>91.1%</td> +</tr> +</table> + +<p><em>Data collected during a 7-day period ending on May 6, 2011</em></p> +</div> + diff --git a/docs/html/resources/dashboard/platform-versions.jd b/docs/html/resources/dashboard/platform-versions.jd index 5d7b651..368164d 100644 --- a/docs/html/resources/dashboard/platform-versions.jd +++ b/docs/html/resources/dashboard/platform-versions.jd @@ -52,7 +52,7 @@ Android Market within a 14-day period ending on the data collection date noted b <div class="dashboard-panel"> <img alt="" height="250" width="460" -src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:2.7,3.5,27.2,63.9,0.8,1.7,0.2&chl=Android%201.5|Android%201.6|Android%202.1|Android%202.2|Android%202.3|Android%202.3.3|Android%203.0&chco=c4df9b,6fad0c" /> +src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:2.3,3.0,24.5,65.9,1.0,3.0,0.3&chl=Android%201.5|Android%201.6|Android%202.1|Android%202.2|Android%202.3|Android%202.3.3|Android%203.0&chco=c4df9b,6fad0c" /> <table> <tr> @@ -60,16 +60,16 @@ src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:2.7,3.5,27.2,63 <th>API Level</th> <th>Distribution</th> </tr> -<tr><td>Android 1.5</td><td>3</td><td>2.7%</td></tr> -<tr><td>Android 1.6</td><td>4</td><td>3.5%</td></tr> -<tr><td>Android 2.1</td><td>7</td><td>27.2%</td></tr> -<tr><td>Android 2.2</td><td>8</td><td>63.9%</td></tr> -<tr><td>Android 2.3</td><td>9</td><td>0.8%</td></tr> -<tr><td>Android 2.3.3</td><td>10</td><td>1.7%</td></tr> -<tr><td>Android 3.0</td><td>11</td><td>0.2%</td></tr> +<tr><td>Android 1.5</td><td>3</td><td>2.3%</td></tr> +<tr><td>Android 1.6</td><td>4</td><td>3.0%</td></tr> +<tr><td>Android 2.1</td><td>7</td><td>24.5%</td></tr> +<tr><td>Android 2.2</td><td>8</td><td>65.9%</td></tr> +<tr><td>Android 2.3</td><td>9</td><td>1.0%</td></tr> +<tr><td>Android 2.3.3</td><td>10</td><td>3.0%</td></tr> +<tr><td>Android 3.0</td><td>11</td><td>0.3%</td></tr> </table> -<p><em>Data collected during two weeks ending on April 1, 2011</em></p> +<p><em>Data collected during two weeks ending on May 2, 2011</em></p> <!-- <p style="font-size:.9em">* <em>Other: 0.1% of devices running obsolete versions</em></p> --> @@ -98,9 +98,9 @@ Android Market within a 14-day period ending on the date indicated on the x-axis <div class="dashboard-panel"> <img alt="" height="250" width="660" style="padding:5px;background:#fff" -src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,x,y,r&chxr=0,0,12|1,0,12|2,0,100|3,0,100&chxl=0%3A%7C10/01%7C10/15%7C11/01%7C11/15%7C12/01%7C12/15%7C01/01%7C01/15%7C02/01%7C02/15%7C03/01%7C03/15%7C04/01%7C1%3A%7C2010%7C%7C%7C%7C%7C%7C2011%7C%7C%7C%7C%7C%7C2011%7C2%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C3%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:99.9,99.9,100.0,99.9,99.8,99.7,100.0,99.9,99.9,99.9,100.0,99.8,99.7|90.2,91.1,92.0,92.7,93.4,94.1,95.2,95.6,96.0,96.3,96.7,96.8,97.0|73.8,75.3,77.4,79.6,82.2,84.4,87.2,88.3,89.7,90.5,91.5,92.0,93.5|33.4,34.5,37.1,40.5,44.3,47.7,51.8,54.3,58.3,59.7,61.5,63.0,66.3|0.0,0.0,0.0,0.0,0.0,0.0,0.4,0.6,0.7,0.8,1.1,1.7,2.5|0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,1.0,1.7&chm=b,c3df9b,0,1,0|tAndroid 1.6,689326,1,0,15,,t::-5|b,b4db77,1,2,0|tAndroid 2.1,547a19,2,0,15,,t::-5|b,a5db51,2,3,0|tAndroid 2.2,3f5e0e,3,0,15,,t::-5|b,96dd28,3,4,0|b,83c916,4,5,0|B,6fad0c,5,6,0&chg=7,25&chdl=Android 1.5|Android 1.6|Android 2.1|Android 2.2|Android 2.3|Android 2.3.3&chco=add274,9dd14f,8ece2a,7ab61c,659b11,507d08" /> +src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,x,y,r&chxr=0,0,12|1,0,12|2,0,100|3,0,100&chxl=0%3A%7C11/01%7C11/15%7C12/01%7C12/15%7C01/01%7C01/15%7C02/01%7C02/15%7C03/01%7C03/15%7C04/01%7C04/15%7C05/01%7C1%3A%7C2010%7C%7C%7C%7C2011%7C%7C%7C%7C%7C%7C%7C%7C2011%7C2%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C3%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:100.0,99.9,99.8,99.7,100.0,99.9,99.9,99.9,100.0,99.8,99.7,99.6,99.6|92.0,92.7,93.4,94.1,95.2,95.6,96.0,96.3,96.7,96.8,97.0,97.1,97.3|77.4,79.6,82.2,84.4,87.2,88.3,89.7,90.5,91.5,92.0,93.5,93.9,94.3|37.1,40.5,44.3,47.7,51.8,54.3,58.3,59.7,61.5,63.0,66.4,68.0,69.8|0.0,0.0,0.0,0.0,0.4,0.6,0.7,0.8,1.1,1.7,2.5,3.1,4.0|0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,1.0,1.7,2.2,3.0&chm=b,c3df9b,0,1,0|tAndroid 1.6,689326,1,0,15,,t::-5|b,b4db77,1,2,0|tAndroid 2.1,547a19,2,0,15,,t::-5|b,a5db51,2,3,0|tAndroid 2.2,3f5e0e,3,0,15,,t::-5|b,96dd28,3,4,0|b,83c916,4,5,0|B,6fad0c,5,6,0&chg=7,25&chdl=Android 1.5|Android 1.6|Android 2.1|Android 2.2|Android 2.3|Android 2.3.3&chco=add274,9dd14f,8ece2a,7ab61c,659b11,507d08" /> -<p><em>Last historical dataset collected during two weeks ending on April 1, 2011</em></p> +<p><em>Last historical dataset collected during two weeks ending on May 2, 2011</em></p> </div><!-- end dashboard-panel --> diff --git a/docs/html/resources/dashboard/screens.jd b/docs/html/resources/dashboard/screens.jd index 90f3f1a..bdaae0d 100644 --- a/docs/html/resources/dashboard/screens.jd +++ b/docs/html/resources/dashboard/screens.jd @@ -36,46 +36,66 @@ div.dashboard-panel th { } </style> -<p>This page provides data about the relative number of active devices -using a particular type of screen, including the screen size and density. For information about how -your application can support multiple screen types, see <a -href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p> +<p> This page provides data about the relative number of active devices that have a particular +screen configuration, defined by a combination of screen size and density. To simplify the way that +you design your user interfaces for different screen configurations, Android divides the range of +actual screen sizes and densities into:</p> + +<ul> +<li>A set of four generalized <strong>sizes</strong>: <em>small</em>, <em>normal</em>, +<em>large</em>, and <em>xlarge</em></em></li> +<li>A set of four generalized <strong>densities</strong>: <em>ldpi</em> (low), <em>mdpi</em> +(medium), <em>hdpi</em> (high), and <em>xhdpi</em> (extra high)</li> +</ul> + +<p>For information about how you can support multiple screen configurations in your +application, see <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple +Screens</a>.</p> <p class="note"><strong>Note:</strong> This data is based on the number -of Android devices that have accessed Android Market within a 14-day period +of Android devices that have accessed Android Market within a 7-day period ending on the data collection date noted below.</p> <div class="dashboard-panel"> -<img alt="" width="460" height="250" -src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:2.3,0.4,45.9,51.2&chl=Small%20/% -20ldpi|Normal%20/%20ldpi|Normal%20/%20mdpi|Normal%20/%20hdpi&chco=c4df9b,6fad0c" /> +<img alt="" width="400" height="250" +src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=xlarge%20/%20mdpi|large%20/%20mdpi|normal%20/%20hdpi|normal%20/%20ldpi|normal%20/%20mdpi|small%20/%20hdpi&chd=t%3A0.5,2.6,75.5,1.2,17.1,3.2" /> <table> <tr> <th></th> -<th scope="col">Low Density</th> -<th scope="col">Medium Density</th> -<th scope="col">High Density</th> +<th scope="col">ldpi</th> +<th scope="col">mdpi</th> +<th scope="col">hdpi</th> +<th scope="col">xhdpi</th> </tr> -<tr><th scope="row">Small</th> -<td class='cent hi'>2.3%</td> -<td></td> -<td></td> +<tr><th scope="row">small</th> +<td></td> <!-- ldpi --> +<td></td> <!-- mdpi --> +<td>3.2%</td> <!-- hdpi --> +<td></td> <!-- xhdpi --> +</tr> +<tr><th scope="row">normal</th> +<td>1.2%</td> <!-- ldpi --> +<td>17.1%</td> <!-- mdpi --> +<td>75.5%</td> <!-- hdpi --> +<td></td> <!-- xhdpi --> </tr> -<tr><th scope="row">Normal</th> -<td class='cent '>0.4%</td> -<td class='cent hi'>45.9%</td> -<td class='cent hi'>51.2%</td> +<tr><th scope="row">large</th> +<td></td> <!-- ldpi --> +<td>2.6%</td> <!-- mdpi --> +<td></td> <!-- hdpi --> +<td></td> <!-- xhdpi --> </tr> -<tr><th scope="row">Large</th> -<td></td> -<td></td> -<td></td> +<tr><th scope="row">xlarge</th> +<td></td> <!-- ldpi --> +<td>0.5%</td> <!-- mdpi --> +<td></td> <!-- hdpi --> +<td></td> <!-- xhdpi --> </tr> </table> -<p><em>Data collected during two weeks ending on August 2, 2010</em></p> +<p><em>Data collected during a 7-day period ending on May 6, 2011</em></p> </div> diff --git a/docs/html/resources/resources-data.js b/docs/html/resources/resources-data.js index 14118bb..03a5c02 100644 --- a/docs/html/resources/resources-data.js +++ b/docs/html/resources/resources-data.js @@ -606,6 +606,16 @@ var ANDROID_RESOURCES = [ } }, { + tags: ['sample', 'new', 'newfeature'], + path: 'samples/USB/index.html', + title: { + en: 'USB' + }, + description: { + en: 'A set of samples that demonstrate how to use various features of the USB APIs.' + } + }, + { tags: ['sample', 'ui', 'widgets'], path: 'samples/Wiktionary/index.html', title: { diff --git a/docs/html/resources/resources_toc.cs b/docs/html/resources/resources_toc.cs index a2580a6..c7dd916 100644 --- a/docs/html/resources/resources_toc.cs +++ b/docs/html/resources/resources_toc.cs @@ -81,6 +81,9 @@ <li><a href="<?cs var:toroot ?>resources/dashboard/screens.html"> <span class="en">Screen Sizes & Densities</span> </a></li> + <li><a href="<?cs var:toroot ?>resources/dashboard/opengl.html"> + <span class="en">OpenGL ES Versions</span> + </a></li> </ul> </li><?cs /if diff --git a/docs/html/sdk/index.jd b/docs/html/sdk/index.jd index 7f6f0105..7c1c86d 100644 --- a/docs/html/sdk/index.jd +++ b/docs/html/sdk/index.jd @@ -1,21 +1,21 @@ page.title=Android SDK sdk.redirect=0 -sdk.win_installer=installer_r10-windows.exe -sdk.win_installer_bytes=32878481 -sdk.win_installer_checksum=8ffa2dd734829d0bbd3ea601b50b36c7 +sdk.win_installer=installer_r11-windows.exe +sdk.win_installer_bytes=32883649 +sdk.win_installer_checksum=3dc8a29ae5afed97b40910ef153caa2b -sdk.win_download=android-sdk_r10-windows.zip -sdk.win_bytes=32832260 -sdk.win_checksum=1e42b8f528d9ca6d9b887c58c6f1b9a2 +sdk.win_download=android-sdk_r11-windows.zip +sdk.win_bytes=32837554 +sdk.win_checksum=0a2c52b8f8d97a4871ce8b3eb38e3072 -sdk.mac_download=android-sdk_r10-mac_x86.zip -sdk.mac_bytes=28847132 -sdk.mac_checksum=e3aa5578a6553b69cc36659c9505be3f +sdk.mac_download=android-sdk_r11-mac_x86.zip +sdk.mac_bytes=28844968 +sdk.mac_checksum=85bed5ed25aea51f6a447a674d637d1e -sdk.linux_download=android-sdk_r10-linux_x86.tgz -sdk.linux_bytes=26981997 -sdk.linux_checksum=c022dda3a56c8a67698e6a39b0b1a4e0 +sdk.linux_download=android-sdk_r11-linux_x86.tgz +sdk.linux_bytes=26984929 +sdk.linux_checksum=026c67f82627a3a70efb197ca3360d0a @jd:body diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs index 6b9a5ce..3240b57 100644 --- a/docs/html/sdk/sdk_toc.cs +++ b/docs/html/sdk/sdk_toc.cs @@ -113,7 +113,8 @@ class="new">new!</span></li> </li> </ul> <ul> - <li><a href="<?cs var:toroot ?>sdk/tools-notes.html">SDK Tools, r10</a> <span class="new">new!</span></li> + <li><a href="<?cs var:toroot ?>sdk/tools-notes.html">SDK Tools, r11</a> <span +class="new">new!</span></li> <li><a href="<?cs var:toroot ?>sdk/win-usb.html">Google USB Driver, r4</a></li> </ul> </li> @@ -137,7 +138,7 @@ class="new">new!</span></li> <span style="display:none" class="ja"></span> <span style="display:none" class="zh-CN"></span> <span style="display:none" class="zh-TW"></span></a> - <span class="new">new!</span></li> + <!-- <span class="new">new!</span> --></li> </ul> </li> <li> diff --git a/docs/html/sdk/tools-notes.jd b/docs/html/sdk/tools-notes.jd index 28d8bdd..354fec9 100644 --- a/docs/html/sdk/tools-notes.jd +++ b/docs/html/sdk/tools-notes.jd @@ -70,6 +70,33 @@ SDK Tools, Revision 10</a> <em>(February 2011)</em> <dl> <dt>Dependencies:</dt> <dd> +<p>If you are developing in Eclipse with ADT, note that the SDK Tools r11 is designed for use with +ADT 10.0.1 and later. If you haven't already, we highly recommend updating your <a +href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin</a> to 10.0.1.</p> + +<p>If you are developing outside Eclipse, you must have <a href="http://ant.apache.org/">Apache +Ant</a> 1.8 or later.</p> + +<dt>General notes:</dt> +<dd> + <ul> + <li>Miscellaneous emulator changes to support Android 3.1.</li> + </ul> +</dd> +</dl> +</div> +</div> + + +<div class="toggleable closed"> + <a href="#" onclick="return toggleDiv(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-img" height="9px" +width="9px" /> +SDK Tools, Revision 10</a> <em>(February 2011)</em> + <div class="toggleme"> + <dl> +<dt>Dependencies:</dt> +<dd> <p>If you are developing in Eclipse with ADT, note that the SDK Tools r10 is designed for use with ADT 10.0.0 and later. After installing SDK Tools r10, we highly recommend updating your ADT Plugin to 10.0.0.</p> @@ -80,7 +107,8 @@ Ant</a> 1.8 or later.</p> <dt>General notes:</dt> <dd> <ul> - <li>The tools now automatically generate Java Programming Language source files (in the <code>gen</code> directory) and + <li>The tools now automatically generate Java Programming Language source files (in the +<code>gen</code> directory) and bytecode (in the <code>res/raw</code> directory) from your native <code>.rs</code> files</li> </ul> </dd> @@ -400,7 +428,7 @@ main and test projects.</li> <dt>DDMS:</dt> <dd> <ul> -<li>Adds a button to dump HPROF file for running appplications (app must be able +<li>Adds a button to dump HPROF file for running applications (app must be able to write to the sdcard).</li> <li>Button to start/stop profiling of a running application (app must be able to write to the sdcard). Upon stop, Traceview will automatically be launched to diff --git a/media/java/android/mtp/MtpDevice.java b/media/java/android/mtp/MtpDevice.java index 47bb8c9..3272fed 100644 --- a/media/java/android/mtp/MtpDevice.java +++ b/media/java/android/mtp/MtpDevice.java @@ -22,7 +22,10 @@ import android.os.ParcelFileDescriptor; import android.util.Log; /** - * This class represents an MTP or PTP device connected on the USB host bus. + * This class represents an MTP or PTP device connected on the USB host bus. An application can + * instantiate an object of this type, by referencing an attached {@link + * android.hardware.usb.UsbDevice} and then use methods in this class to get information about the + * device and objects stored on it, as well as open the connection and transfer data. */ public final class MtpDevice { diff --git a/media/java/android/mtp/package.html b/media/java/android/mtp/package.html new file mode 100644 index 0000000..6bd9229 --- /dev/null +++ b/media/java/android/mtp/package.html @@ -0,0 +1,8 @@ +<html> +<body> +<p>Provides APIs that let you interact directly with connected cameras and other devices, using the +PTP (Picture Transfer Protocol) subset of the MTP (Media Transfer Protocol) specification. Your +application can receive notifications when devices are attached and removed, manage files and +storage on those devices, and transfer files and metadata from the devices.</p> +</body> +</html>
\ No newline at end of file diff --git a/voip/java/android/net/rtp/package.html b/voip/java/android/net/rtp/package.html new file mode 100644 index 0000000..4506b09 --- /dev/null +++ b/voip/java/android/net/rtp/package.html @@ -0,0 +1,28 @@ +<html> +<body> +<p>Provides APIs for RTP (Real-time Transport Protocol), allowing applications to manage on-demand +or interactive data streaming. In particular, apps that provide VOIP, push-to-talk, conferencing, +and audio streaming can use these APIs to initiate sessions and transmit or receive data streams +over any available network.</p> + +<p>To support audio conferencing and similar usages, you need to instantiate two classes as +endpoints for the stream:</p> + +<ul> +<li>{@link android.net.rtp.AudioStream} specifies a remote endpoint and consists of network mapping +and a configured {@link android.net.rtp.AudioCodec}.</li> + +<li>{@link android.net.rtp.AudioGroup} represents the local endpoint for one or more {@link +android.net.rtp.AudioStream}s. The {@link android.net.rtp.AudioGroup} mixes all the {@link +android.net.rtp.AudioStream}s and optionally interacts with the device speaker and the microphone at +the same time.</li> +</ul> + +<p>The simplest usage involves a single remote endpoint and local endpoint. For more complex usages, +refer to the limitations described for {@link android.net.rtp.AudioGroup}.</p> + +<p class="note"><strong>Note:</strong> To use the RTP APIs, you must request the {@link +android.Manifest.permission#INTERNET} and {@link +android.Manifest.permission#RECORD_AUDIO} permissions in your manifest file.</p> +</body> +</html>
\ No newline at end of file |
