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 android.app.appsearch.functions;
17 
18 import android.annotation.NonNull;
19 import android.content.Intent;
20 import android.os.UserHandle;
21 
22 /**
23  * Defines a contract for establishing temporary connections to services and executing operations
24  * within a specified timeout. Implementations of this interface provide mechanisms to ensure that
25  * services are properly unbound after the operation completes or a timeout occurs.
26  *
27  * @hide
28  */
29 public interface ServiceCallHelper<T> {
30 
31     /**
32      * Initiates service binding and executes a provided method when the service connects. Unbinds
33      * the service after execution or upon timeout. Returns the result of the bindService API.
34      *
35      * <p>When the service connection was made successfully, it's the caller responsibility to
36      * report the usage is completed and can be unbound by calling {@link
37      * ServiceUsageCompleteListener#onCompleted()}.
38      *
39      * <p>This method includes a timeout mechanism to prevent the system from being stuck in a state
40      * where a service is bound indefinitely (for example, if the binder method never returns). This
41      * helps ensure that the calling app does not remain alive unnecessarily.
42      *
43      * @param intent An Intent object that describes the service that should be bound.
44      * @param bindFlags Flags used to control the binding process See {@link
45      *     android.content.Context#bindService}.
46      * @param timeoutInMillis The maximum time in milliseconds to wait for the service connection.
47      * @param userHandle The UserHandle of the user for which the service should be bound.
48      * @param callback A callback to be invoked for various events. See {@link
49      *     RunServiceCallCallback}.
50      */
runServiceCall( @onNull Intent intent, int bindFlags, long timeoutInMillis, @NonNull UserHandle userHandle, @NonNull RunServiceCallCallback<T> callback)51     boolean runServiceCall(
52             @NonNull Intent intent,
53             int bindFlags,
54             long timeoutInMillis,
55             @NonNull UserHandle userHandle,
56             @NonNull RunServiceCallCallback<T> callback);
57 
58     /** An interface for clients to signal that they have finished using a bound service. */
59     interface ServiceUsageCompleteListener {
60         /**
61          * Called when a client has finished using a bound service. This indicates that the service
62          * can be safely unbound.
63          */
onCompleted()64         void onCompleted();
65     }
66 
67     interface RunServiceCallCallback<T> {
68         /**
69          * Called when the service connection has been established. Uses {@code
70          * serviceUsageCompleteListener} to report finish using the connected service.
71          */
onServiceConnected( @onNull T service, @NonNull ServiceUsageCompleteListener serviceUsageCompleteListener)72         void onServiceConnected(
73                 @NonNull T service,
74                 @NonNull ServiceUsageCompleteListener serviceUsageCompleteListener);
75 
76         /** Called when the service connection was failed to establish. */
onFailedToConnect()77         void onFailedToConnect();
78 
79         /**
80          * Called when the whole operation(i.e. binding and the service call) takes longer than
81          * allowed.
82          */
onTimedOut()83         void onTimedOut();
84     }
85 }
86