1 /* 2 * Copyright 2017 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 package android.hardware.location; 17 18 import android.annotation.NonNull; 19 import android.annotation.SystemApi; 20 21 import java.util.concurrent.Executor; 22 23 /** 24 * A class for {@link android.hardware.location.ContextHubClient ContextHubClient} to 25 * receive messages and life-cycle events from nanoapps in the Context Hub at which the client is 26 * attached to. 27 * 28 * This callback is registered through the {@link 29 * android.hardware.location.ContextHubManager#createClient( 30 * ContextHubInfo, ContextHubClientCallback, Executor) creation} of 31 * {@link android.hardware.location.ContextHubClient ContextHubClient}. Callbacks are invoked in 32 * the following ways: 33 * 1) Messages from nanoapps delivered through onMessageFromNanoApp may either be broadcasted 34 * or targeted to a specific client. 35 * 2) Nanoapp or Context Hub events (the remaining callbacks) are broadcasted to all clients, and 36 * the client can choose to ignore the event by filtering through the parameters. 37 * 38 * @hide 39 */ 40 @SystemApi 41 public class ContextHubClientCallback { 42 /** 43 * Callback invoked when receiving a message from a nanoapp. 44 * 45 * The message contents of this callback may either be broadcasted or targeted to the 46 * client receiving the invocation. 47 * 48 * @param client the client that is associated with this callback 49 * @param message the message sent by the nanoapp 50 */ onMessageFromNanoApp(ContextHubClient client, NanoAppMessage message)51 public void onMessageFromNanoApp(ContextHubClient client, NanoAppMessage message) {} 52 53 /** 54 * Callback invoked when the attached Context Hub has reset. 55 * 56 * @param client the client that is associated with this callback 57 */ onHubReset(ContextHubClient client)58 public void onHubReset(ContextHubClient client) {} 59 60 /** 61 * Callback invoked when a nanoapp aborts at the attached Context Hub. 62 * 63 * @param client the client that is associated with this callback 64 * @param nanoAppId the ID of the nanoapp that had aborted 65 * @param abortCode the reason for nanoapp's abort, specific to each nanoapp 66 */ onNanoAppAborted(ContextHubClient client, long nanoAppId, int abortCode)67 public void onNanoAppAborted(ContextHubClient client, long nanoAppId, int abortCode) {} 68 69 /** 70 * Callback invoked when a nanoapp is dynamically loaded at the attached Context Hub through 71 * the {@link android.hardware.location.ContextHubManager}. 72 * 73 * NOTE: This callback is <b>not</b> invoked for a nanoapp that is loaded internally by CHRE 74 * (e.g. nanoapps that are preloaded by the system). To check the availability of these 75 * nanoapps, use the {@link ContextHubManager#queryNanoApps(ContextHubInfo)} API. 76 * 77 * @param client the client that is associated with this callback 78 * @param nanoAppId the ID of the nanoapp that had been loaded 79 */ onNanoAppLoaded(ContextHubClient client, long nanoAppId)80 public void onNanoAppLoaded(ContextHubClient client, long nanoAppId) {} 81 82 /** 83 * Callback invoked when a nanoapp is dynamically unloaded from the attached Context Hub through 84 * the {@link android.hardware.location.ContextHubManager}. 85 * 86 * @param client the client that is associated with this callback 87 * @param nanoAppId the ID of the nanoapp that had been unloaded 88 */ onNanoAppUnloaded(ContextHubClient client, long nanoAppId)89 public void onNanoAppUnloaded(ContextHubClient client, long nanoAppId) {} 90 91 /** 92 * Callback invoked when a nanoapp is dynamically enabled at the attached Context Hub through 93 * the {@link android.hardware.location.ContextHubManager}. 94 * 95 * @param client the client that is associated with this callback 96 * @param nanoAppId the ID of the nanoapp that had been enabled 97 */ onNanoAppEnabled(ContextHubClient client, long nanoAppId)98 public void onNanoAppEnabled(ContextHubClient client, long nanoAppId) {} 99 100 /** 101 * Callback invoked when a nanoapp is dynamically disabled at the attached Context Hub through 102 * the {@link android.hardware.location.ContextHubManager}. 103 * 104 * @param client the client that is associated with this callback 105 * @param nanoAppId the ID of the nanoapp that had been disabled 106 */ onNanoAppDisabled(ContextHubClient client, long nanoAppId)107 public void onNanoAppDisabled(ContextHubClient client, long nanoAppId) {} 108 109 /** 110 * Callback invoked when a {@link ContextHubClient}'s authorization to communicate with a 111 * nanoapp changes. This typically happens as a result of the app that created the 112 * {@link ContextHubClient} gaining or losing the permissions required to communicate with a 113 * nanoapp. 114 * 115 * An example of the connection callbacks looks like: 116 * 1) {@link ContextHubClient} sends message to nanoapp and holds required permissions 117 * 2) {@link ContextHubClient} loses required permissions 118 * 3) Callback invoked with the nanoapp ID and 119 * {@link ContextHubManager#AUTHORIZATION_DENIED_GRACE_PERIOD} 120 * 4) {@link ContextHubClient} performs any cleanup required with the nanoapp 121 * 5) Callback invoked with the nanoapp ID and {@link ContextHubManager#AUTHORIZATION_DENIED}. 122 * At this point, any further attempts of communication between the nanoapp and the 123 * {@link ContextHubClient} will be dropped by the contexthub and a security exception will 124 * be thrown when calling {@link ContextHubClient#sendMessageToNanoApp}. The 125 * {@link ContextHubClient} should assume no communciation can happen again until 126 * {@link ContextHubManager#AUTHORIZATION_GRANTED} is received. 127 * 128 * @param client the client that is associated with this callback 129 * @param nanoAppId the ID of the nanoapp associated with the new 130 * authorization state 131 * @param authorization the authorization state denoting the ability of the 132 * client to communicate with the nanoapp 133 */ onClientAuthorizationChanged( @onNull ContextHubClient client, long nanoAppId, @ContextHubManager.AuthorizationState int authorization)134 public void onClientAuthorizationChanged( 135 @NonNull ContextHubClient client, 136 long nanoAppId, 137 @ContextHubManager.AuthorizationState int authorization) {} 138 } 139