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