1 /*
2  * Copyright (C) 2020 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.os;
18 
19 import android.os.IUpdateEngineStableCallback;
20 import android.os.ParcelFileDescriptor;
21 
22 /**
23  * The stable interface exposed by the update engine daemon.
24  *
25  * WARNING: this interface exposes less capabilities than IUpdateEngine,
26  * for instance, not having a cancel method. This is relied on for
27  * security.
28  * @hide
29  */
30 interface IUpdateEngineStable {
31   /**
32    * Apply the given payload as provided in the given file descriptor.
33    *
34    * See {@link #bind(IUpdateEngineCallback)} for status updates.
35    *
36    * @param pfd The file descriptor opened at the payload file. Note that the daemon must have
37    *   enough permission to operate on the file descriptor.
38    * @param payload_offset offset into pfd where the payload binary starts.
39    * @param payload_size length after payload_offset to read from pfd. If 0, it will be auto
40    *   detected.
41    * @param headerKeyValuePairs additional header key value pairs, in the format of "key=value".
42    * @see android.os.UpdateEngine#applyPayload(android.content.res.AssetFileDescriptor, String[])
43    * @hide
44    */
applyPayloadFd(in ParcelFileDescriptor pfd, in long payload_offset, in long payload_size, in String[] headerKeyValuePairs)45   void applyPayloadFd(in ParcelFileDescriptor pfd,
46                       in long payload_offset,
47                       in long payload_size,
48                       in String[] headerKeyValuePairs);
49 
50   /**
51    * Bind a callback for status updates on payload application.
52    *
53    * At any given time, only one callback can be bound. If a callback is already bound,
54    * subsequent binding will fail and return false until the bound callback is unbound. That is,
55    * binding is first-come, first-serve.
56    *
57    * A bound callback may be unbound explicitly by calling
58    * {@link #unbind(IUpdateEngineStableCallback)}, or
59    * implicitly when the process implementing the callback dies.
60    *
61    * @param callback See {@link IUpdateEngineStableCallback}
62    * @return true if binding is successful, false otherwise.
63    * @see android.os.UpdateEngine#bind(android.os.UpdateEngineCallback)
64    * @hide
65    */
bind(IUpdateEngineStableCallback callback)66   boolean bind(IUpdateEngineStableCallback callback);
67 
68   /**
69    * Unbind a possibly bound callback.
70    *
71    * If the provided callback does not match the previously bound callback, unbinding fails.
72    *
73    * Note that a callback may also be unbound when the process implementing the callback dies.
74    * Hence, a client usually does not need to explicitly unbind a callback unless it wants to change
75    * the bound callback.
76    *
77    * @param callback The callback to be unbound. See {@link IUpdateEngineStableCallback}.
78    * @return true if unbinding is successful, false otherwise.
79    * @see android.os.UpdateEngine#unbind(android.os.UpdateEngineCallback)
80    * @hide
81    */
unbind(IUpdateEngineStableCallback callback)82   boolean unbind(IUpdateEngineStableCallback callback);
83 }
84