| 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 FL_BINARY_MESSENGER_ERROR_ALREADY_RESPONDED,
32 } FlBinaryMessengerError;
33
34 G_MODULE_EXPORT
35 GQuark fl_binary_messenger_codec_error_quark(void) G_GNUC_CONST;
36
37 G_MODULE_EXPORT
38 G_DECLARE_INTERFACE(FlBinaryMessenger,
39 fl_binary_messenger,
40 FL,
41 BINARY_MESSENGER,
42 GObject)
43
44 G_MODULE_EXPORT
45 G_DECLARE_DERIVABLE_TYPE(FlBinaryMessengerResponseHandle,
46 fl_binary_messenger_response_handle,
47 FL,
48 BINARY_MESSENGER_RESPONSE_HANDLE,
49 GObject)
50
51 /**
52 * FlBinaryMessengerMessageHandler:
53 * @messenger: an #FlBinaryMessenger.
54 * @channel: channel message received on.
55 * @message: message content received from Dart.
56 * @response_handle: a handle to respond to the message with.
57 * @user_data: (closure): data provided when registering this handler.
58 *
59 * Function called when platform messages are received. Call
60 * fl_binary_messenger_send_response() to respond to this message. If the
61 * response is not occurring in this callback take a reference to
62 * @response_handle and release that once it has been responded to. Failing to
63 * respond before the last reference to @response_handle is dropped is a
64 * programming error.
65 */
66 typedef void (*FlBinaryMessengerMessageHandler)(
67 FlBinaryMessenger* messenger,
68 const gchar* channel,
69 GBytes* message,
70 FlBinaryMessengerResponseHandle* response_handle,
71 gpointer user_data);
72
73 struct _FlBinaryMessengerInterface {
74 GTypeInterface parent_iface;
75
76 void (*set_message_handler_on_channel)(
77 FlBinaryMessenger* messenger,
78 const gchar* channel,
79 FlBinaryMessengerMessageHandler handler,
80 gpointer user_data,
81 GDestroyNotify destroy_notify);
82
83 gboolean (*send_response)(FlBinaryMessenger* messenger,
84 FlBinaryMessengerResponseHandle* response_handle,
85 GBytes* response,
86 GError** error);
87
88 void (*send_on_channel)(FlBinaryMessenger* messenger,
89 const gchar* channel,
90 GBytes* message,
91 GCancellable* cancellable,
92 GAsyncReadyCallback callback,
93 gpointer user_data);
94
95 GBytes* (*send_on_channel_finish)(FlBinaryMessenger* messenger,
96 GAsyncResult* result,
97 GError** error);
98
99 void (*resize_channel)(FlBinaryMessenger* messenger,
100 const gchar* channel,
101 int64_t new_size);
102
103 void (*set_warns_on_channel_overflow)(FlBinaryMessenger* messenger,
104 const gchar* channel,
105 bool warns);
106
107 void (*shutdown)(FlBinaryMessenger* messenger);
108 };
109
110 struct _FlBinaryMessengerResponseHandleClass {
111 GObjectClass parent_class;
112 };
113
114 /**
115 * FlBinaryMessenger:
116 *
117 * #FlBinaryMessenger is an object that allows sending and receiving of platform
118 * messages with an #FlEngine.
119 */
120
121 /**
122 * FlBinaryMessengerResponseHandle:
123 *
124 * #FlBinaryMessengerResponseHandle is an object used to send responses with.
125 */
126
127 /**
128 * fl_binary_messenger_set_platform_message_handler:
129 * @binary_messenger: an #FlBinaryMessenger.
130 * @channel: channel to listen on.
131 * @handler: (allow-none): function to call when a message is received on this
132 * channel or %NULL to disable a handler
133 * @user_data: (closure): user data to pass to @handler.
134 * @destroy_notify: (allow-none): a function which gets called to free
135 * @user_data, or %NULL.
136 *
137 * Sets the function called when a platform message is received on the given
138 * channel. See #FlBinaryMessengerMessageHandler for details on how to respond
139 * to messages.
140 *
141 * The handler is removed if the channel is closed or is replaced by another
142 * handler, set @destroy_notify if you want to detect this.
143 */
144 void fl_binary_messenger_set_message_handler_on_channel(
145 FlBinaryMessenger* messenger,
146 const gchar* channel,
147 FlBinaryMessengerMessageHandler handler,
148 gpointer user_data,
149 GDestroyNotify destroy_notify);
150
151 /**
152 * fl_binary_messenger_send_response:
153 * @binary_messenger: an #FlBinaryMessenger.
154 * @response_handle: handle that was provided in a
155 * #FlBinaryMessengerMessageHandler.
156 * @response: (allow-none): response to send or %NULL for an empty response.
157 * @error: (allow-none): #GError location to store the error occurring, or %NULL
158 * to ignore. If `error` is not %NULL, `*error` must be initialized (typically
159 * %NULL, but an error from a previous call using GLib error handling is
160 * explicitly valid).
161 *
162 * Responds to a platform message. This function is thread-safe.
163 *
164 * Returns: %TRUE on success.
165 */
166 gboolean fl_binary_messenger_send_response(
167 FlBinaryMessenger* messenger,
168 FlBinaryMessengerResponseHandle* response_handle,
169 GBytes* response,
170 GError** error);
171
172 /**
173 * fl_binary_messenger_send_on_channel:
174 * @binary_messenger: an #FlBinaryMessenger.
175 * @channel: channel to send to.
176 * @message: (allow-none): message buffer to send or %NULL for an empty message.
177 * @cancellable: (allow-none): a #GCancellable or %NULL.
178 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
179 * satisfied.
180 * @user_data: (closure): user data to pass to @callback.
181 *
182 * Asynchronously sends a platform message.
183 */
184 void fl_binary_messenger_send_on_channel(FlBinaryMessenger* messenger,
185 const gchar* channel,
186 GBytes* message,
187 GCancellable* cancellable,
188 GAsyncReadyCallback callback,
189 gpointer user_data);
190
191 /**
192 * fl_binary_messenger_send_on_channel_finish:
193 * @messenger: an #FlBinaryMessenger.
194 * @result: a #GAsyncResult.
195 * @error: (allow-none): #GError location to store the error occurring, or %NULL
196 * to ignore. If `error` is not %NULL, `*error` must be initialized (typically
197 * %NULL, but an error from a previous call using GLib error handling is
198 * explicitly valid).
199 *
200 * Completes request started with fl_binary_messenger_send_on_channel().
201 *
202 * Returns: (transfer full): message response on success or %NULL on error.
203 */
204 GBytes* fl_binary_messenger_send_on_channel_finish(FlBinaryMessenger* messenger,
205 GAsyncResult* result,
206 GError** error);
207
208 /**
209 * fl_binary_messenger_resize_channel:
210 * @binary_messenger: an #FlBinaryMessenger.
211 * @channel: channel to be resize.
212 * @new_size: the new size for the channel buffer.
213 *
214 * Sends a message to the control channel asking to resize a channel buffer.
215 */
216 void fl_binary_messenger_resize_channel(FlBinaryMessenger* messenger,
217 const gchar* channel,
218 int64_t new_size);
219
220 /**
221 * fl_binary_messenger_set_warns_on_channel_overflow:
222 * @messenger: an #FlBinaryMessenger.
223 * @channel: channel to be allowed to overflow silently.
224 * @warns: when false, the channel is expected to overflow and warning messages
225 * will not be shown.
226 *
227 * Sends a message to the control channel asking to allow or disallow a channel
228 * to overflow silently.
229 */
230 void fl_binary_messenger_set_warns_on_channel_overflow(
231 FlBinaryMessenger* messenger,
232 const gchar* channel,
233 bool warns);
234
235 G_END_DECLS
236
237 #endif // FLUTTER_SHELL_PLATFORM_LINUX_PUBLIC_FLUTTER_LINUX_FL_BINARY_MESSENGER_H_
G_DECLARE_DERIVABLE_TYPE
G_BEGIN_DECLS G_DECLARE_DERIVABLE_TYPE(FlAccessibleNode, fl_accessible_node, FL, ACCESSIBLE_NODE, AtkObject)
resize_channel
static void resize_channel(FlBinaryMessenger *messenger, const gchar *channel, int64_t new_size)
Definition: fl_binary_messenger.cc:320
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:255
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:173
send_response
static gboolean send_response(FlBinaryMessenger *messenger, FlBinaryMessengerResponseHandle *response_handle_, GBytes *response, GError **error)
Definition: fl_binary_messenger.cc:210
set_warns_on_channel_overflow
static void set_warns_on_channel_overflow(FlBinaryMessenger *messenger, const gchar *channel, bool warns)
Definition: fl_binary_messenger.cc:345
shutdown
static void shutdown(FlBinaryMessenger *messenger)
Definition: fl_binary_messenger.cc:359
FL
G_MODULE_EXPORT FL
Definition: fl_binary_messenger.h:47
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_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:468
fl_binary_messenger_codec_error_quark
G_MODULE_EXPORT GQuark fl_binary_messenger_codec_error_quark(void) G_GNUC_CONST
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:459
FlBinaryMessengerError
FlBinaryMessengerError
Definition: fl_binary_messenger.h:29
FL_BINARY_MESSENGER_ERROR_ALREADY_RESPONDED
@ FL_BINARY_MESSENGER_ERROR_ALREADY_RESPONDED
Definition: fl_binary_messenger.h:31
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:66
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:435
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:449
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:422
BINARY_MESSENGER_RESPONSE_HANDLE
G_MODULE_EXPORT BINARY_MESSENGER_RESPONSE_HANDLE
Definition: fl_binary_messenger.h:48
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:408
fl_binary_messenger_response_handle
G_MODULE_EXPORT fl_binary_messenger_response_handle
Definition: fl_binary_messenger.h:46
user_data
G_BEGIN_DECLS G_MODULE_EXPORT FlValue gpointer user_data
Definition: fl_event_channel.h:90
error
const uint8_t uint32_t uint32_t GError ** error
Definition: fl_pixel_buffer_texture_test.cc:40
fl_value.h
_FlBinaryMessengerInterface
Definition: fl_binary_messenger.h:73
_FlBinaryMessengerInterface::parent_iface
GTypeInterface parent_iface
Definition: fl_binary_messenger.h:74
_FlBinaryMessengerResponseHandleClass
Definition: fl_binary_messenger.h:110
_FlBinaryMessengerResponseHandleClass::parent_class
GObjectClass parent_class
Definition: fl_binary_messenger.h:111