1 /* 2 * Copyright (C) 2024 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 com.android.server.appfunctions; 17 18 import android.annotation.NonNull; 19 import android.content.Intent; 20 import android.os.CancellationSignal; 21 import android.os.IBinder; 22 import android.os.UserHandle; 23 24 /** 25 * Defines a contract for establishing temporary connections to services and executing operations. 26 * Implementations of this interface provide mechanisms to ensure that services are properly unbound 27 * after the operation completes or a cancellation timeout occurs. 28 * 29 * @param <T> Class of wrapped service. 30 */ 31 public interface RemoteServiceCaller<T> { 32 33 /** 34 * Initiates service binding and executes a provided method when the service connects. 35 * 36 * <p>Unbinds the service after execution or upon cancellation timeout or calling process death. 37 * Returns the result of the bindService API. 38 * 39 * <p>When the service connection was made successfully, it's the caller responsibility to 40 * report the usage is completed and can be unbound by calling {@link 41 * ServiceUsageCompleteListener#onCompleted()}. 42 * 43 * <p>This method includes a timeout mechanism for cancellation to prevent the system from being 44 * stuck in a state where a service is bound indefinitely. If the app to be bound does not 45 * return the result within `cancellationTimeoutMillis` after the cancellation signal is sent, 46 * this method will unbind the service connection. 47 * 48 * <p>This method will also unbind the service after the calling process dies (because a 49 * cancellation signal cannot be sent and system server can become bound forever if otherwise). 50 * 51 * @param intent An Intent object that describes the service that should be bound. 52 * @param bindFlags Flags used to control the binding process See {@link 53 * android.content.Context#bindService}. 54 * @param userHandle The UserHandle of the user for which the service should be bound. 55 * @param cancellationTimeoutMillis The timeout before the service is unbound after a 56 * cancellation signal is issued. 57 * @param cancellationSignal The cancellation signal forwarded to the service. 58 * @param callback A callback to be invoked for various events. See {@link 59 * RunServiceCallCallback}. 60 * @param callerBinder The binder of the caller. 61 */ runServiceCall( @onNull Intent intent, int bindFlags, @NonNull UserHandle userHandle, long cancellationTimeoutMillis, @NonNull CancellationSignal cancellationSignal, @NonNull RunServiceCallCallback<T> callback, @NonNull IBinder callerBinder)62 boolean runServiceCall( 63 @NonNull Intent intent, 64 int bindFlags, 65 @NonNull UserHandle userHandle, 66 long cancellationTimeoutMillis, 67 @NonNull CancellationSignal cancellationSignal, 68 @NonNull RunServiceCallCallback<T> callback, 69 @NonNull IBinder callerBinder); 70 71 /** An interface for clients to signal that they have finished using a bound service. */ 72 interface ServiceUsageCompleteListener { 73 /** 74 * Called when a client has finished using a bound service. This indicates that the service 75 * can be safely unbound. 76 */ onCompleted()77 void onCompleted(); 78 } 79 80 interface RunServiceCallCallback<T> { 81 /** 82 * Called when the service connection has been established. Uses {@code 83 * serviceUsageCompleteListener} to report finish using the connected service. 84 */ onServiceConnected( @onNull T service, @NonNull ServiceUsageCompleteListener serviceUsageCompleteListener)85 void onServiceConnected( 86 @NonNull T service, 87 @NonNull ServiceUsageCompleteListener serviceUsageCompleteListener); 88 89 /** Called when the service connection was failed to establish. */ onFailedToConnect()90 void onFailedToConnect(); 91 92 /** Called when the caller has cancelled this remote service call. */ onCancelled()93 void onCancelled(); 94 } 95 } 96