1 /* 2 * Copyright (C) 2015 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.support.car; 18 19 /** 20 * CarAppContextManager allows applications to set and listen for the current application context 21 * like active navigation or active voice command. Usually only one instance of such application 22 * should run in the system, and other app setting the flag for the matching app should 23 * lead into other app to stop. 24 * @hide 25 */ 26 public abstract class CarAppContextManager implements CarManagerBase { 27 /** 28 * Listener to get notification for app getting information on app context change. 29 */ 30 public interface AppContextChangeListener { 31 /** 32 * Application context has changed. Note that {@link CarAppContextManager} instance 33 * causing the change will not get this notification. 34 * @param activeContexts 35 */ onAppContextChange(int activeContexts)36 void onAppContextChange(int activeContexts); 37 } 38 39 /** 40 * Listener to get notification for app getting information on app context ownership loss. 41 */ 42 public interface AppContextOwnershipChangeListener { 43 /** 44 * Lost ownership for the context, which happens when other app has set the context. 45 * The app losing context should stop the action associated with the context. 46 * For example, navigaiton app currently running active navigation should stop navigation 47 * upon getting this for {@link CarAppContextManager#APP_CONTEXT_NAVIGATION}. 48 * @param context 49 */ onAppContextOwnershipLoss(int context)50 void onAppContextOwnershipLoss(int context); 51 } 52 53 /** @hide */ 54 public static final int APP_CONTEXT_START_FLAG = 0x1; 55 /** 56 * Flag for active navigation. 57 */ 58 public static final int APP_CONTEXT_NAVIGATION = 0x1; 59 /** 60 * Flag for active voice command. 61 */ 62 public static final int APP_CONTEXT_VOICE_COMMAND = 0x2; 63 /** 64 * Update this after adding a new flag. 65 * @hide 66 */ 67 public static final int APP_CONTEXT_END_FLAG = 0x2; 68 69 /** 70 * Register listener to monitor app context change. Only one listener can be registered and 71 * registering multiple times will lead into only the last listener to be active. 72 * @param listener 73 * @param contextFilter Flags of contexts to get notification. 74 * @throws CarNotConnectedException 75 */ registerContextListener(AppContextChangeListener listener, int contextFilter)76 public abstract void registerContextListener(AppContextChangeListener listener, 77 int contextFilter) throws CarNotConnectedException; 78 79 /** 80 * Unregister listener and stop listening context change events. If app has owned a context 81 * by {@link #setActiveContext(int)}, it will be reset to inactive state. 82 * @throws CarNotConnectedException 83 */ unregisterContextListener()84 public abstract void unregisterContextListener() throws CarNotConnectedException; 85 86 /** 87 * Retrieve currently active contexts. 88 * @return 89 * @throws CarNotConnectedException 90 */ getActiveAppContexts()91 public abstract int getActiveAppContexts() throws CarNotConnectedException; 92 93 /** 94 * Check if the current process is owning the given context. 95 * @param context 96 * @return 97 * @throws CarNotConnectedException 98 */ isOwningContext(int context)99 public abstract boolean isOwningContext(int context) throws CarNotConnectedException; 100 101 /** 102 * Set the given contexts as active. By setting this, the application is becoming owner 103 * of the context, and will get {@link AppContextChangeListener#onAppContextOwnershipLoss(int)} 104 * if ownership is given to other app by calling this. Fore-ground app will have higher priority 105 * and other app cannot set the same context while owner is in fore-ground. 106 * Before calling this, {@link #registerContextListener(AppContextChangeListener, int)} should 107 * be called first. Otherwise, it will throw IllegalStateException 108 * @param contexts 109 * @throws IllegalStateException If listener was not registered. 110 * @throws SecurityException If owner cannot be changed. 111 * @throws CarNotConnectedException 112 */ setActiveContexts(AppContextOwnershipChangeListener ownershipListener, int contexts)113 public abstract void setActiveContexts(AppContextOwnershipChangeListener ownershipListener, 114 int contexts) throws IllegalStateException, SecurityException, CarNotConnectedException; 115 116 /** 117 * Reset the given contexts, i.e. mark them as inactive. This also involves releasing ownership 118 * for the context. 119 * @param contexts 120 * @throws CarNotConnectedException 121 */ resetActiveContexts(int contexts)122 public abstract void resetActiveContexts(int contexts) throws CarNotConnectedException; 123 } 124