1 /* 2 * Copyright (C) 2022 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 com.android.server.sdksandbox; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.content.ServiceConnection; 23 import android.content.pm.PackageManager; 24 25 import com.android.sdksandbox.ISdkSandboxService; 26 27 import java.io.PrintWriter; 28 import java.lang.annotation.Retention; 29 import java.lang.annotation.RetentionPolicy; 30 31 /** 32 * Interface to get hold of SdkSandbox service 33 * 34 * @hide 35 */ 36 public interface SdkSandboxServiceProvider { 37 38 /** @hide */ 39 @IntDef(value = {NON_EXISTENT, CREATE_PENDING, CREATED}) 40 @Retention(RetentionPolicy.SOURCE) 41 @interface SandboxStatus {} 42 43 // Represents the state of the sandbox process when it has either not yet been created or is 44 // dead. 45 int NON_EXISTENT = 1; 46 47 // Indicates that the sandbox is either in the middle of being created (after a call to bind 48 // was performed) or being restarted. 49 int CREATE_PENDING = 2; 50 51 // Indicates that the sandbox process is up and running. 52 int CREATED = 3; 53 54 /** Fixed suffix which get appended to app process name to create its sandbox process name. */ 55 String SANDBOX_PROCESS_NAME_SUFFIX = "_sdk_sandbox"; 56 57 /** 58 * Fixed suffix appended to instrumented app process name to create its sandbox process name. 59 */ 60 String SANDBOX_INSTR_PROCESS_NAME_SUFFIX = "_sdk_sandbox_instr"; 61 62 /** 63 * Bind to and establish a connection with SdkSandbox service. 64 * 65 * @param callingInfo represents the calling app. 66 * @param serviceConnection receives information when service is started and stopped. 67 */ bindService(CallingInfo callingInfo, ServiceConnection serviceConnection)68 void bindService(CallingInfo callingInfo, ServiceConnection serviceConnection); 69 70 /** 71 * Unbind the SdkSandbox service associated with the app. 72 * 73 * @param callingInfo represents the app for which the sandbox should be unbound. 74 */ unbindService(CallingInfo callingInfo)75 void unbindService(CallingInfo callingInfo); 76 77 /** 78 * Kills the sandbox for the given app. 79 * 80 * @param callingInfo app for which the sandbox kill is being requested. 81 */ stopSandboxService(CallingInfo callingInfo)82 void stopSandboxService(CallingInfo callingInfo); 83 84 /** 85 * Return {@link ISdkSandboxService} connected for {@code callingInfo} or otherwise {@code 86 * null}. 87 */ 88 @Nullable getSdkSandboxServiceForApp(CallingInfo callingInfo)89 ISdkSandboxService getSdkSandboxServiceForApp(CallingInfo callingInfo); 90 91 /** 92 * Informs the provider when the sandbox service has connected. 93 * 94 * @param callingInfo represents the app for which the sandbox service has connected. 95 * @param service the binder object used to communicate with the sandbox service. 96 */ onServiceConnected(CallingInfo callingInfo, @NonNull ISdkSandboxService service)97 void onServiceConnected(CallingInfo callingInfo, @NonNull ISdkSandboxService service); 98 99 /** 100 * Informs the provider when the sandbox service has disconnected. 101 * 102 * @param callingInfo represents the app for which the sandbox service has disconnected. 103 */ onServiceDisconnected(CallingInfo callingInfo)104 void onServiceDisconnected(CallingInfo callingInfo); 105 106 /** 107 * Informs the provider when an app has died. 108 * 109 * @param callingInfo represents the app for which the sandbox has died. 110 */ onAppDeath(CallingInfo callingInfo)111 void onAppDeath(CallingInfo callingInfo); 112 113 /** 114 * Informs the provider when the sandbox service has died. 115 * 116 * @param callingInfo represents the app for which the sandbox service has died. 117 */ onSandboxDeath(CallingInfo callingInfo)118 void onSandboxDeath(CallingInfo callingInfo); 119 120 /** 121 * Returns true if the sandbox is currently bound for the given app. 122 * 123 * @param callingInfo app for which the sandbox bound status is being requested. 124 */ isSandboxBoundForApp(CallingInfo callingInfo)125 boolean isSandboxBoundForApp(CallingInfo callingInfo); 126 127 /** 128 * Returns the status of the sandbox for the given app. 129 * 130 * @param callingInfo app for which the sandbox status is being requested. 131 */ 132 @SandboxStatus getSandboxStatusForApp(CallingInfo callingInfo)133 int getSandboxStatusForApp(CallingInfo callingInfo); 134 135 /** Dump debug information for adb shell dumpsys */ dump(PrintWriter writer)136 default void dump(PrintWriter writer) { 137 } 138 139 /** 140 * Returns sandbox process name for the passed app package name. 141 * 142 * @param callingInfo app for which the sandbox status is being requested. 143 * @throws PackageManager.NameNotFoundException exception thrown if the app corresponding to the 144 * callingInfo does not exist (e.g. if it is not installed). 145 */ 146 @NonNull toSandboxProcessName(@onNull CallingInfo callingInfo)147 String toSandboxProcessName(@NonNull CallingInfo callingInfo) 148 throws PackageManager.NameNotFoundException; 149 150 /** 151 * Returns name of the sdk sandbox process that corresponds to the given client app. 152 * 153 * @param callingInfo app for which the sandbox status is being requested. 154 * @return name of the sdk sandbox process to be instrumented 155 */ 156 @NonNull toSandboxProcessNameForInstrumentation(@onNull CallingInfo callingInfo)157 String toSandboxProcessNameForInstrumentation(@NonNull CallingInfo callingInfo) 158 throws PackageManager.NameNotFoundException; 159 } 160