Home | History | Annotate | Download | only in admin 
      1 page.title=Building Multiuser-Aware Apps
      2 @jd:body
      3 
      4 <!--
      5     Copyright 2015 The Android Open Source Project
      6 
      7     Licensed under the Apache License, Version 2.0 (the "License");
      8     you may not use this file except in compliance with the License.
      9     You may obtain a copy of the License at
     10 
     11         http://www.apache.org/licenses/LICENSE-2.0
     12 
     13     Unless required by applicable law or agreed to in writing, software
     14     distributed under the License is distributed on an "AS IS" BASIS,
     15     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     16     See the License for the specific language governing permissions and
     17     limitations under the License.
     18 -->
     19 <div id="qv-wrapper">
     20   <div id="qv">
     21     <h2>In this document</h2>
     22     <ol id="auto-toc">
     23     </ol>
     24   </div>
     25 </div>
     26 
     27 <p>When a device supports <a href="multi-user.html">multiple users</a>, its apps must be made aware of these distinct users.</p>
     28 
     29 <p>Certain apps need to have some components run as singletons and can accept
     30 requests from any user. Only system apps can currently use this feature.</p>
     31 
     32 <p>This facility:</p>
     33 
     34 <ul>
     35   <li>Conserves resources
     36   <li>Arbitrates one or more shared resources across users
     37   <li>Reduces network overhead by using a single server connection
     38 </ul>
     39 
     40 <p>See the diagram below for a depiction of permissions flow with multiple users.</p>
     41 
     42 <p><img src="images/multi-user-perms.png" alt="Multiple users permissions flow" />
     43 <p class="img-caption"><strong>Figure 1.</strong> Multiple users permissions</p>
     44 
     45 <h2 id=enabling_a_singleton_component>Enabling a singleton component</h2>
     46 
     47 <p>To identify an app as a singleton, Add <code>android:singleUser=true</code> to your service or provider in the Android manifest.</p>
     48 
     49 <p>The system will instantiate that component in the process running as user 0
     50 only. Any requests to connect to that provider or service from any user will be
     51 routed to the process in user 0. If this is the only component in your app,
     52 only one instance of your app will run.</p>
     53 
     54 <p>Activities in your package will still be launched in a separate process for
     55 each user, with the UID being in the UID range for that user (such as 1010034).</p>
     56 
     57 <h2 id=interacting_with_users>Interacting with users</h2>
     58 
     59 <h3 id=perms_required>Set permissions</h3>
     60 
     61 <p>These permissions are required</p>
     62 
     63 <pre>
     64 INTERACT_ACROSS_USERS (signature|system)
     65 INTERACT_ACROSS_USERS_FULL (signature)
     66 </pre>
     67 
     68 <h3 id=apis>Employ APIs</h3>
     69 
     70 <p>Use the following APIs to make apps aware of multiple users.</p>
     71 
     72 <ol>
     73   <li> Extract the user handle from incoming Binder calls:
     74   <ul>
     75     <li> <code>int userHandle = UserHandle.getCallingUserId()</code>
     76   </ul>
     77   <li> Use new, protected APIs to start services, activities, broadcasts on a specific
     78 user: 
     79   <ul>
     80     <li><code>Context.startActivityAsUser(Intent, UserHandle)</code>
     81     <li><code>Context.bindServiceAsUser(Intent, , UserHandle)</code>
     82     <li><code>Context.sendBroadcastAsUser(Intent,  , UserHandle)</code>
     83     <li><code>Context.startServiceAsUser(Intent, , UserHandle)
     84 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.
     85   </ul>
     86   <li>Communicate with components in your own app:
     87 <code>(INTERACT_ACROSS_USERS)</code>
     88 Or with components in other apps:
     89 <code>(INTERACT_ACROSS_USERS_FULL)</code>
     90   <li>You may need to create proxy components that run in the users process that
     91 then access the <code>singleUser</code> component in user 0.
     92   <li>Query users and their handles with the new <code>UserManager</code> system service:
     93   <ul>
     94     <li><code>UserManager.getUsers()</code>
     95     <li><code>UserManager.getUserInfo()</code>
     96     <li><code>UserManager.supportsMultipleUsers()</code>
     97     <li><code>UserManager.getUserSerialNumber(int userHandle)</code> - a non-recycled number that corresponds to a user handle.
     98     <li><code>UserManager.getUserHandle(int serialNumber)</code>
     99     <li><code>UserManager.getUserProfiles() </code>- returns the collection of self and managed profiles, if any.
    100   </ul>
    101   <li>Register to listen to specific or all users and the callbacks with new APIs on
    102 ContentObserver, PackageMonitor, BroadcastReceiver that provide additional
    103 information about which user has caused the callback.
    104 </ol>
    105