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"
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.
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.
132  public:
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:376
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:365
flutter::PlatformHandler
Definition: platform_handler.h:33
flutter::PlatformHandler::~PlatformHandler
virtual ~PlatformHandler()
flutter::FlutterWindowsEngine
Definition: flutter_windows_engine.h:90
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:440
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:333
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:401
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:294
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:421
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