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 { |
27 | FL_BINARY_MESSENGER_ERROR_ALREADY_RESPONDED, |
28 | } FlBinaryMessengerError; |
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, |
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 | */ |
72 | typedef 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 | */ |
96 | void 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 | */ |
116 | gboolean 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 | */ |
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_ |
159 | |