1 /*
2  * Copyright 2022 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 androidx.privacysandbox.ui.core
18 
19 import android.content.Context
20 import android.content.res.Configuration
21 import android.os.Bundle
22 import android.view.View
23 import java.lang.AutoCloseable
24 import java.util.concurrent.Executor
25 
26 /**
27  * An Adapter that provides content from a SandboxedSdk to be displayed as part of a host app's UI.
28  */
29 interface SandboxedUiAdapter {
30 
31     /**
32      * Open a new session for displaying content with an initial size of
33      * [initialWidth]x[initialHeight] pixels. [client] will receive all incoming communication from
34      * the provider of content. All incoming calls to [client] will be made through the provided
35      * [clientExecutor]. [isZOrderOnTop] tracks if the content surface will be placed on top of its
36      * window
37      */
openSessionnull38     fun openSession(
39         context: Context,
40         sessionData: SessionData,
41         initialWidth: Int,
42         initialHeight: Int,
43         isZOrderOnTop: Boolean,
44         clientExecutor: Executor,
45         client: SessionClient
46     )
47 
48     /** A single session with the provider of remote content. */
49     interface Session : AutoCloseable {
50 
51         /**
52          * Return the [View] that presents content for this session. The same view will be returned
53          * for the life of the session object. Accessing [view] after [close] may throw an
54          * [IllegalStateException].
55          */
56         val view: View
57 
58         /**
59          * The set of options that will be used to determine what information is calculated and sent
60          * to [SessionObserver]s attached to this session.
61          *
62          * This value should not be directly set by UI providers. Instead, the registration of any
63          * [SessionObserverFactory] will indicate that information should be calculated for this
64          * session.
65          */
66         val signalOptions: Set<String>
67 
68         /**
69          * Notify the provider that the size of the host presentation area has changed to a size of
70          * [width] x [height] pixels.
71          */
72         fun notifyResized(width: Int, height: Int)
73 
74         /**
75          * Notify the provider that there's a change in the intended z order of the session UI and
76          * it is now set to [isZOrderOnTop].
77          */
78         fun notifyZOrderChanged(isZOrderOnTop: Boolean)
79 
80         /** Notify the session that the host configuration has changed to [configuration]. */
81         fun notifyConfigurationChanged(configuration: Configuration)
82 
83         /**
84          * Notify the session when the presentation state of its UI container has changed.
85          *
86          * [uiContainerInfo] contains a Bundle that represents the state of the container. The exact
87          * details of this Bundle depend on the container this Bundle is describing. This
88          * notification is not in real time and is throttled, so it should not be used to react to
89          * UI changes on the client side.
90          *
91          * UI providers should add [SessionObserverFactory]s to observe UI changes rather than using
92          * this method directly.
93          */
94         fun notifyUiChanged(uiContainerInfo: Bundle)
95 
96         /**
97          * Notifies that the session has been rendered inside the container hosting this session.
98          *
99          * [supportedSignalOptions] specifies the signal options which are supported by the host
100          * container.
101          *
102          * UI providers should add [SessionObserverFactory]s to receive this value rather than using
103          * this method directly. This API is used to notify the [SessionObserver]s associated with
104          * this session about the supported signal options for this session.
105          *
106          * @see [SandboxedUiAdapterSignalOptions]
107          */
108         fun notifySessionRendered(supportedSignalOptions: Set<String>)
109 
110         /**
111          * Close this session, indicating that the remote provider of content should dispose of
112          * associated resources and that the [SessionClient] should not receive further callback
113          * events.
114          */
115         override fun close()
116     }
117 
118     /** The client of a single session that will receive callback events from an active session. */
119     interface SessionClient {
120         /**
121          * Called to report that the session was opened successfully, delivering the [Session]
122          * handle that should be used to notify the session of UI events.
123          */
onSessionOpenednull124         fun onSessionOpened(session: Session)
125 
126         /**
127          * Called to report a terminal error in the session. No further events will be reported to
128          * this [SessionClient] and any further or currently pending calls to the [Session] that may
129          * have been in flight may be ignored.
130          */
131         fun onSessionError(throwable: Throwable)
132 
133         /**
134          * Called when the provider of content would like the UI to be presented at [width] and
135          * [height]. The library tries to get as close a fit as possible whilst staying within the
136          * container's constraints.
137          */
138         fun onResizeRequested(width: Int, height: Int)
139     }
140 }
141