Flutter Linux Embedder
fl_binary_messenger.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_LINUX_PUBLIC_FLUTTER_LINUX_FL_BINARY_MESSENGER_H_
6 #define FLUTTER_SHELL_PLATFORM_LINUX_PUBLIC_FLUTTER_LINUX_FL_BINARY_MESSENGER_H_
7 
8 #if !defined(__FLUTTER_LINUX_INSIDE__) && !defined(FLUTTER_LINUX_COMPILATION)
9 #error "Only <flutter_linux/flutter_linux.h> can be included directly."
10 #endif
11 
12 #include "fl_value.h"
13 
14 #include <gio/gio.h>
15 #include <glib-object.h>
16 #include <gmodule.h>
17 
18 G_BEGIN_DECLS
19 
20 /**
21  * FlBinaryMessengerError:
22  * @FL_BINARY_MESSENGER_ERROR_ALREADY_RESPONDED: unable to send response, this
23  * message has already been responded to.
24  *
25  * Errors for #FlBinaryMessenger objects to set on failures.
26  */
27 #define FL_BINARY_MESSENGER_ERROR fl_binary_messenger_codec_error_quark()
28 
29 typedef enum {
30  // Part of the public API, so fixing the name is a breaking change.
31  // NOLINTNEXTLINE(readability-identifier-naming)
34 
35 G_MODULE_EXPORT
36 GQuark fl_binary_messenger_codec_error_quark(void) G_GNUC_CONST;
37 
38 G_MODULE_EXPORT
39 G_DECLARE_INTERFACE(FlBinaryMessenger,
40  fl_binary_messenger,
41  FL,
42  BINARY_MESSENGER,
43  GObject)
44 
45 G_MODULE_EXPORT
46 G_DECLARE_DERIVABLE_TYPE(FlBinaryMessengerResponseHandle,
48  FL,
50  GObject)
51 
52 /**
53  * FlBinaryMessengerMessageHandler:
54  * @messenger: an #FlBinaryMessenger.
55  * @channel: channel message received on.
56  * @message: message content received from Dart.
57  * @response_handle: a handle to respond to the message with.
58  * @user_data: (closure): data provided when registering this handler.
59  *
60  * Function called when platform messages are received. Call
61  * fl_binary_messenger_send_response() to respond to this message. If the
62  * response is not occurring in this callback take a reference to
63  * @response_handle and release that once it has been responded to. Failing to
64  * respond before the last reference to @response_handle is dropped is a
65  * programming error.
66  */
68  FlBinaryMessenger* messenger,
69  const gchar* channel,
70  GBytes* message,
71  FlBinaryMessengerResponseHandle* response_handle,
72  gpointer user_data);
73 
75  GTypeInterface parent_iface;
76 
78  FlBinaryMessenger* messenger,
79  const gchar* channel,
81  gpointer user_data,
82  GDestroyNotify destroy_notify);
83 
84  gboolean (*send_response)(FlBinaryMessenger* messenger,
85  FlBinaryMessengerResponseHandle* response_handle,
86  GBytes* response,
87  GError** error);
88 
89  void (*send_on_channel)(FlBinaryMessenger* messenger,
90  const gchar* channel,
91  GBytes* message,
92  GCancellable* cancellable,
93  GAsyncReadyCallback callback,
94  gpointer user_data);
95 
96  GBytes* (*send_on_channel_finish)(FlBinaryMessenger* messenger,
97  GAsyncResult* result,
98  GError** error);
99 
100  void (*resize_channel)(FlBinaryMessenger* messenger,
101  const gchar* channel,
102  int64_t new_size);
103 
104  void (*set_warns_on_channel_overflow)(FlBinaryMessenger* messenger,
105  const gchar* channel,
106  bool warns);
107 
108  void (*shutdown)(FlBinaryMessenger* messenger);
109 };
110 
112  GObjectClass parent_class;
113 };
114 
115 /**
116  * FlBinaryMessenger:
117  *
118  * #FlBinaryMessenger is an object that allows sending and receiving of platform
119  * messages with an #FlEngine.
120  */
121 
122 /**
123  * FlBinaryMessengerResponseHandle:
124  *
125  * #FlBinaryMessengerResponseHandle is an object used to send responses with.
126  */
127 
128 /**
129  * fl_binary_messenger_set_platform_message_handler:
130  * @binary_messenger: an #FlBinaryMessenger.
131  * @channel: channel to listen on.
132  * @handler: (allow-none): function to call when a message is received on this
133  * channel or %NULL to disable a handler
134  * @user_data: (closure): user data to pass to @handler.
135  * @destroy_notify: (allow-none): a function which gets called to free
136  * @user_data, or %NULL.
137  *
138  * Sets the function called when a platform message is received on the given
139  * channel. See #FlBinaryMessengerMessageHandler for details on how to respond
140  * to messages.
141  *
142  * The handler is removed if the channel is closed or is replaced by another
143  * handler, set @destroy_notify if you want to detect this.
144  */
146  FlBinaryMessenger* messenger,
147  const gchar* channel,
149  gpointer user_data,
150  GDestroyNotify destroy_notify);
151 
152 /**
153  * fl_binary_messenger_send_response:
154  * @binary_messenger: an #FlBinaryMessenger.
155  * @response_handle: handle that was provided in a
156  * #FlBinaryMessengerMessageHandler.
157  * @response: (allow-none): response to send or %NULL for an empty response.
158  * @error: (allow-none): #GError location to store the error occurring, or %NULL
159  * to ignore.
160  *
161  * Responds to a platform message. This function is thread-safe.
162  *
163  * Returns: %TRUE on success.
164  */
166  FlBinaryMessenger* messenger,
167  FlBinaryMessengerResponseHandle* response_handle,
168  GBytes* response,
169  GError** error);
170 
171 /**
172  * fl_binary_messenger_send_on_channel:
173  * @binary_messenger: an #FlBinaryMessenger.
174  * @channel: channel to send to.
175  * @message: (allow-none): message buffer to send or %NULL for an empty message.
176  * @cancellable: (allow-none): a #GCancellable or %NULL.
177  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
178  * satisfied.
179  * @user_data: (closure): user data to pass to @callback.
180  *
181  * Asynchronously sends a platform message.
182  */
183 void fl_binary_messenger_send_on_channel(FlBinaryMessenger* messenger,
184  const gchar* channel,
185  GBytes* message,
186  GCancellable* cancellable,
187  GAsyncReadyCallback callback,
188  gpointer user_data);
189 
190 /**
191  * fl_binary_messenger_send_on_channel_finish:
192  * @messenger: an #FlBinaryMessenger.
193  * @result: a #GAsyncResult.
194  * @error: (allow-none): #GError location to store the error occurring, or %NULL
195  * to ignore.
196  *
197  * Completes request started with fl_binary_messenger_send_on_channel().
198  *
199  * Returns: (transfer full): message response on success or %NULL on error.
200  */
201 GBytes* fl_binary_messenger_send_on_channel_finish(FlBinaryMessenger* messenger,
202  GAsyncResult* result,
203  GError** error);
204 
205 /**
206  * fl_binary_messenger_resize_channel:
207  * @binary_messenger: an #FlBinaryMessenger.
208  * @channel: channel to be resize.
209  * @new_size: the new size for the channel buffer.
210  *
211  * Sends a message to the control channel asking to resize a channel buffer.
212  */
213 void fl_binary_messenger_resize_channel(FlBinaryMessenger* messenger,
214  const gchar* channel,
215  int64_t new_size);
216 
217 /**
218  * fl_binary_messenger_set_warns_on_channel_overflow:
219  * @messenger: an #FlBinaryMessenger.
220  * @channel: channel to be allowed to overflow silently.
221  * @warns: when false, the channel is expected to overflow and warning messages
222  * will not be shown.
223  *
224  * Sends a message to the control channel asking to allow or disallow a channel
225  * to overflow silently.
226  */
228  FlBinaryMessenger* messenger,
229  const gchar* channel,
230  bool warns);
231 
232 G_END_DECLS
233 
234 #endif // FLUTTER_SHELL_PLATFORM_LINUX_PUBLIC_FLUTTER_LINUX_FL_BINARY_MESSENGER_H_
G_DECLARE_DERIVABLE_TYPE
G_DECLARE_DERIVABLE_TYPE(FlAccessibleNode, fl_accessible_node, FL, ACCESSIBLE_NODE, AtkObject)
_FlBinaryMessengerInterface
Definition: fl_binary_messenger.h:74
send_response
static gboolean send_response(FlBinaryMessenger *messenger, FlBinaryMessengerResponseHandle *response_handle_, GBytes *response, GError **error)
Definition: fl_binary_messenger.cc:222
_FlBinaryMessengerInterface::parent_iface
GTypeInterface parent_iface
Definition: fl_binary_messenger.h:75
fl_binary_messenger_send_on_channel_finish
GBytes * fl_binary_messenger_send_on_channel_finish(FlBinaryMessenger *messenger, GAsyncResult *result, GError **error)
Definition: fl_binary_messenger.cc:457
fl_binary_messenger_set_warns_on_channel_overflow
void fl_binary_messenger_set_warns_on_channel_overflow(FlBinaryMessenger *messenger, const gchar *channel, bool warns)
Definition: fl_binary_messenger.cc:476
shutdown
static void shutdown(FlBinaryMessenger *messenger)
Definition: fl_binary_messenger.cc:367
user_data
FlKeyEvent uint64_t FlKeyResponderAsyncCallback gpointer user_data
Definition: fl_key_channel_responder.cc:121
_FlBinaryMessengerResponseHandleClass::parent_class
GObjectClass parent_class
Definition: fl_binary_messenger.h:112
fl_binary_messenger_send_response
gboolean fl_binary_messenger_send_response(FlBinaryMessenger *messenger, FlBinaryMessengerResponseHandle *response_handle, GBytes *response, GError **error)
Definition: fl_binary_messenger.cc:430
send_on_channel
static void send_on_channel(FlBinaryMessenger *messenger, const gchar *channel, GBytes *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
Definition: fl_binary_messenger.cc:267
fl_binary_messenger_send_on_channel
void fl_binary_messenger_send_on_channel(FlBinaryMessenger *messenger, const gchar *channel, GBytes *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
Definition: fl_binary_messenger.cc:443
_FlBinaryMessengerResponseHandleClass
Definition: fl_binary_messenger.h:111
resize_channel
static void resize_channel(FlBinaryMessenger *messenger, const gchar *channel, int64_t new_size)
Definition: fl_binary_messenger.cc:328
fl_binary_messenger_set_message_handler_on_channel
void fl_binary_messenger_set_message_handler_on_channel(FlBinaryMessenger *messenger, const gchar *channel, FlBinaryMessengerMessageHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_binary_messenger.cc:416
FlBinaryMessengerMessageHandler
G_MODULE_EXPORT GObject typedef void(* FlBinaryMessengerMessageHandler)(FlBinaryMessenger *messenger, const gchar *channel, GBytes *message, FlBinaryMessengerResponseHandle *response_handle, gpointer user_data)
Definition: fl_binary_messenger.h:67
FlBinaryMessengerError
FlBinaryMessengerError
Definition: fl_binary_messenger.h:29
result
GAsyncResult * result
Definition: fl_text_input_plugin.cc:106
fl_binary_messenger_codec_error_quark
G_MODULE_EXPORT GQuark fl_binary_messenger_codec_error_quark(void) G_GNUC_CONST
FL_BINARY_MESSENGER_ERROR_ALREADY_RESPONDED
@ FL_BINARY_MESSENGER_ERROR_ALREADY_RESPONDED
Definition: fl_binary_messenger.h:32
FL
G_MODULE_EXPORT FL
Definition: fl_binary_messenger.h:48
fl_value.h
error
const uint8_t uint32_t uint32_t GError ** error
Definition: fl_pixel_buffer_texture_test.cc:40
fl_binary_messenger_response_handle
G_MODULE_EXPORT fl_binary_messenger_response_handle
Definition: fl_binary_messenger.h:47
BINARY_MESSENGER_RESPONSE_HANDLE
G_MODULE_EXPORT BINARY_MESSENGER_RESPONSE_HANDLE
Definition: fl_binary_messenger.h:49
callback
FlKeyEvent uint64_t FlKeyResponderAsyncCallback callback
Definition: fl_key_channel_responder.cc:120
set_message_handler_on_channel
static void set_message_handler_on_channel(FlBinaryMessenger *messenger, const gchar *channel, FlBinaryMessengerMessageHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_binary_messenger.cc:185
set_warns_on_channel_overflow
static void set_warns_on_channel_overflow(FlBinaryMessenger *messenger, const gchar *channel, bool warns)
Definition: fl_binary_messenger.cc:353
G_DECLARE_INTERFACE
G_MODULE_EXPORT G_DECLARE_INTERFACE(FlBinaryMessenger, fl_binary_messenger, FL, BINARY_MESSENGER, GObject) G_MODULE_EXPORT G_DECLARE_DERIVABLE_TYPE(FlBinaryMessengerResponseHandle
fl_binary_messenger_resize_channel
void fl_binary_messenger_resize_channel(FlBinaryMessenger *messenger, const gchar *channel, int64_t new_size)
Definition: fl_binary_messenger.cc:467