| 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,
30 fl_basic_message_channel_response_handle,
31 FL,
32 BASIC_MESSAGE_CHANNEL_RESPONSE_HANDLE,
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 */
110 typedef void (*FlBasicMessageChannelMessageHandler)(
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 */
148 void fl_basic_message_channel_set_message_handler(
149 FlBasicMessageChannel* channel,
150 FlBasicMessageChannelMessageHandler handler,
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. If `error` is not %NULL, `*error` must be initialized (typically
163 * %NULL, but an error from a previous call using GLib error handling is
164 * explicitly valid).
165 *
166 * Responds to a message.
167 *
168 * Returns: %TRUE on success.
169 */
170 gboolean fl_basic_message_channel_respond(
171 FlBasicMessageChannel* channel,
172 FlBasicMessageChannelResponseHandle* response_handle,
173 FlValue* message,
174 GError** error);
175
176 /**
177 * fl_basic_message_channel_send:
178 * @channel: an #FlBasicMessageChannel.
179 * @message: (allow-none): message to send, must match what the #FlMessageCodec
180 * supports.
181 * @cancellable: (allow-none): a #GCancellable or %NULL.
182 * @callback: (scope async): (allow-none): a #GAsyncReadyCallback to call when
183 * the request is satisfied or %NULL to ignore the response.
184 * @user_data: (closure): user data to pass to @callback.
185 *
186 * Asynchronously sends a message.
187 */
188 void fl_basic_message_channel_send(FlBasicMessageChannel* channel,
189 FlValue* message,
190 GCancellable* cancellable,
191 GAsyncReadyCallback callback,
192 gpointer user_data);
193
194 /**
195 * fl_basic_message_channel_send_finish:
196 * @channel: an #FlBasicMessageChannel.
197 * @result: a #GAsyncResult.
198 * @error: (allow-none): #GError location to store the error occurring, or %NULL
199 * to ignore. If `error` is not %NULL, `*error` must be initialized (typically
200 * %NULL, but an error from a previous call using GLib error handling is
201 * explicitly valid).
202 *
203 * Completes request started with fl_basic_message_channel_send().
204 *
205 * Returns: message response on success or %NULL on error.
206 */
207 FlValue* fl_basic_message_channel_send_finish(FlBasicMessageChannel* channel,
208 GAsyncResult* result,
209 GError** error);
210
211 G_END_DECLS
212
213 #endif // FLUTTER_SHELL_PLATFORM_LINUX_PUBLIC_FLUTTER_LINUX_FL_BASIC_MESSAGE_CHANNEL_H_
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
FL
G_BEGIN_DECLS G_MODULE_EXPORT FL
Definition: fl_basic_message_channel.h:31
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
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_response_handle
G_BEGIN_DECLS G_MODULE_EXPORT fl_basic_message_channel_response_handle
Definition: fl_basic_message_channel.h:30
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_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_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_binary_messenger.h
user_data
G_BEGIN_DECLS G_MODULE_EXPORT FlValue gpointer user_data
Definition: fl_event_channel.h:90
fl_message_codec.h
error
const uint8_t uint32_t uint32_t GError ** error
Definition: fl_pixel_buffer_texture_test.cc:40
FlValue
typedefG_BEGIN_DECLS struct _FlValue FlValue
Definition: fl_value.h:42