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