| page.title=Building Multiuser-Aware Apps |
| @jd:body |
| |
| <!-- |
| Copyright 2015 The Android Open Source Project |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol id="auto-toc"> |
| </ol> |
| </div> |
| </div> |
| |
| <p>When a device supports <a href="multi-user.html">multiple users</a>, its apps must be made aware of these distinct users.</p> |
| |
| <p>Certain apps need to have some components run as singletons and can accept |
| requests from any user. Only system apps can currently use this feature.</p> |
| |
| <p>This facility:</p> |
| |
| <ul> |
| <li>Conserves resources |
| <li>Arbitrates one or more shared resources across users |
| <li>Reduces network overhead by using a single server connection |
| </ul> |
| |
| <p>See the diagram below for a depiction of permissions flow with multiple users.</p> |
| |
| <p><img src="images/multi-user-perms.png" alt="Multiple users permissions flow" /> |
| <p class="img-caption"><strong>Figure 1.</strong> Multiple users permissions</p> |
| |
| <h2 id=enabling_a_singleton_component>Enabling a singleton component</h2> |
| |
| <p>To identify an app as a singleton, Add <code>android:singleUser=”true”</code> to your service or provider in the Android manifest.</p> |
| |
| <p>The system will instantiate that component in the process running as user 0 |
| only. Any requests to connect to that provider or service from any user will be |
| routed to the process in user 0. If this is the only component in your app, |
| only one instance of your app will run.</p> |
| |
| <p>Activities in your package will still be launched in a separate process for |
| each user, with the UID being in the UID range for that user (such as 1010034).</p> |
| |
| <h2 id=interacting_with_users>Interacting with users</h2> |
| |
| <h3 id=perms_required>Set permissions</h3> |
| |
| <p>These permissions are required</p> |
| |
| <pre> |
| INTERACT_ACROSS_USERS (signature|system) |
| INTERACT_ACROSS_USERS_FULL (signature) |
| </pre> |
| |
| <h3 id=apis>Employ APIs</h3> |
| |
| <p>Use the following APIs to make apps aware of multiple users.</p> |
| |
| <ol> |
| <li> Extract the user handle from incoming Binder calls: |
| <ul> |
| <li> <code>int userHandle = UserHandle.getCallingUserId()</code> |
| </ul> |
| <li> Use new, protected APIs to start services, activities, broadcasts on a specific |
| user: |
| <ul> |
| <li><code>Context.startActivityAsUser(Intent, UserHandle)</code> |
| <li><code>Context.bindServiceAsUser(Intent, …, UserHandle)</code> |
| <li><code>Context.sendBroadcastAsUser(Intent, … , UserHandle)</code> |
| <li><code>Context.startServiceAsUser(Intent, …, UserHandle) |
| UserHandle</code> can be an explicit user or one of the special handles: <code>UserHandle.CURRENT</code> or <code>UserHandle.ALL</code>. <code>CURRENT</code> indicates the user that is currently in the foreground. You can use <code>ALL</code> when you want to send a broadcast to all users. |
| </ul> |
| <li>Communicate with components in your own app: |
| <code>(INTERACT_ACROSS_USERS)</code> |
| Or with components in other apps: |
| <code>(INTERACT_ACROSS_USERS_FULL)</code> |
| <li>You may need to create proxy components that run in the user’s process that |
| then access the <code>singleUser</code> component in user 0. |
| <li>Query users and their handles with the new <code>UserManager</code> system service: |
| <ul> |
| <li><code>UserManager.getUsers()</code> |
| <li><code>UserManager.getUserInfo()</code> |
| <li><code>UserManager.supportsMultipleUsers()</code> |
| <li><code>UserManager.getUserSerialNumber(int userHandle)</code> - a non-recycled number that corresponds to a user handle. |
| <li><code>UserManager.getUserHandle(int serialNumber)</code> |
| <li><code>UserManager.getUserProfiles() </code>- returns the collection of self and managed profiles, if any. |
| </ul> |
| <li>Register to listen to specific or all users and the callbacks with new APIs on |
| ContentObserver, PackageMonitor, BroadcastReceiver that provide additional |
| information about which user has caused the callback. |
| </ol> |