86 lines
3.5 KiB
Java
86 lines
3.5 KiB
Java
/*
|
|
* Copyright (C) 2024 The Android Open Source Project
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
package android.app.appsearch.functions;
|
|
|
|
import android.annotation.NonNull;
|
|
import android.content.Intent;
|
|
import android.os.UserHandle;
|
|
|
|
/**
|
|
* Defines a contract for establishing temporary connections to services and executing operations
|
|
* within a specified timeout. Implementations of this interface provide mechanisms to ensure that
|
|
* services are properly unbound after the operation completes or a timeout occurs.
|
|
*
|
|
* @hide
|
|
*/
|
|
public interface ServiceCallHelper<T> {
|
|
|
|
/**
|
|
* Initiates service binding and executes a provided method when the service connects. Unbinds
|
|
* the service after execution or upon timeout. Returns the result of the bindService API.
|
|
*
|
|
* <p>When the service connection was made successfully, it's the caller responsibility to
|
|
* report the usage is completed and can be unbound by calling {@link
|
|
* ServiceUsageCompleteListener#onCompleted()}.
|
|
*
|
|
* <p>This method includes a timeout mechanism to prevent the system from being stuck in a state
|
|
* where a service is bound indefinitely (for example, if the binder method never returns). This
|
|
* helps ensure that the calling app does not remain alive unnecessarily.
|
|
*
|
|
* @param intent An Intent object that describes the service that should be bound.
|
|
* @param bindFlags Flags used to control the binding process See {@link
|
|
* android.content.Context#bindService}.
|
|
* @param timeoutInMillis The maximum time in milliseconds to wait for the service connection.
|
|
* @param userHandle The UserHandle of the user for which the service should be bound.
|
|
* @param callback A callback to be invoked for various events. See {@link
|
|
* RunServiceCallCallback}.
|
|
*/
|
|
boolean runServiceCall(
|
|
@NonNull Intent intent,
|
|
int bindFlags,
|
|
long timeoutInMillis,
|
|
@NonNull UserHandle userHandle,
|
|
@NonNull RunServiceCallCallback<T> callback);
|
|
|
|
/** An interface for clients to signal that they have finished using a bound service. */
|
|
interface ServiceUsageCompleteListener {
|
|
/**
|
|
* Called when a client has finished using a bound service. This indicates that the service
|
|
* can be safely unbound.
|
|
*/
|
|
void onCompleted();
|
|
}
|
|
|
|
interface RunServiceCallCallback<T> {
|
|
/**
|
|
* Called when the service connection has been established. Uses {@code
|
|
* serviceUsageCompleteListener} to report finish using the connected service.
|
|
*/
|
|
void onServiceConnected(
|
|
@NonNull T service,
|
|
@NonNull ServiceUsageCompleteListener serviceUsageCompleteListener);
|
|
|
|
/** Called when the service connection was failed to establish. */
|
|
void onFailedToConnect();
|
|
|
|
/**
|
|
* Called when the whole operation(i.e. binding and the service call) takes longer than
|
|
* allowed.
|
|
*/
|
|
void onTimedOut();
|
|
}
|
|
}
|