Flutter Linux Embedder
fl_basic_message_channel.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_BASIC_MESSAGE_CHANNEL_H_
6 #define FLUTTER_SHELL_PLATFORM_LINUX_PUBLIC_FLUTTER_LINUX_FL_BASIC_MESSAGE_CHANNEL_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 <gio/gio.h>
13 #include <glib-object.h>
14 #include <gmodule.h>
15 
16 #include "fl_binary_messenger.h"
17 #include "fl_message_codec.h"
18 
19 G_BEGIN_DECLS
20 
21 G_MODULE_EXPORT
22 G_DECLARE_FINAL_TYPE(FlBasicMessageChannel,
23  fl_basic_message_channel,
24  FL,
25  BASIC_MESSAGE_CHANNEL,
26  GObject)
27 
28 G_MODULE_EXPORT
29 G_DECLARE_FINAL_TYPE(FlBasicMessageChannelResponseHandle,
31  FL,
33  GObject)
34 
35 /**
36  * FlBasicMessageChannel:
37  *
38  * #FlBasicMessageChannel is an object that allows sending and receiving
39  * messages to/from Dart code over platform channels.
40  *
41  * The following example shows how to send messages on a channel:
42  *
43  * |[<!-- language="C" -->
44  * static FlBasicMessageChannel *channel = NULL;
45  *
46  * static void message_cb (FlBasicMessageChannel* channel,
47  * FlValue* message,
48  * FlBasicMessageChannelResponseHandle* response_handle,
49  * gpointer user_data) {
50  * g_autoptr(FlValue) response = handle_message (message);
51  * g_autoptr(GError) error = NULL;
52  * if (!fl_basic_message_channel_respond (channel, response_handle, response,
53  * &error))
54  * g_warning ("Failed to send channel response: %s", error->message);
55  * }
56  *
57  * static void message_response_cb (GObject *object,
58  * GAsyncResult *result,
59  * gpointer user_data) {
60  * g_autoptr(GError) error = NULL;
61  * g_autoptr(FlValue) response =
62  * fl_basic_message_channel_send_finish (FL_BASIC_MESSAGE_CHANNEL (object),
63  * result, &error);
64  * if (response == NULL) {
65  * g_warning ("Failed to send message: %s", error->message);
66  * return;
67  * }
68  *
69  * handle_response (response);
70  * }
71  *
72  * static void setup_channel () {
73  * g_autoptr(FlStandardMessageCodec) codec = fl_standard_message_codec_new ();
74  * channel = fl_basic_message_channel_new (messenger, "flutter/foo",
75  * FL_MESSAGE_CODEC (codec));
76  * fl_basic_message_channel_set_message_handler (channel, message_cb, NULL,
77  * NULL);
78  *
79  * g_autoptr(FlValue) message = fl_value_new_string ("Hello World");
80  * fl_basic_message_channel_send (channel, message, NULL,
81  * message_response_cb, NULL);
82  * }
83  * ]|
84  *
85  * #FlBasicMessageChannel matches the BasicMessageChannel class in the Flutter
86  * services library.
87  */
88 
89 /**
90  * FlBasicMessageChannelResponseHandle:
91  *
92  * #FlBasicMessageChannelResponseHandle is an object used to send responses
93  * with.
94  */
95 
96 /**
97  * FlBasicMessageChannelMessageHandler:
98  * @channel: an #FlBasicMessageChannel.
99  * @message: message received.
100  * @response_handle: a handle to respond to the message with.
101  * @user_data: (closure): data provided when registering this handler.
102  *
103  * Function called when a message is received. Call
104  * fl_basic_message_channel_respond() to respond to this message. If the
105  * response is not occurring in this callback take a reference to
106  * @response_handle and release that once it has been responded to. Failing to
107  * respond before the last reference to @response_handle is dropped is a
108  * programming error.
109  */
111  FlBasicMessageChannel* channel,
112  FlValue* message,
113  FlBasicMessageChannelResponseHandle* response_handle,
114  gpointer user_data);
115 
116 /**
117  * fl_basic_message_channel_new:
118  * @messenger: an #FlBinaryMessenger.
119  * @name: a channel name.
120  * @codec: the message codec.
121  *
122  * Creates a basic message channel. @codec must match the codec used on the Dart
123  * end of the channel.
124  *
125  * Returns: a new #FlBasicMessageChannel.
126  */
127 FlBasicMessageChannel* fl_basic_message_channel_new(
128  FlBinaryMessenger* messenger,
129  const gchar* name,
130  FlMessageCodec* codec);
131 
132 /**
133  * fl_basic_message_channel_set_message_handler:
134  * @channel: an #FlBasicMessageChannel.
135  * @handler: (allow-none): function to call when a message is received on this
136  * channel or %NULL to disable the handler.
137  * @user_data: (closure): user data to pass to @handler.
138  * @destroy_notify: (allow-none): a function which gets called to free
139  * @user_data, or %NULL.
140  *
141  * Sets the function called when a message is received from the Dart side of the
142  * channel. See #FlBasicMessageChannelMessageHandler for details on how to
143  * respond to messages.
144  *
145  * The handler is removed if the channel is closed or is replaced by another
146  * handler, set @destroy_notify if you want to detect this.
147  */
149  FlBasicMessageChannel* channel,
151  gpointer user_data,
152  GDestroyNotify destroy_notify);
153 
154 /**
155  * fl_basic_message_channel_respond:
156  * @channel: an #FlBasicMessageChannel.
157  * @response_handle: handle that was provided in a
158  * #FlBasicMessageChannelMessageHandler.
159  * @message: (allow-none): message response to send or %NULL for an empty
160  * response.
161  * @error: (allow-none): #GError location to store the error occurring, or %NULL
162  * to ignore.
163  *
164  * Responds to a message.
165  *
166  * Returns: %TRUE on success.
167  */
169  FlBasicMessageChannel* channel,
170  FlBasicMessageChannelResponseHandle* response_handle,
171  FlValue* message,
172  GError** error);
173 
174 /**
175  * fl_basic_message_channel_send:
176  * @channel: an #FlBasicMessageChannel.
177  * @message: (allow-none): message to send, must match what the #FlMessageCodec
178  * supports.
179  * @cancellable: (allow-none): a #GCancellable or %NULL.
180  * @callback: (scope async): (allow-none): a #GAsyncReadyCallback to call when
181  * the request is satisfied or %NULL to ignore the response.
182  * @user_data: (closure): user data to pass to @callback.
183  *
184  * Asynchronously sends a message.
185  */
186 void fl_basic_message_channel_send(FlBasicMessageChannel* channel,
187  FlValue* message,
188  GCancellable* cancellable,
189  GAsyncReadyCallback callback,
190  gpointer user_data);
191 
192 /**
193  * fl_basic_message_channel_send_finish:
194  * @channel: an #FlBasicMessageChannel.
195  * @result: a #GAsyncResult.
196  * @error: (allow-none): #GError location to store the error occurring, or %NULL
197  * to ignore.
198  *
199  * Completes request started with fl_basic_message_channel_send().
200  *
201  * Returns: message response on success or %NULL on error.
202  */
203 FlValue* fl_basic_message_channel_send_finish(FlBasicMessageChannel* channel,
204  GAsyncResult* result,
205  GError** error);
206 
207 G_END_DECLS
208 
209 #endif // FLUTTER_SHELL_PLATFORM_LINUX_PUBLIC_FLUTTER_LINUX_FL_BASIC_MESSAGE_CHANNEL_H_
G_DECLARE_FINAL_TYPE
G_BEGIN_DECLS G_MODULE_EXPORT G_DECLARE_FINAL_TYPE(FlBasicMessageChannel, fl_basic_message_channel, FL, BASIC_MESSAGE_CHANNEL, GObject) G_MODULE_EXPORT G_DECLARE_FINAL_TYPE(FlBasicMessageChannelResponseHandle
fl_basic_message_channel_send
void fl_basic_message_channel_send(FlBasicMessageChannel *channel, FlValue *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
Definition: fl_basic_message_channel.cc:226
fl_basic_message_channel_respond
gboolean fl_basic_message_channel_respond(FlBasicMessageChannel *channel, FlBasicMessageChannelResponseHandle *response_handle, FlValue *message, GError **error)
Definition: fl_basic_message_channel.cc:204
FlBasicMessageChannelMessageHandler
G_BEGIN_DECLS G_MODULE_EXPORT GObject typedef void(* FlBasicMessageChannelMessageHandler)(FlBasicMessageChannel *channel, FlValue *message, FlBasicMessageChannelResponseHandle *response_handle, gpointer user_data)
Definition: fl_basic_message_channel.h:110
FlValue
typedefG_BEGIN_DECLS struct _FlValue FlValue
Definition: fl_value.h:42
fl_basic_message_channel_send_finish
FlValue * fl_basic_message_channel_send_finish(FlBasicMessageChannel *channel, GAsyncResult *result, GError **error)
Definition: fl_basic_message_channel.cc:253
user_data
FlKeyEvent uint64_t FlKeyResponderAsyncCallback gpointer user_data
Definition: fl_key_channel_responder.cc:121
fl_basic_message_channel_set_message_handler
void fl_basic_message_channel_set_message_handler(FlBasicMessageChannel *channel, FlBasicMessageChannelMessageHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_basic_message_channel.cc:176
fl_basic_message_channel_new
FlBasicMessageChannel * fl_basic_message_channel_new(FlBinaryMessenger *messenger, const gchar *name, FlMessageCodec *codec)
Definition: fl_basic_message_channel.cc:154
BASIC_MESSAGE_CHANNEL_RESPONSE_HANDLE
G_BEGIN_DECLS G_MODULE_EXPORT BASIC_MESSAGE_CHANNEL_RESPONSE_HANDLE
Definition: fl_basic_message_channel.h:32
fl_binary_messenger.h
fl_message_codec.h
FL
G_BEGIN_DECLS G_MODULE_EXPORT FL
Definition: fl_basic_message_channel.h:31
result
GAsyncResult * result
Definition: fl_text_input_plugin.cc:106
error
const uint8_t uint32_t uint32_t GError ** error
Definition: fl_pixel_buffer_texture_test.cc:40
callback
FlKeyEvent uint64_t FlKeyResponderAsyncCallback callback
Definition: fl_key_channel_responder.cc:120
fl_basic_message_channel_response_handle
G_BEGIN_DECLS G_MODULE_EXPORT fl_basic_message_channel_response_handle
Definition: fl_basic_message_channel.h:30