Flutter Engine
fl_method_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_METHOD_CHANNEL_H_
6 #define FLUTTER_SHELL_PLATFORM_LINUX_FL_METHOD_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_call.h"
17 #include "fl_method_codec.h"
18 #include "fl_method_response.h"
19 
20 G_BEGIN_DECLS
21 
22 G_DECLARE_FINAL_TYPE(FlMethodChannel,
23  fl_method_channel,
24  FL,
25  METHOD_CHANNEL,
26  GObject)
27 
28 /**
29  * FlMethodChannel:
30  *
31  * #FlMethodChannel is an object that allows method calls to and from Dart code.
32  *
33  * The following example shows how to call and handle methods on a channel.
34  * See #FlMethodResponse for how to handle errors in more detail.
35  *
36  * |[<!-- language="C" -->
37  * static FlMethodChannel *channel = NULL;
38  *
39  * static void method_call_cb (FlMethodChannel* channel,
40  * FlMethodCall* method_call,
41  * gpointer user_data) {
42  * g_autoptr(FlMethodResponse) response = NULL;
43  * if (strcmp (fl_method_call_get_name (method_call), "Foo.bar") == 0) {
44  * g_autoptr(GError) bar_error = NULL;
45  * g_autoptr(FlValue) result =
46  * do_bar (fl_method_call_get_args (method_call), &bar_error);
47  * if (result == NULL)
48  * response =
49  * FL_METHOD_RESPONSE (fl_method_error_response_new ("bar error",
50  * bar_error->message));
51  * else
52  * response = FL_METHOD_RESPONSE (fl_method_success_response_new
53  * (result)); } else response = FL_METHOD_RESPONSE
54  * (fl_method_not_implemented_response_new ());
55  *
56  * g_autoptr(GError) error = NULL;
57  * if (!fl_method_call_respond(method_call, response))
58  * g_warning ("Failed to send response: %s", error->message);
59  * }
60  *
61  * static void method_response_cb(GObject *object,
62  * GAsyncResult *result,
63  * gpointer user_data) {
64  * g_autoptr(GError) error = NULL;
65  * g_autoptr(FlMethodResponse) response =
66  * fl_method_channel_invoke_method_finish (FL_METHOD_CODEC (object), result,
67  * &error);
68  * if (response == NULL) {
69  * g_warning ("Failed to call method: %s", error->message);
70  * return;
71  * }
72  *
73  * g_autoptr(FlValue) value =
74  * fl_method_response_get_result (response, &error);
75  * if (response == NULL) {
76  * g_warning ("Method returned error: %s", error->message);
77  * return;
78  * }
79  *
80  * use_result (value);
81  * }
82  *
83  * static void call_method () {
84  * g_autoptr(FlStandardMethodCodec) codec = fl_standard_method_codec_new ();
85  * channel =
86  * fl_method_channel_new(messenger, "flutter/foo", FL_METHOD_CODEC (codec));
87  * fl_method_channel_set_method_call_handler (channel, method_call_cb, NULL,
88  * NULL);
89  *
90  * g_autoptr(FlValue) args = fl_value_new_string ("Hello World");
91  * fl_method_channel_invoke_method (channel, "Foo.foo", args,
92  * cancellable, method_response_cb, NULL);
93  * }
94  * ]|
95  *
96  * #FlMethodChannel matches the MethodChannel class in the Flutter services
97  * library.
98  */
99 
100 /**
101  * FlMethodChannelMethodCallHandler:
102  * @channel: an #FlMethodChannel.
103  * @method_call: an #FlMethodCall.
104  * @user_data: (closure): data provided when registering this handler.
105  *
106  * Function called when a method call is received. Respond to the method call
107  * with fl_method_call_respond(). If the response is not occurring in this
108  * callback take a reference to @method_call and release that once it has been
109  * responded to. Failing to respond before the last reference to @method_call is
110  * dropped is a programming error.
111  */
112 typedef void (*FlMethodChannelMethodCallHandler)(FlMethodChannel* channel,
113  FlMethodCall* method_call,
114  gpointer user_data);
115 
116 /**
117  * fl_method_channel_new:
118  * @messenger: an #FlBinaryMessenger.
119  * @name: a channel name.
120  * @codec: the method codec.
121  *
122  * Creates a new method channel. @codec must match the codec used on the Dart
123  * end of the channel.
124  *
125  * Returns: a new #FlMethodChannel.
126  */
127 FlMethodChannel* fl_method_channel_new(FlBinaryMessenger* messenger,
128  const gchar* name,
129  FlMethodCodec* codec);
130 
131 /**
132  * fl_method_channel_set_method_call_handler:
133  * @channel: an #FlMethodChannel.
134  * @handler: function to call when a method call is received on this channel.
135  * @user_data: (closure): user data to pass to @handler.
136  * @destroy_notify: (allow-none): a function which gets called to free
137  * @user_data, or %NULL.
138  *
139  * Sets the function called when a method call is received from the Dart side of
140  * the channel. See #FlMethodChannelMethodCallHandler for details on how to
141  * respond to method calls.
142  *
143  * The handler is removed if the channel is closed or is replaced by another
144  * handler, set @destroy_notify if you want to detect this.
145  */
147  FlMethodChannel* channel,
148  FlMethodChannelMethodCallHandler handler,
149  gpointer user_data,
150  GDestroyNotify destroy_notify);
151 
152 /**
153  * fl_method_channel_invoke_method:
154  * @channel: an #FlMethodChannel.
155  * @method: the method to call.
156  * @args: (allow-none): arguments to the method, must match what the
157  * #FlMethodCodec supports.
158  * @cancellable: (allow-none): a #GCancellable or %NULL.
159  * @callback: (scope async): (allow-none): a #GAsyncReadyCallback to call when
160  * the request is satisfied or %NULL to ignore the response.
161  * @user_data: (closure): user data to pass to @callback.
162  *
163  * Calls a method on this channel.
164  */
165 void fl_method_channel_invoke_method(FlMethodChannel* channel,
166  const gchar* method,
167  FlValue* args,
168  GCancellable* cancellable,
169  GAsyncReadyCallback callback,
170  gpointer user_data);
171 
172 /**
173  * fl_method_channel_invoke_method_finish:
174  * @channel: an #FlMethodChannel.
175  * @result: #GAsyncResult.
176  * @error: (allow-none): #GError location to store the error occurring, or %NULL
177  * to ignore.
178  *
179  * Completes request started with fl_method_channel_invoke_method().
180  *
181  * Returns: (transfer full): an #FlMethodResponse or %NULL on error.
182  */
184  FlMethodChannel* channel,
185  GAsyncResult* result,
186  GError** error);
187 
188 G_END_DECLS
189 
190 #endif // FLUTTER_SHELL_PLATFORM_LINUX_FL_METHOD_CHANNEL_H_
G_BEGIN_DECLS FlValue * args
G_BEGIN_DECLS FlMethodCall * method_call
void fl_method_channel_invoke_method(FlMethodChannel *channel, const gchar *method, FlValue *args, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
typedefG_BEGIN_DECLS struct _FlValue FlValue
Definition: fl_value.h:39
FlMethodResponse GError ** error
FlMethodResponse * fl_method_channel_invoke_method_finish(FlMethodChannel *channel, GAsyncResult *result, GError **error)
void fl_method_channel_set_method_call_handler(FlMethodChannel *channel, FlMethodChannelMethodCallHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
G_BEGIN_DECLS G_DECLARE_FINAL_TYPE(FlMethodChannel, fl_method_channel, FL, METHOD_CHANNEL, GObject) typedef void(*FlMethodChannelMethodCallHandler)(FlMethodChannel *channel
G_BEGIN_DECLS FlMethodCall gpointer user_data
const char * name
Definition: fuchsia.cc:50
G_BEGIN_DECLS FL
FlMethodChannel * fl_method_channel_new(FlBinaryMessenger *messenger, const gchar *name, FlMethodCodec *codec)