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
15G_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
26typedef enum {
27 FL_BINARY_MESSENGER_ERROR_ALREADY_RESPONDED,
28} FlBinaryMessengerError;
29
30GQuark fl_binary_messenger_codec_error_quark(void) G_GNUC_CONST;
31
32G_DECLARE_FINAL_TYPE(FlBinaryMessenger,
33 fl_binary_messenger,
34 FL,
35 BINARY_MESSENGER,
36 GObject)
37
38G_DECLARE_FINAL_TYPE(FlBinaryMessengerResponseHandle,
39 fl_binary_messenger_response_handle,
40 FL,
41 BINARY_MESSENGER_RESPONSE_HANDLE,
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 */
72typedef void (*FlBinaryMessengerMessageHandler)(
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 */
96void fl_binary_messenger_set_message_handler_on_channel(
97 FlBinaryMessenger* messenger,
98 const gchar* channel,
99 FlBinaryMessengerMessageHandler handler,
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 */
116gboolean fl_binary_messenger_send_response(
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 */
134void 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 */
152GBytes* fl_binary_messenger_send_on_channel_finish(FlBinaryMessenger* messenger,
153 GAsyncResult* result,
154 GError** error);
155
156G_END_DECLS
157
158#endif // FLUTTER_SHELL_PLATFORM_LINUX_FL_BINARY_MESSENGER_H_
159