| Flutter Windows Embedder |

platform_handler.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #ifndef FLUTTER_SHELL_PLATFORM_WINDOWS_PLATFORM_HANDLER_H_
6 #define FLUTTER_SHELL_PLATFORM_WINDOWS_PLATFORM_HANDLER_H_
7
8 #include <Windows.h>
9
10 #include <functional>
11 #include <memory>
12 #include <optional>
13 #include <variant>
14
15 #include "flutter/fml/macros.h"
16 #include "flutter/shell/platform/common/client_wrapper/include/flutter/binary_messenger.h"
17 #include "flutter/shell/platform/common/client_wrapper/include/flutter/method_channel.h"
18 #include "rapidjson/document.h"
19
20 namespace flutter {
21
22 class FlutterWindowsEngine;
23 class ScopedClipboardInterface;
24
25 // Indicates whether an exit request may be canceled by the framework.
26 // These values must be kept in sync with kExitTypeNames in platform_handler.cc
27 enum class AppExitType {
28 required,
29 cancelable,
30 };
31
32 // Handler for internal system channels.
33 class PlatformHandler {
34 public:
35 explicit PlatformHandler(
36 BinaryMessenger* messenger,
37 FlutterWindowsEngine* engine,
38 std::optional<std::function<std::unique_ptr<ScopedClipboardInterface>()>>
39 scoped_clipboard_provider = std::nullopt);
40
41 virtual ~PlatformHandler();
42
43 // String values used for encoding/decoding exit requests.
44 static constexpr char kExitTypeCancelable[] = "cancelable";
45 static constexpr char kExitTypeRequired[] = "required";
46
47 // Send a request to the framework to test if a cancelable exit request
48 // should be canceled or honored. hwnd is std::nullopt for a request to quit
49 // the process, otherwise it holds the HWND of the window that initiated the
50 // quit request.
51 virtual void RequestAppExit(std::optional<HWND> hwnd,
52 std::optional<WPARAM> wparam,
53 std::optional<LPARAM> lparam,
54 AppExitType exit_type,
55 UINT exit_code);
56
57 protected:
58 // Gets plain text from the clipboard and provides it to |result| as the
59 // value in a dictionary with the given |key|.
60 virtual void GetPlainText(
61 std::unique_ptr<MethodResult<rapidjson::Document>> result,
62 std::string_view key);
63
64 // Provides a boolean to |result| as the value in a dictionary at key
65 // "value" representing whether or not the clipboard has a non-empty string.
66 virtual void GetHasStrings(
67 std::unique_ptr<MethodResult<rapidjson::Document>> result);
68
69 // Sets the clipboard's plain text to |text|, and reports the result (either
70 // an error, or null for success) to |result|.
71 virtual void SetPlainText(
72 const std::string& text,
73 std::unique_ptr<MethodResult<rapidjson::Document>> result);
74
75 virtual void SystemSoundPlay(
76 const std::string& sound_type,
77 std::unique_ptr<MethodResult<rapidjson::Document>> result);
78
79 // Handle a request from the framework to exit the application.
80 virtual void SystemExitApplication(
81 AppExitType exit_type,
82 UINT exit_code,
83 std::unique_ptr<MethodResult<rapidjson::Document>> result);
84
85 // Actually quit the application with the provided exit code. hwnd is
86 // std::nullopt for a request to quit the process, otherwise it holds the HWND
87 // of the window that initiated the quit request.
88 virtual void QuitApplication(std::optional<HWND> hwnd,
89 std::optional<WPARAM> wparam,
90 std::optional<LPARAM> lparam,
91 UINT exit_code);
92
93 // Callback from when the cancelable exit request response request is
94 // answered by the framework. hwnd is std::nullopt for a request to quit the
95 // process, otherwise it holds the HWND of the window that initiated the quit
96 // request.
97 virtual void RequestAppExitSuccess(std::optional<HWND> hwnd,
98 std::optional<WPARAM> wparam,
99 std::optional<LPARAM> lparam,
100 const rapidjson::Document* result,
101 UINT exit_code);
102
103 // A error type to use for error responses.
104 static constexpr char kClipboardError[] = "Clipboard error";
105
106 static constexpr char kSoundTypeAlert[] = "SystemSoundType.alert";
107
108 private:
109 // Called when a method is called on |channel_|;
110 void HandleMethodCall(
111 const MethodCall<rapidjson::Document>& method_call,
112 std::unique_ptr<MethodResult<rapidjson::Document>> result);
113
114 // The MethodChannel used for communication with the Flutter engine.
115 std::unique_ptr<MethodChannel<rapidjson::Document>> channel_;
116
117 // A reference to the Flutter engine.
118 FlutterWindowsEngine* engine_;
119
120 // A scoped clipboard provider that can be passed in for mocking in tests.
121 // Use this to acquire clipboard in each operation to avoid blocking clipboard
122 // unnecessarily. See flutter/flutter#103205.
123 std::function<std::unique_ptr<ScopedClipboardInterface>()>
124 scoped_clipboard_provider_;
125
126 FML_DISALLOW_COPY_AND_ASSIGN(PlatformHandler);
127 };
128
129 // A public interface for ScopedClipboard, so that it can be injected into
130 // PlatformHandler.
131 class ScopedClipboardInterface {
132 public:
133 virtual ~ScopedClipboardInterface(){};
134
135 // Attempts to open the clipboard for the given window, returning the error
136 // code in the case of failure and 0 otherwise.
137 virtual int Open(HWND window) = 0;
138
139 // Returns true if there is string data available to get.
140 virtual bool HasString() = 0;
141
142 // Returns string data from the clipboard.
143 //
144 // If getting a string fails, returns the error code.
145 //
146 // Open(...) must have succeeded to call this method.
147 virtual std::variant<std::wstring, int> GetString() = 0;
148
149 // Sets the string content of the clipboard, returning the error code on
150 // failure and 0 otherwise.
151 //
152 // Open(...) must have succeeded to call this method.
153 virtual int SetString(const std::wstring string) = 0;
154 };
155
156 } // namespace flutter
157
158 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_PLATFORM_HANDLER_H_
flutter::PlatformHandler::SystemExitApplication
virtual void SystemExitApplication(AppExitType exit_type, UINT exit_code, std::unique_ptr< MethodResult< rapidjson::Document >> result)
Definition: platform_handler.cc:370
flutter::AppExitType::cancelable
@ cancelable
flutter::AppExitType
AppExitType
Definition: platform_handler.h:27
flutter::PlatformHandler::SystemSoundPlay
virtual void SystemSoundPlay(const std::string &sound_type, std::unique_ptr< MethodResult< rapidjson::Document >> result)
Definition: platform_handler.cc:359
flutter::PlatformHandler
Definition: platform_handler.h:33
flutter::PlatformHandler::~PlatformHandler
virtual ~PlatformHandler()
flutter::FlutterWindowsEngine
Definition: flutter_windows_engine.h:78
flutter::PlatformHandler::QuitApplication
virtual void QuitApplication(std::optional< HWND > hwnd, std::optional< WPARAM > wparam, std::optional< LPARAM > lparam, UINT exit_code)
Definition: platform_handler.cc:434
flutter::ScopedClipboardInterface::SetString
virtual int SetString(const std::wstring string)=0
binary_messenger.h
flutter::PlatformHandler::SetPlainText
virtual void SetPlainText(const std::string &text, std::unique_ptr< MethodResult< rapidjson::Document >> result)
Definition: platform_handler.cc:329
flutter::ScopedClipboardInterface::GetString
virtual std::variant< std::wstring, int > GetString()=0
flutter::PlatformHandler::kExitTypeRequired
static constexpr char kExitTypeRequired[]
Definition: platform_handler.h:45
flutter::PlatformHandler::RequestAppExit
virtual void RequestAppExit(std::optional< HWND > hwnd, std::optional< WPARAM > wparam, std::optional< LPARAM > lparam, AppExitType exit_type, UINT exit_code)
Definition: platform_handler.cc:395
flutter::BinaryMessenger
Definition: binary_messenger.h:28
flutter::ScopedClipboardInterface::Open
virtual int Open(HWND window)=0
text
std::u16string text
Definition: keyboard_unittests.cc:332
flutter::MethodCall
Definition: method_call.h:18
flutter::PlatformHandler::kExitTypeCancelable
static constexpr char kExitTypeCancelable[]
Definition: platform_handler.h:44
flutter::PlatformHandler::kClipboardError
static constexpr char kClipboardError[]
Definition: platform_handler.h:104
flutter::ScopedClipboardInterface::HasString
virtual bool HasString()=0
flutter::ScopedClipboardInterface::~ScopedClipboardInterface
virtual ~ScopedClipboardInterface()
Definition: platform_handler.h:133
flutter
Definition: accessibility_bridge_windows.cc:11
flutter::PlatformHandler::GetHasStrings
virtual void GetHasStrings(std::unique_ptr< MethodResult< rapidjson::Document >> result)
Definition: platform_handler.cc:292
flutter::MethodResult
Definition: method_result.h:17
method_channel.h
flutter::ScopedClipboardInterface
Definition: platform_handler.h:131
flutter::PlatformHandler::RequestAppExitSuccess
virtual void RequestAppExitSuccess(std::optional< HWND > hwnd, std::optional< WPARAM > wparam, std::optional< LPARAM > lparam, const rapidjson::Document *result, UINT exit_code)
Definition: platform_handler.cc:415
flutter::PlatformHandler::kSoundTypeAlert
static constexpr char kSoundTypeAlert[]
Definition: platform_handler.h:106
key
int key
Definition: keyboard_key_handler_unittests.cc:114
flutter::AppExitType::required
@ required
flutter::PlatformHandler::PlatformHandler
PlatformHandler(BinaryMessenger *messenger, FlutterWindowsEngine *engine, std::optional< std::function< std::unique_ptr< ScopedClipboardInterface >()>> scoped_clipboard_provider=std::nullopt)
Definition: platform_handler.cc:222
flutter::PlatformHandler::GetPlainText
virtual void GetPlainText(std::unique_ptr< MethodResult< rapidjson::Document >> result, std::string_view key)
Definition: platform_handler.cc:248