Flutter Engine
fl_binary_messenger.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_BINARY_MESSENGER_H_
6 #define FLUTTER_SHELL_PLATFORM_LINUX_FL_BINARY_MESSENGER_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 G_BEGIN_DECLS
16 
17 /**
18  * FlBinaryMessengerError:
19  * @FL_BINARY_MESSENGER_ERROR_ALREADY_RESPONDED: unable to send response, this
20  * message has already been responded to.
21  *
22  * Errors for #FlBinaryMessenger objects to set on failures.
23  */
24 #define FL_BINARY_MESSENGER_ERROR fl_binary_messenger_codec_error_quark()
25 
26 typedef enum {
29 
30 GQuark fl_binary_messenger_codec_error_quark(void) G_GNUC_CONST;
31 
32 G_DECLARE_FINAL_TYPE(FlBinaryMessenger,
33  fl_binary_messenger,
34  FL,
35  BINARY_MESSENGER,
36  GObject)
37 
38 G_DECLARE_FINAL_TYPE(FlBinaryMessengerResponseHandle,
40  FL,
42  GObject)
43 
44 /**
45  * FlBinaryMessenger:
46  *
47  * #FlBinaryMessenger is an object that allows sending and receiving of platform
48  * messages with an #FlEngine.
49  */
50 
51 /**
52  * FlBinaryMessengerResponseHandle:
53  *
54  * #FlBinaryMessengerResponseHandle is an object used to send responses with.
55  */
56 
57 /**
58  * FlBinaryMessengerMessageHandler:
59  * @messenger: an #FlBinaryMessenger.
60  * @channel: channel message received on.
61  * @message: message content received from Dart.
62  * @response_handle: a handle to respond to the message with.
63  * @user_data: (closure): data provided when registering this handler.
64  *
65  * Function called when platform messages are received. Call
66  * fl_binary_messenger_send_response() to respond to this message. If the
67  * response is not occurring in this callback take a reference to
68  * @response_handle and release that once it has been responded to. Failing to
69  * respond before the last reference to @response_handle is dropped is a
70  * programming error.
71  */
73  FlBinaryMessenger* messenger,
74  const gchar* channel,
75  GBytes* message,
76  FlBinaryMessengerResponseHandle* response_handle,
77  gpointer user_data);
78 
79 /**
80  * fl_binary_messenger_set_platform_message_handler:
81  * @binary_messenger: an #FlBinaryMessenger.
82  * @channel: channel to listen on.
83  * @handler: (allow-none): function to call when a message is received on this
84  * channel or %NULL to disable a handler
85  * @user_data: (closure): user data to pass to @handler.
86  * @destroy_notify: (allow-none): a function which gets called to free
87  * @user_data, or %NULL.
88  *
89  * Sets the function called when a platform message is received on the given
90  * channel. See #FlBinaryMessengerMessageHandler for details on how to respond
91  * to messages.
92  *
93  * The handler is removed if the channel is closed or is replaced by another
94  * handler, set @destroy_notify if you want to detect this.
95  */
97  FlBinaryMessenger* messenger,
98  const gchar* channel,
100  gpointer user_data,
101  GDestroyNotify destroy_notify);
102 
103 /**
104  * fl_binary_messenger_send_response:
105  * @binary_messenger: an #FlBinaryMessenger.
106  * @response_handle: handle that was provided in a
107  * #FlBinaryMessengerMessageHandler.
108  * @response: (allow-none): response to send or %NULL for an empty response.
109  * @error: (allow-none): #GError location to store the error occurring, or %NULL
110  * to ignore.
111  *
112  * Responds to a platform message.
113  *
114  * Returns: %TRUE on success.
115  */
117  FlBinaryMessenger* messenger,
118  FlBinaryMessengerResponseHandle* response_handle,
119  GBytes* response,
120  GError** error);
121 
122 /**
123  * fl_binary_messenger_send_on_channel:
124  * @binary_messenger: an #FlBinaryMessenger.
125  * @channel: channel to send to.
126  * @message: (allow-none): message buffer to send or %NULL for an empty message.
127  * @cancellable: (allow-none): a #GCancellable or %NULL.
128  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
129  * satisfied.
130  * @user_data: (closure): user data to pass to @callback.
131  *
132  * Asynchronously sends a platform message.
133  */
134 void fl_binary_messenger_send_on_channel(FlBinaryMessenger* messenger,
135  const gchar* channel,
136  GBytes* message,
137  GCancellable* cancellable,
138  GAsyncReadyCallback callback,
139  gpointer user_data);
140 
141 /**
142  * fl_binary_messenger_send_on_channel_finish:
143  * @binary_messenger: an #FlBinaryMessenger.
144  * @result: a #GAsyncResult.
145  * @error: (allow-none): #GError location to store the error occurring, or %NULL
146  * to ignore.
147  *
148  * Completes request started with fl_binary_messenger_send_on_channel().
149  *
150  * Returns: (transfer full): message response on success or %NULL on error.
151  */
152 GBytes* fl_binary_messenger_send_on_channel_finish(FlBinaryMessenger* messenger,
153  GAsyncResult* result,
154  GError** error);
155 
156 G_END_DECLS
157 
158 #endif // FLUTTER_SHELL_PLATFORM_LINUX_FL_BINARY_MESSENGER_H_
GBytes * fl_binary_messenger_send_on_channel_finish(FlBinaryMessenger *messenger, GAsyncResult *result, GError **error)
G_DECLARE_FINAL_TYPE(FlBinaryMessenger, fl_binary_messenger, FL, BINARY_MESSENGER, GObject) G_DECLARE_FINAL_TYPE(FlBinaryMessengerResponseHandle
BINARY_MESSENGER_RESPONSE_HANDLE
FlMethodResponse GError ** error
void fl_binary_messenger_send_on_channel(FlBinaryMessenger *messenger, const gchar *channel, GBytes *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
GQuark fl_binary_messenger_codec_error_quark(void) G_GNUC_CONST
G_BEGIN_DECLS FlValue gpointer user_data
FlBinaryMessengerError
gboolean fl_binary_messenger_send_response(FlBinaryMessenger *messenger, FlBinaryMessengerResponseHandle *response_handle, GBytes *response, GError **error)
fl_binary_messenger_response_handle
GObject typedef void(* FlBinaryMessengerMessageHandler)(FlBinaryMessenger *messenger, const gchar *channel, GBytes *message, FlBinaryMessengerResponseHandle *response_handle, gpointer user_data)
void fl_binary_messenger_set_message_handler_on_channel(FlBinaryMessenger *messenger, const gchar *channel, FlBinaryMessengerMessageHandler handler, gpointer user_data, GDestroyNotify destroy_notify)