Flutter Linux Embedder
fl_event_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_EVENT_CHANNEL_H_
6 #define FLUTTER_SHELL_PLATFORM_LINUX_PUBLIC_FLUTTER_LINUX_FL_EVENT_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_method_channel.h"
18 #include "fl_method_response.h"
19 
20 G_BEGIN_DECLS
21 
22 G_MODULE_EXPORT
23 G_DECLARE_FINAL_TYPE(FlEventChannel,
24  fl_event_channel,
25  FL,
26  EVENT_CHANNEL,
27  GObject)
28 
29 /**
30  * FlEventChannel:
31  *
32  * #FlEventChannel is an object that allows sending
33  * an events stream to Dart code over platform channels.
34  *
35  * The following example shows how to send events on a channel:
36  *
37  * |[<!-- language="C" -->
38  * static FlEventChannel *channel = NULL;
39  * static gboolean send_events = FALSE;
40  *
41  * static void event_occurs_cb (FooEvent *event) {
42  * if (send_events) {
43  * g_autoptr(FlValue) message = foo_event_to_value (event);
44  * g_autoptr(GError) error = NULL;
45  * if (!fl_event_channel_send (channel, message, NULL, &error)) {
46  * g_warning ("Failed to send event: %s", error->message);
47  * }
48  * }
49  * }
50  *
51  * static FlMethodErrorResponse* listen_cb (FlEventChannel* channel,
52  * FlValue *args,
53  * gpointer user_data) {
54  * send_events = TRUE;
55  * return NULL;
56  * }
57  *
58  * static FlMethodErrorResponse* cancel_cb (GObject *object,
59  * FlValue *args,
60  * gpointer user_data) {
61  * send_events = FALSE;
62  * return NULL;
63  * }
64  *
65  * static void setup_channel () {
66  * g_autoptr(FlStandardMethodCodec) codec = fl_standard_method_codec_new ();
67  * channel = fl_event_channel_new (messenger, "flutter/foo",
68  * FL_METHOD_CODEC (codec));
69  * fl_event_channel_set_stream_handlers (channel, listen_cb, cancel_cb,
70  * NULL, NULL);
71  * }
72  * ]|
73  *
74  * #FlEventChannel matches the EventChannel class in the Flutter
75  * services library.
76  */
77 
78 /**
79  * FlEventChannelHandler:
80  * @channel: an #FlEventChannel.
81  * @args: arguments passed from the Dart end of the channel.
82  * @user_data: (closure): data provided when registering this handler.
83  *
84  * Function called when the stream is listened to or cancelled.
85  *
86  * Returns: (transfer full): an #FlMethodErrorResponse or %NULL if no error.
87  */
88 typedef FlMethodErrorResponse* (*FlEventChannelHandler)(FlEventChannel* channel,
90  gpointer user_data);
91 
92 /**
93  * fl_event_channel_new:
94  * @messenger: an #FlBinaryMessenger.
95  * @name: a channel name.
96  * @codec: the message codec.
97  *
98  * Creates an event channel. @codec must match the codec used on the Dart
99  * end of the channel.
100  *
101  * Returns: a new #FlEventChannel.
102  */
103 FlEventChannel* fl_event_channel_new(FlBinaryMessenger* messenger,
104  const gchar* name,
105  FlMethodCodec* codec);
106 
107 /**
108  * fl_event_channel_set_stream_handlers:
109  * @channel: an #FlEventChannel.
110  * @listen_handler: (allow-none): function to call when the Dart side of the
111  * channel starts listening to the stream.
112  * @cancel_handler: (allow-none): function to call when the Dart side of the
113  * channel cancels their subscription to the stream.
114  * @user_data: (closure): user data to pass to @listen_handler and
115  * @cancel_handler.
116  * @destroy_notify: (allow-none): a function which gets called to free
117  * @user_data, or %NULL.
118  *
119  * Sets the functions called when the Dart side requests the stream to start and
120  * finish.
121  *
122  * The handlers are removed if the channel is closed or is replaced by another
123  * handler, set @destroy_notify if you want to detect this.
124  */
125 void fl_event_channel_set_stream_handlers(FlEventChannel* channel,
126  FlEventChannelHandler listen_handler,
127  FlEventChannelHandler cancel_handler,
128  gpointer user_data,
129  GDestroyNotify destroy_notify);
130 
131 /**
132  * fl_event_channel_send:
133  * @channel: an #FlEventChannel.
134  * @event: event to send, must match what the #FlMethodCodec supports.
135  * @cancellable: (allow-none): a #GCancellable or %NULL.
136  * @error: (allow-none): #GError location to store the error occurring, or %NULL
137  * to ignore.
138  *
139  * Sends an event on the channel.
140  * Events should only be sent once the channel is being listened to.
141  *
142  * Returns: %TRUE if successful.
143  */
144 gboolean fl_event_channel_send(FlEventChannel* channel,
145  FlValue* event,
146  GCancellable* cancellable,
147  GError** error);
148 
149 /**
150  * fl_event_channel_send_error:
151  * @channel: an #FlEventChannel.
152  * @code: error code to send.
153  * @message: error message to send.
154  * @details: (allow-none): error details or %NULL.
155  * @cancellable: (allow-none): a #GCancellable or %NULL.
156  * @error: (allow-none): #GError location to store the error occurring, or %NULL
157  * to ignore.
158  *
159  * Sends an error on the channel.
160  * Errors should only be sent once the channel is being listened to.
161  *
162  * Returns: %TRUE if successful.
163  */
164 gboolean fl_event_channel_send_error(FlEventChannel* channel,
165  const gchar* code,
166  const gchar* message,
167  FlValue* details,
168  GCancellable* cancellable,
169  GError** error);
170 
171 /**
172  * fl_event_channel_send_end_of_stream:
173  * @channel: an #FlEventChannel.
174  * @cancellable: (allow-none): a #GCancellable or %NULL.
175  * @error: (allow-none): #GError location to store the error occurring, or %NULL
176  * to ignore.
177  *
178  * Indicates the stream has completed.
179  * It is a programmer error to send any more events after calling this.
180  *
181  * Returns: %TRUE if successful.
182  */
183 gboolean fl_event_channel_send_end_of_stream(FlEventChannel* channel,
184  GCancellable* cancellable,
185  GError** error);
186 
187 G_END_DECLS
188 
189 #endif // FLUTTER_SHELL_PLATFORM_LINUX_PUBLIC_FLUTTER_LINUX_FL_EVENT_CHANNEL_H_
event
FlKeyEvent * event
Definition: fl_key_channel_responder.cc:118
fl_method_channel.h
FlValue
typedefG_BEGIN_DECLS struct _FlValue FlValue
Definition: fl_value.h:42
fl_event_channel_new
FlEventChannel * fl_event_channel_new(FlBinaryMessenger *messenger, const gchar *name, FlMethodCodec *codec)
Definition: fl_event_channel.cc:159
user_data
G_BEGIN_DECLS G_MODULE_EXPORT FlValue gpointer user_data
Definition: fl_event_channel.h:90
fl_event_channel_send_error
G_MODULE_EXPORT gboolean fl_event_channel_send_error(FlEventChannel *self, const gchar *code, const gchar *message, FlValue *details, GCancellable *cancellable, GError **error)
Definition: fl_event_channel.cc:215
fl_binary_messenger.h
fl_event_channel_send_end_of_stream
G_MODULE_EXPORT gboolean fl_event_channel_send_end_of_stream(FlEventChannel *self, GCancellable *cancellable, GError **error)
Definition: fl_event_channel.cc:237
FL
FL
Definition: fl_binary_messenger.cc:27
fl_method_response.h
args
G_BEGIN_DECLS G_MODULE_EXPORT FlValue * args
Definition: fl_event_channel.h:89
error
const uint8_t uint32_t uint32_t GError ** error
Definition: fl_pixel_buffer_texture_test.cc:40
fl_event_channel_send
gboolean fl_event_channel_send(FlEventChannel *channel, FlValue *event, GCancellable *cancellable, GError **error)
Definition: fl_event_channel.cc:196
G_DECLARE_FINAL_TYPE
G_BEGIN_DECLS G_MODULE_EXPORT G_DECLARE_FINAL_TYPE(FlEventChannel, fl_event_channel, FL, EVENT_CHANNEL, GObject) typedef FlMethodErrorResponse *(*FlEventChannelHandler)(FlEventChannel *channel
fl_event_channel_set_stream_handlers
void fl_event_channel_set_stream_handlers(FlEventChannel *channel, FlEventChannelHandler listen_handler, FlEventChannelHandler cancel_handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_event_channel.cc:181