1 /*
2  * Copyright (C) 2023 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 android.federatedcompute;
18 
19 import android.annotation.NonNull;
20 import android.app.Service;
21 import android.content.Intent;
22 import android.content.pm.PackageManager;
23 import android.federatedcompute.aidl.IExampleStoreCallback;
24 import android.federatedcompute.aidl.IExampleStoreService;
25 import android.os.Bundle;
26 import android.os.IBinder;
27 
28 /**
29  * The abstract base class that client apps hosting their own Example Stores must implement.
30  *
31  * <p>The FederatedCompute will call into client apps' implementations to fetch data to use during
32  * the training of new models or get the aggregation analytic result. Apps must add a {@code
33  * <service>} entry to their manifest so that the FederatedCompute can bind to their implementation,
34  * like so:
35  *
36  * <pre>{@code
37  * <application>
38  *   <service android:enabled="true" android:exported="true" android:name=".YourServiceClass">
39  *     <intent-filter>
40  *       <action android:name="com.android.federatedcompute.EXAMPLE_STORE"/>
41  *     </intent-filter>
42  *   </service>
43  * </application>
44  * }</pre>
45  *
46  * @hide
47  */
48 public abstract class ExampleStoreService extends Service {
49     private static final String TAG = ExampleStoreService.class.getSimpleName();
50 
51     private static final String BIND_EXAMPLE_STORE_SERVICE =
52             "android.permission.BIND_EXAMPLE_STORE_SERVICE";
53     private IBinder mIBinder;
54 
55     @Override
onCreate()56     public void onCreate() {
57         mIBinder = new ServiceBinder();
58     }
59 
60     @Override
onBind(Intent intent)61     public IBinder onBind(Intent intent) {
62         return mIBinder;
63     }
64 
65     class ServiceBinder extends IExampleStoreService.Stub {
66         @Override
startQuery(Bundle params, IExampleStoreCallback callback)67         public void startQuery(Bundle params, IExampleStoreCallback callback) {
68             if (!ExampleStoreService.this.checkCallerPermission()) {
69                 throw new SecurityException(
70                         "Unauthorized startQuery call to ExampleStore.");
71             }
72             ExampleStoreService.this.startQuery(
73                     params, new ExampleStoreQueryCallbackImpl(callback));
74         }
75     }
76 
77     /**
78      * To be overridden by implementation to provide checks if caller has specific permission to be
79      * used in ServiceBinder call.
80      *
81      * @return true if permission granted
82      */
checkCallerPermission()83     protected boolean checkCallerPermission() {
84         return checkCallingOrSelfPermission(BIND_EXAMPLE_STORE_SERVICE)
85                 == PackageManager.PERMISSION_GRANTED;
86     }
87 
88     /**
89      * The abstract method that client apps should implement to start a new example store query
90      * using the given selection criteria.
91      */
startQuery(@onNull Bundle params, @NonNull QueryCallback callback)92     public abstract void startQuery(@NonNull Bundle params, @NonNull QueryCallback callback);
93 
94     /**
95      * The client apps use this callback to return their ExampleStoreIterator implementation to the
96      * federated training service.
97      */
98     public interface QueryCallback {
99         /** Called when the iterator is ready for use. */
onStartQuerySuccess(@onNull ExampleStoreIterator iterator)100         void onStartQuerySuccess(@NonNull ExampleStoreIterator iterator);
101 
102         /** Called when an error occurred and the iterator cannot be created. */
onStartQueryFailure(int errorCode)103         void onStartQueryFailure(int errorCode);
104     }
105 }
106