am 3d265b57: am 50f86c65: docs: a few style adjustments to admin doc

page.title=Android Device Administration API

page.title=Device Administration

@jd:body

<div id="qv-wrapper">

<div id="qv">

    <h2>In this document</h2>

    <ol>

<li><a href="#overview">Device Administration API Overview</a>

    <ol>

      <li><a href="#how">How does it work?</a></li>

      <li><a href="#policies">Policies</a></li>

    </ol>

  </li>

  <li><a href="#how">How Does It Work?</a></li>

  <li><a href="#sample">Sample Application</a></li>

  <li><a href="#developing">Developing a Device Administration Application</a>

    <ol>

      <li><a href="#manifest">Creating the Manifest</a></li>

      <li><a href="#code">Implementing the Code</a>

      <li><a href="#manifest">Creating the manifest</a></li>

      <li><a href="#code">Implementing the code</a></li>

    </ol>

  </li>

 </ol>

    <h2>Key classes</h2>

    <ol>

      <li>{@link android.app.admin.DeviceAdminReceiver}</li>

      <li>{@link android.app.admin.DevicePolicyManager}</li>

      <li>{@link android.app.admin.DeviceAdminInfo}</li>

    </ol>

</div>

</div>

solutions for Android-powered devices. It discusses the various features

provided by the Device Administration API to provide stronger security for

employee devices that are powered by Android.</p>

<h2 id="overview">Device Administration API Overview</h2>

<p>Here are examples of the types of applications that might use the Device Administration API:</p>

<ul>

  <li>Email clients.</li>

  <li>Device management services and applications.</li>

</ul>

<h3 id="how">How Does it Work?</h3>

<h3 id="how">How does it work?</h3>

<p>You use the Device Administration API to write device admin applications that users

install on their devices. The device admin application enforces the desired

policies. Here's how it works:</p> <ul>

<p>To uninstall an existing device admin application, users need to

first unregister the application as an administrator. </p>

<h3 id="policies">Policies</h3>

<p>In an enterprise setting, it's often the case that employee devices must

adhere to a strict set of policies that govern the use of the device. The

Device Administration API supports the  policies listed in Table 1.

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>

</table>

<h4>Other Features</h4>

<h4>Other features</h4>

<p>In addition to supporting the policies listed in the above table, the Device

Administration API lets you do the following:</p> <ul>

  <li>Prompt user to set a new password.</li>

<h2 id="sample">Sample Application</h2>

<p>The examples used in this document are based on the <a

href="{@docRoot}resources/samples/ApiDemos/src/com/example/

android/apis/app/DeviceAdminSample.html">Device Administration API

<img src="{@docRoot}images/admin/device-admin-app.png"/>

<p class="img-caption"><strong>Figure 1.</strong> Screenshot of the Sample Application</p>

<h2 id="developing">Developing a Device Administration Application</h2>

<p>System administrators can use the Device Administration API to write an application

that enforces remote/local device security policy enforcement. This section

summarizes the steps involved in creating a device administration

application.</p>

<h3 id="manifest">Creating the Manifest</h3>

<h3 id="manifest">Creating the manifest</h3>

<p>To use the Device Administration API, the application's

manifest must include the following:</p>

<ul>

</p>

For more discussion of the manifest file, see the <a

href="{@docRoot}guide/topics/manifest/manifest-intro.html">Android Developers Guide</a>.

<h2 id="code">Implementing the Code</h2>

<h3 id="code">Implementing the code</h3>

<p>The Device Administration API includes the following classes:</p>

<dl>

  <dt>{@link android.app.admin.DeviceAdminReceiver}</dt>

The rest of this section describes how you use the {@link

android.app.admin.DeviceAdminReceiver} and

{@link android.app.admin.DevicePolicyManager} APIs to write a device admin application.</p>

<h4 id="receiver">Subclassing DeviceAdminReceiver</h4>

<p>To create a device admin application, you must subclass

{@link android.app.admin.DeviceAdminReceiver}. The {@link android.app.admin.DeviceAdminReceiver} class

    }

...

}</pre>

<h4 id="enabling">Enabling the Application</h4>

<h4 id="enabling">Enabling the application</h4>

<p>One of the major events a device admin application has to handle is the user

enabling the application. The user must explicitly enable the application for

the policies to be enforced. If the user chooses not to enable the application

sample application, this happens when the user clicks the <strong>Enable

Admin</strong> button. </p>

<p>When the user clicks the <strong>Enable Admin</strong> button, the display

changes to prompt the user to enable the device admin application, as shown in <strong>Figure 2</strong>.</p>

changes to prompt the user to enable the device admin application, as shown in figure

2.</p>

<img src="{@docRoot}images/admin/device-admin-activate-prompt.png"/>

<p class="img-caption"><strong>Figure 2.</strong> Sample Application: Activating the Application</p>

<p>Below  is the code that gets executed when the user clicks the <strong>Enable

Admin</strong> button shown in <strong>Figure 1</strong>. </p>

Admin</strong> button shown in figure 1. </p>

<pre> private OnClickListener mEnableListener = new OnClickListener() {

    public void onClick(View v) {

<code>intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN,

mDeviceAdminSample)</code> states that <code>mDeviceAdminSample</code> (which is

a {@link android.app.admin.DeviceAdminReceiver} component) is the target policy.

This line invokes the user interface shown in <strong>Figure 2</strong>, which guides users through

This line invokes the user interface shown in figure 2, which guides users through

adding the device administrator to the system (or allows them to reject it).</p>

<p>When the application needs to perform an operation that is contingent on the

    // do something else

}

</pre>

<h3 id="admin_ops">Managing Policies</h3>

<h3 id="admin_ops">Managing policies</h3>

<p>{@link android.app.admin.DevicePolicyManager} is a public class for managing policies

enforced on a device. {@link android.app.admin.DevicePolicyManager} manages policies for one

or more {@link android.app.admin.DeviceAdminReceiver} instances. </p>

<p>You get a handle to the {@link android.app.admin.DevicePolicyManager} as follows: </p>

<pre>DevicePolicyManager mDPM =

(DevicePolicyManager)getSystemService(Context.DEVICE_POLICY_SERVICE);<br

/></pre>

<pre>

DevicePolicyManager mDPM =

    (DevicePolicyManager)getSystemService(Context.DEVICE_POLICY_SERVICE);

</pre>

<p>This section describes how to use {@link android.app.admin.DevicePolicyManager} to perform

 administrative tasks:</p>

<ul>

  <li><a href="#lock">Set  device lock</a></li>

  <li><a href="#wipe">Perform data wipe</a></li>

</ul>

<h4 id="pwd">Set password policies</h4>

<p>{@link android.app.admin.DevicePolicyManager} includes APIs for setting and enforcing the

device password policy. In the Device Administration API, the password only applies to

screen lock. This section describes common password-related tasks.</p>

<h5>Set a password for the device</h5>

<p>This code displays a user interface prompting the user to set a password:</p>

<pre>Intent intent = new Intent(DevicePolicyManager.ACTION_SET_NEW_PASSWORD);

startActivity(intent);

</pre>

<h5>Set the password quality</h5>

<p>The password quality can be one of the following {@link android.app.admin.DevicePolicyManager} constants: </p>

<dl>

...

mDPM.setPasswordQuality(mDeviceAdminSample, DevicePolicyManager.PASSWORD_QUALITY_ALPHANUMERIC);

</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>

...

mDPM.setPasswordMinimumLength(mDeviceAdminSample, pwLength);

</pre>

<h5>Set maximum failed password attempts</h5>

<p>You can set the maximum number of allowed failed password attempts before the

device is wiped (that is, reset to factory settings). For example:</p>

int maxFailedPw;

 ...

mDPM.setMaximumFailedPasswordsForWipe(mDeviceAdminSample, maxFailedPw);</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>

DevicePolicyManager mDPM;

mDPM.lockNow();</pre>

<h4 id="wipe">Perform data wipe</h4>

<p>You can use the {@link android.app.admin.DevicePolicyManager} method

{@link android.app.admin.DevicePolicyManager#wipeData wipeData()} to reset the device to factory settings. This is useful

if the device is lost or stolen. Often the decision to wipe the device is the