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 /**
17  * @addtogroup NativeActivity Native Activity
18  * @{
19  */
20 /**
21  * @file surface_control_input_receiver.h
22  */
23 
24 #pragma once
25 
26 #include <stdint.h>
27 #include <android/input.h>
28 #include <android/surface_control.h>
29 #include <android/input_transfer_token_jni.h>
30 
31 __BEGIN_DECLS
32 
33 /**
34  * The AInputReceiver_onMotionEvent callback is invoked when the registered input channel receives
35  * a motion event.
36  *
37  * \param context Optional context provided by the client that is passed when creating the
38  * AInputReceiverCallbacks.
39  *
40  * \param motionEvent The motion event. This must be released with AInputEvent_release.
41  *
42  * Available since API level 35.
43  */
44 typedef bool (*AInputReceiver_onMotionEvent)(void *_Null_unspecified context,
45                                              AInputEvent *_Nonnull motionEvent)
46                                             __INTRODUCED_IN(__ANDROID_API_V__);
47 /**
48  * The AInputReceiver_onKeyEvent callback is invoked when the registered input channel receives
49  * a key event.
50  *
51  * \param context Optional context provided by the client that is passed when creating the
52  * AInputReceiverCallbacks.
53  *
54  * \param keyEvent The key event. This must be released with AInputEvent_release.
55  *
56  * Available since API level 35.
57  */
58 typedef bool (*AInputReceiver_onKeyEvent)(void *_Null_unspecified context,
59                                           AInputEvent *_Nonnull keyEvent)
60                                           __INTRODUCED_IN(__ANDROID_API_V__);
61 
62 struct AInputReceiverCallbacks;
63 
64 struct AInputReceiver;
65 
66 /**
67  * The InputReceiver that holds the reference to the registered input channel. This must be released
68  * using AInputReceiver_release
69  *
70  * Available since API level 35.
71  */
72 typedef struct AInputReceiver AInputReceiver __INTRODUCED_IN(__ANDROID_API_V__);
73 
74 /**
75  * Registers an input receiver for an ASurfaceControl that will receive batched input event. For
76  * those events that are batched, the invocation will happen once per AChoreographer frame, and
77  * other input events will be delivered immediately.
78  *
79  * This is different from AInputReceiver_createUnbatchedInputReceiver in that the input events are
80  * received batched. The caller must invoke AInputReceiver_release to clean up the resources when
81  * no longer needing to use the input receiver.
82  *
83  * \param aChoreographer         The AChoreographer used for batching. This should match the
84  *                               rendering AChoreographer.
85  * \param hostInputTransferToken The host token to link the embedded. This is used to handle
86  *                               transferring touch gesture from host to embedded and for ANRs
87  *                               to ensure the host receives the ANR if any issues with
88  *                               touch on the embedded. This can be retrieved for the host window
89  *                               by calling AttachedSurfaceControl#getInputTransferToken()
90  * \param aSurfaceControl        The ASurfaceControl to register the InputChannel for
91  * \param aInputReceiverCallbacks The SurfaceControlInputReceiver that will receive the input events
92  *
93  * Returns the reference to AInputReceiver to clean up resources when done.
94  *
95  * Available since API level 35.
96  */
97 AInputReceiver* _Nonnull
98 AInputReceiver_createBatchedInputReceiver(AChoreographer* _Nonnull aChoreographer,
99                                         const AInputTransferToken* _Nonnull hostInputTransferToken,
100                                         const ASurfaceControl* _Nonnull aSurfaceControl,
101                                         AInputReceiverCallbacks* _Nonnull aInputReceiverCallbacks)
102                                         __INTRODUCED_IN(__ANDROID_API_V__);
103 
104 /**
105  * Registers an input receiver for an ASurfaceControl that will receive every input event.
106  * This is different from AInputReceiver_createBatchedInputReceiver in that the input events are
107  * received unbatched. The caller must invoke AInputReceiver_release to clean up the resources when
108  * no longer needing to use the input receiver.
109  *
110  * \param aLooper                The looper to use when invoking callbacks.
111  * \param hostInputTransferToken The host token to link the embedded. This is used to handle
112  *                               transferring touch gesture from host to embedded and for ANRs
113  *                               to ensure the host receives the ANR if any issues with
114  *                               touch on the embedded. This can be retrieved for the host window
115  *                               by calling AttachedSurfaceControl#getInputTransferToken()
116  * \param aSurfaceControl        The ASurfaceControl to register the InputChannel for
117  * \param aInputReceiverCallbacks The SurfaceControlInputReceiver that will receive the input events
118  *
119  * Returns the reference to AInputReceiver to clean up resources when done.
120  *
121  * Available since API level 35.
122  */
123 AInputReceiver* _Nonnull
124 AInputReceiver_createUnbatchedInputReceiver(ALooper* _Nonnull aLooper,
125                                          const AInputTransferToken* _Nonnull hostInputTransferToken,
126                                          const ASurfaceControl* _Nonnull aSurfaceControl,
127                                          AInputReceiverCallbacks* _Nonnull aInputReceiverCallbacks)
128                                          __INTRODUCED_IN(__ANDROID_API_V__);
129 
130 /**
131  * Returns the AInputTransferToken that can be used to transfer touch gesture to or from other
132  * windows. This InputTransferToken is associated with the SurfaceControl that registered an input
133  * receiver and can be used with the host token for things like transfer touch gesture via
134  * WindowManager#transferTouchGesture().
135  *
136  * This must be released with AInputTransferToken_release.
137  *
138  * \param aInputReceiver The inputReceiver object to retrieve the AInputTransferToken for.
139  *
140  * Available since API level 35.
141  */
142 const AInputTransferToken *_Nonnull
143 AInputReceiver_getInputTransferToken(AInputReceiver *_Nonnull aInputReceiver)
144         __INTRODUCED_IN(__ANDROID_API_V__);
145 
146 /**
147  * Unregisters the input channel and deletes the AInputReceiver. This must be called on the same
148  * looper thread it was created with.
149  *
150  * \param aInputReceiver The inputReceiver object to release.
151  *
152  * Available since API level 35.
153  */
154 void
155 AInputReceiver_release(AInputReceiver *_Nullable aInputReceiver) __INTRODUCED_IN(__ANDROID_API_V__);
156 
157 /**
158  * Creates a AInputReceiverCallbacks object that is used when registering for an AInputReceiver.
159  * This must be released using AInputReceiverCallbacks_release
160  *
161  * \param context Optional context provided by the client that will be passed into the callbacks.
162  *
163  * Available since API level 35.
164  */
165 AInputReceiverCallbacks* _Nonnull AInputReceiverCallbacks_create(void* _Nullable context)
166                                                         __INTRODUCED_IN(__ANDROID_API_V__);
167 
168 /**
169  * Releases the AInputReceiverCallbacks. This must be called on the same
170  * looper thread the AInputReceiver was created with. The receiver will not invoke any callbacks
171  * once it's been released.
172  *
173  * Available since API level 35
174  */
175 void AInputReceiverCallbacks_release(AInputReceiverCallbacks* _Nullable callbacks)
176                                      __INTRODUCED_IN(__ANDROID_API_V__);
177 
178 /**
179  * Sets a AInputReceiver_onMotionEvent callback for an AInputReceiverCallbacks
180  *
181  * \param callbacks The callback object to set the motion event on.
182  * \param onMotionEvent The motion event that will be invoked
183  *
184  * Available since API level 35.
185  */
186 void AInputReceiverCallbacks_setMotionEventCallback(AInputReceiverCallbacks* _Nonnull callbacks,
187                                                 AInputReceiver_onMotionEvent _Nonnull onMotionEvent)
188                                                 __INTRODUCED_IN(__ANDROID_API_V__);
189 
190 /**
191  * Sets a AInputReceiver_onKeyEvent callback for an AInputReceiverCallbacks
192  *
193  * \param callbacks The callback object to set the motion event on.
194  * \param onMotionEvent The key event that will be invoked
195  *
196  * Available since API level 35.
197  */
198 void AInputReceiverCallbacks_setKeyEventCallback(AInputReceiverCallbacks* _Nonnull callbacks,
199                                                  AInputReceiver_onKeyEvent _Nonnull onKeyEvent)
200                                                  __INTRODUCED_IN(__ANDROID_API_V__);
201 
202 __END_DECLS
203