Home | History | Annotate | Download | only in car 
      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          */
     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          */
     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      */
     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      */
     84     public abstract void unregisterContextListener() throws CarNotConnectedException;
     85 
     86     /**
     87      * Retrieve currently active contexts.
     88      * @return
     89      * @throws CarNotConnectedException
     90      */
     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      */
     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      */
    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      */
    122     public abstract void resetActiveContexts(int contexts) throws CarNotConnectedException;
    123 }
    124