1 /*
2  * Copyright (C) 2019 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 #ifndef _UI_INPUT_INPUTDISPATCHER_INPUTDISPATCHERINTERFACE_H
18 #define _UI_INPUT_INPUTDISPATCHER_INPUTDISPATCHERINTERFACE_H
19 
20 #include <InputListener.h>
21 #include <input/ISetInputWindowsListener.h>
22 #include <unordered_map>
23 
24 namespace android {
25 
26 class InputApplicationHandle;
27 class InputChannel;
28 class InputWindowHandle;
29 
30 /*
31  * Constants used to report the outcome of input event injection.
32  */
33 enum {
34     /* (INTERNAL USE ONLY) Specifies that injection is pending and its outcome is unknown. */
35     INPUT_EVENT_INJECTION_PENDING = -1,
36 
37     /* Injection succeeded. */
38     INPUT_EVENT_INJECTION_SUCCEEDED = 0,
39 
40     /* Injection failed because the injector did not have permission to inject
41      * into the application with input focus. */
42     INPUT_EVENT_INJECTION_PERMISSION_DENIED = 1,
43 
44     /* Injection failed because there were no available input targets. */
45     INPUT_EVENT_INJECTION_FAILED = 2,
46 
47     /* Injection failed due to a timeout. */
48     INPUT_EVENT_INJECTION_TIMED_OUT = 3
49 };
50 
51 /* Notifies the system about input events generated by the input reader.
52  * The dispatcher is expected to be mostly asynchronous. */
53 class InputDispatcherInterface : public virtual RefBase, public InputListenerInterface {
54 protected:
InputDispatcherInterface()55     InputDispatcherInterface() {}
~InputDispatcherInterface()56     virtual ~InputDispatcherInterface() {}
57 
58 public:
59     /* Dumps the state of the input dispatcher.
60      *
61      * This method may be called on any thread (usually by the input manager). */
62     virtual void dump(std::string& dump) = 0;
63 
64     /* Called by the heatbeat to ensures that the dispatcher has not deadlocked. */
65     virtual void monitor() = 0;
66 
67     /**
68      * Wait until dispatcher is idle. That means, there are no further events to be processed,
69      * and all of the policy callbacks have been completed.
70      * Return true if the dispatcher is idle.
71      * Return false if the timeout waiting for the dispatcher to become idle has expired.
72      */
73     virtual bool waitForIdle() = 0;
74 
75     /* Make the dispatcher start processing events.
76      *
77      * The dispatcher will start consuming events from the InputListenerInterface
78      * in the order that they were received.
79      */
80     virtual status_t start() = 0;
81 
82     /* Makes the dispatcher stop processing events. */
83     virtual status_t stop() = 0;
84 
85     /* Injects an input event and optionally waits for sync.
86      * The synchronization mode determines whether the method blocks while waiting for
87      * input injection to proceed.
88      * Returns one of the INPUT_EVENT_INJECTION_XXX constants.
89      *
90      * This method may be called on any thread (usually by the input manager).
91      */
92     virtual int32_t injectInputEvent(const InputEvent* event, int32_t injectorPid,
93                                      int32_t injectorUid, int32_t syncMode,
94                                      std::chrono::milliseconds timeout, uint32_t policyFlags) = 0;
95 
96     /*
97      * Check whether InputEvent actually happened by checking the signature of the event.
98      *
99      * Return nullptr if the event cannot be verified.
100      */
101     virtual std::unique_ptr<VerifiedInputEvent> verifyInputEvent(const InputEvent& event) = 0;
102 
103     /* Sets the list of input windows per display.
104      *
105      * This method may be called on any thread (usually by the input manager).
106      */
107     virtual void setInputWindows(
108             const std::unordered_map<int32_t, std::vector<sp<InputWindowHandle>>>&
109                     handlesPerDisplay) = 0;
110 
111     /* Sets the focused application on the given display.
112      *
113      * This method may be called on any thread (usually by the input manager).
114      */
115     virtual void setFocusedApplication(
116             int32_t displayId, const sp<InputApplicationHandle>& inputApplicationHandle) = 0;
117 
118     /* Sets the focused display.
119      *
120      * This method may be called on any thread (usually by the input manager).
121      */
122     virtual void setFocusedDisplay(int32_t displayId) = 0;
123 
124     /* Sets the input dispatching mode.
125      *
126      * This method may be called on any thread (usually by the input manager).
127      */
128     virtual void setInputDispatchMode(bool enabled, bool frozen) = 0;
129 
130     /* Sets whether input event filtering is enabled.
131      * When enabled, incoming input events are sent to the policy's filterInputEvent
132      * method instead of being dispatched.  The filter is expected to use
133      * injectInputEvent to inject the events it would like to have dispatched.
134      * It should include POLICY_FLAG_FILTERED in the policy flags during injection.
135      */
136     virtual void setInputFilterEnabled(bool enabled) = 0;
137 
138     /**
139      * Set the touch mode state.
140      * Touch mode is a global state that apps may enter / exit based on specific
141      * user interactions with input devices.
142      * If true, the device is in touch mode.
143      */
144     virtual void setInTouchMode(bool inTouchMode) = 0;
145 
146     /* Transfers touch focus from one window to another window.
147      *
148      * Returns true on success.  False if the window did not actually have touch focus.
149      */
150     virtual bool transferTouchFocus(const sp<IBinder>& fromToken, const sp<IBinder>& toToken) = 0;
151 
152     /* Registers input channels that may be used as targets for input events.
153      *
154      * This method may be called on any thread (usually by the input manager).
155      */
156     virtual status_t registerInputChannel(const sp<InputChannel>& inputChannel) = 0;
157 
158     /* Registers input channels to be used to monitor input events.
159      *
160      * Each monitor must target a specific display and will only receive input events sent to that
161      * display. If the monitor is a gesture monitor, it will only receive pointer events on the
162      * targeted display.
163      *
164      * This method may be called on any thread (usually by the input manager).
165      */
166     virtual status_t registerInputMonitor(const sp<InputChannel>& inputChannel, int32_t displayId,
167                                           bool gestureMonitor) = 0;
168 
169     /* Unregister input channels that will no longer receive input events.
170      *
171      * This method may be called on any thread (usually by the input manager).
172      */
173     virtual status_t unregisterInputChannel(const sp<InputChannel>& inputChannel) = 0;
174 
175     /* Allows an input monitor steal the current pointer stream away from normal input windows.
176      *
177      * This method may be called on any thread (usually by the input manager).
178      */
179     virtual status_t pilferPointers(const sp<IBinder>& token) = 0;
180 };
181 
182 } // namespace android
183 
184 #endif // _UI_INPUT_INPUTDISPATCHER_INPUTDISPATCHERINTERFACE_H
185