Flutter Engine
FlutterChannels.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_FLUTTERCHANNELS_H_
6 #define FLUTTER_FLUTTERCHANNELS_H_
7 
9 #import "FlutterCodecs.h"
10 
12 /**
13  * A message reply callback.
14  *
15  * Used for submitting a reply back to a Flutter message sender. Also used in
16  * the dual capacity for handling a message reply received from Flutter.
17  *
18  * @param reply The reply.
19  */
20 typedef void (^FlutterReply)(id _Nullable reply);
21 
22 /**
23  * A strategy for handling incoming messages from Flutter and to send
24  * asynchronous replies back to Flutter.
25  *
26  * @param message The message.
27  * @param callback A callback for submitting a reply to the sender.
28  */
29 typedef void (^FlutterMessageHandler)(id _Nullable message, FlutterReply callback);
30 
31 /**
32  * A channel for communicating with the Flutter side using basic, asynchronous
33  * message passing.
34  */
36 @interface FlutterBasicMessageChannel : NSObject
37 /**
38  * Creates a `FlutterBasicMessageChannel` with the specified name and binary
39  * messenger.
40  *
41  * The channel name logically identifies the channel; identically named channels
42  * interfere with each other's communication.
43  *
44  * The binary messenger is a facility for sending raw, binary messages to the
45  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
46  *
47  * The channel uses `FlutterStandardMessageCodec` to encode and decode messages.
48  *
49  * @param name The channel name.
50  * @param messenger The binary messenger.
51  */
52 + (instancetype)messageChannelWithName:(NSString*)name
53  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger;
54 
55 /**
56  * Creates a `FlutterBasicMessageChannel` with the specified name, binary
57  * messenger, and message codec.
58  *
59  * The channel name logically identifies the channel; identically named channels
60  * interfere with each other's communication.
61  *
62  * The binary messenger is a facility for sending raw, binary messages to the
63  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
64  *
65  * @param name The channel name.
66  * @param messenger The binary messenger.
67  * @param codec The message codec.
68  */
69 + (instancetype)messageChannelWithName:(NSString*)name
70  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
71  codec:(NSObject<FlutterMessageCodec>*)codec;
72 
73 /**
74  * Initializes a `FlutterBasicMessageChannel` with the specified name, binary
75  * messenger, and message codec.
76  *
77  * The channel name logically identifies the channel; identically named channels
78  * interfere with each other's communication.
79  *
80  * The binary messenger is a facility for sending raw, binary messages to the
81  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
82  *
83  * @param name The channel name.
84  * @param messenger The binary messenger.
85  * @param codec The message codec.
86  */
87 - (instancetype)initWithName:(NSString*)name
88  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
89  codec:(NSObject<FlutterMessageCodec>*)codec;
90 
91 /**
92  * Sends the specified message to the Flutter side, ignoring any reply.
93  *
94  * @param message The message. Must be supported by the codec of this
95  * channel.
96  */
97 - (void)sendMessage:(id _Nullable)message;
98 
99 /**
100  * Sends the specified message to the Flutter side, expecting an asynchronous
101  * reply.
102  *
103  * @param message The message. Must be supported by the codec of this channel.
104  * @param callback A callback to be invoked with the message reply from Flutter.
105  */
106 - (void)sendMessage:(id _Nullable)message reply:(FlutterReply _Nullable)callback;
107 
108 /**
109  * Registers a message handler with this channel.
110  *
111  * Replaces any existing handler. Use a `nil` handler for unregistering the
112  * existing handler.
113  *
114  * @param handler The message handler.
115  */
116 - (void)setMessageHandler:(FlutterMessageHandler _Nullable)handler;
117 
118 /**
119  * Adjusts the number of messages that will get buffered when sending messages to
120  * channels that aren't fully setup yet. For example, the engine isn't running
121  * yet or the channel's message handler isn't setup on the Dart side yet.
122  */
123 - (void)resizeChannelBuffer:(NSInteger)newSize;
124 
125 @end
126 
127 /**
128  * A method call result callback.
129  *
130  * Used for submitting a method call result back to a Flutter caller. Also used in
131  * the dual capacity for handling a method call result received from Flutter.
132  *
133  * @param result The result.
134  */
135 typedef void (^FlutterResult)(id _Nullable result);
136 
137 /**
138  * A strategy for handling method calls.
139  *
140  * @param call The incoming method call.
141  * @param result A callback to asynchronously submit the result of the call.
142  * Invoke the callback with a `FlutterError` to indicate that the call failed.
143  * Invoke the callback with `FlutterMethodNotImplemented` to indicate that the
144  * method was unknown. Any other values, including `nil`, are interpreted as
145  * successful results.
146  */
148 
149 /**
150  * A constant used with `FlutterMethodCallHandler` to respond to the call of an
151  * unknown method.
152  */
154 extern NSObject const* FlutterMethodNotImplemented;
155 
156 /**
157  * A channel for communicating with the Flutter side using invocation of
158  * asynchronous methods.
159  */
161 @interface FlutterMethodChannel : NSObject
162 /**
163  * Creates a `FlutterMethodChannel` with the specified name and binary messenger.
164  *
165  * The channel name logically identifies the channel; identically named channels
166  * interfere with each other's communication.
167  *
168  * The binary messenger is a facility for sending raw, binary messages to the
169  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
170  *
171  * The channel uses `FlutterStandardMethodCodec` to encode and decode method calls
172  * and result envelopes.
173  *
174  * @param name The channel name.
175  * @param messenger The binary messenger.
176  */
177 + (instancetype)methodChannelWithName:(NSString*)name
178  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger;
179 
180 /**
181  * Creates a `FlutterMethodChannel` with the specified name, binary messenger, and
182  * method codec.
183  *
184  * The channel name logically identifies the channel; identically named channels
185  * interfere with each other's communication.
186  *
187  * The binary messenger is a facility for sending raw, binary messages to the
188  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
189  *
190  * @param name The channel name.
191  * @param messenger The binary messenger.
192  * @param codec The method codec.
193  */
194 + (instancetype)methodChannelWithName:(NSString*)name
195  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
196  codec:(NSObject<FlutterMethodCodec>*)codec;
197 
198 /**
199  * Initializes a `FlutterMethodChannel` with the specified name, binary messenger,
200  * and method codec.
201  *
202  * The channel name logically identifies the channel; identically named channels
203  * interfere with each other's communication.
204  *
205  * The binary messenger is a facility for sending raw, binary messages to the
206  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
207  *
208  * @param name The channel name.
209  * @param messenger The binary messenger.
210  * @param codec The method codec.
211  */
212 - (instancetype)initWithName:(NSString*)name
213  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
214  codec:(NSObject<FlutterMethodCodec>*)codec;
215 
216 // clang-format off
217 /**
218  * Invokes the specified Flutter method with the specified arguments, expecting
219  * no results.
220  *
221  * @see [MethodChannel.setMethodCallHandler](https://docs.flutter.io/flutter/services/MethodChannel/setMethodCallHandler.html)
222  *
223  * @param method The name of the method to invoke.
224  * @param arguments The arguments. Must be a value supported by the codec of this
225  * channel.
226  */
227 // clang-format on
228 - (void)invokeMethod:(NSString*)method arguments:(id _Nullable)arguments;
229 
230 /**
231  * Invokes the specified Flutter method with the specified arguments, expecting
232  * an asynchronous result.
233  *
234  * @param method The name of the method to invoke.
235  * @param arguments The arguments. Must be a value supported by the codec of this
236  * channel.
237  * @param callback A callback that will be invoked with the asynchronous result.
238  * The result will be a `FlutterError` instance, if the method call resulted
239  * in an error on the Flutter side. Will be `FlutterMethodNotImplemented`, if
240  * the method called was not implemented on the Flutter side. Any other value,
241  * including `nil`, should be interpreted as successful results.
242  */
243 - (void)invokeMethod:(NSString*)method
244  arguments:(id _Nullable)arguments
245  result:(FlutterResult _Nullable)callback;
246 /**
247  * Registers a handler for method calls from the Flutter side.
248  *
249  * Replaces any existing handler. Use a `nil` handler for unregistering the
250  * existing handler.
251  *
252  * @param handler The method call handler.
253  */
254 - (void)setMethodCallHandler:(FlutterMethodCallHandler _Nullable)handler;
255 
256 /**
257  * Adjusts the number of messages that will get buffered when sending messages to
258  * channels that aren't fully setup yet. For example, the engine isn't running
259  * yet or the channel's message handler isn't setup on the Dart side yet.
260  */
261 - (void)resizeChannelBuffer:(NSInteger)newSize;
262 
263 @end
264 
265 /**
266  * An event sink callback.
267  *
268  * @param event The event.
269  */
270 typedef void (^FlutterEventSink)(id _Nullable event);
271 
272 /**
273  * A strategy for exposing an event stream to the Flutter side.
274  */
277 /**
278  * Sets up an event stream and begin emitting events.
279  *
280  * Invoked when the first listener is registered with the Stream associated to
281  * this channel on the Flutter side.
282  *
283  * @param arguments Arguments for the stream.
284  * @param events A callback to asynchronously emit events. Invoke the
285  * callback with a `FlutterError` to emit an error event. Invoke the
286  * callback with `FlutterEndOfEventStream` to indicate that no more
287  * events will be emitted. Any other value, including `nil` are emitted as
288  * successful events.
289  * @return A FlutterError instance, if setup fails.
290  */
291 - (FlutterError* _Nullable)onListenWithArguments:(id _Nullable)arguments
292  eventSink:(FlutterEventSink)events;
293 
294 /**
295  * Tears down an event stream.
296  *
297  * Invoked when the last listener is deregistered from the Stream associated to
298  * this channel on the Flutter side.
299  *
300  * The channel implementation may call this method with `nil` arguments
301  * to separate a pair of two consecutive set up requests. Such request pairs
302  * may occur during Flutter hot restart.
303  *
304  * @param arguments Arguments for the stream.
305  * @return A FlutterError instance, if teardown fails.
306  */
307 - (FlutterError* _Nullable)onCancelWithArguments:(id _Nullable)arguments;
308 @end
309 
310 /**
311  * A constant used with `FlutterEventChannel` to indicate end of stream.
312  */
314 extern NSObject const* FlutterEndOfEventStream;
315 
316 /**
317  * A channel for communicating with the Flutter side using event streams.
318  */
320 @interface FlutterEventChannel : NSObject
321 /**
322  * Creates a `FlutterEventChannel` with the specified name and binary messenger.
323  *
324  * The channel name logically identifies the channel; identically named channels
325  * interfere with each other's communication.
326  *
327  * The binary messenger is a facility for sending raw, binary messages to the
328  * Flutter side. This protocol is implemented by `FlutterViewController`.
329  *
330  * The channel uses `FlutterStandardMethodCodec` to decode stream setup and
331  * teardown requests, and to encode event envelopes.
332  *
333  * @param name The channel name.
334  * @param messenger The binary messenger.
335  */
336 + (instancetype)eventChannelWithName:(NSString*)name
337  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger;
338 
339 /**
340  * Creates a `FlutterEventChannel` with the specified name, binary messenger,
341  * and method codec.
342  *
343  * The channel name logically identifies the channel; identically named channels
344  * interfere with each other's communication.
345  *
346  * The binary messenger is a facility for sending raw, binary messages to the
347  * Flutter side. This protocol is implemented by `FlutterViewController`.
348  *
349  * @param name The channel name.
350  * @param messenger The binary messenger.
351  * @param codec The method codec.
352  */
353 + (instancetype)eventChannelWithName:(NSString*)name
354  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
355  codec:(NSObject<FlutterMethodCodec>*)codec;
356 
357 /**
358  * Initializes a `FlutterEventChannel` with the specified name, binary messenger,
359  * and method codec.
360  *
361  * The channel name logically identifies the channel; identically named channels
362  * interfere with each other's communication.
363  *
364  * The binary messenger is a facility for sending raw, binary messages to the
365  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
366  *
367  * @param name The channel name.
368  * @param messenger The binary messenger.
369  * @param codec The method codec.
370  */
371 - (instancetype)initWithName:(NSString*)name
372  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
373  codec:(NSObject<FlutterMethodCodec>*)codec;
374 /**
375  * Registers a handler for stream setup requests from the Flutter side.
376  *
377  * Replaces any existing handler. Use a `nil` handler for unregistering the
378  * existing handler.
379  *
380  * @param handler The stream handler.
381  */
382 - (void)setStreamHandler:(NSObject<FlutterStreamHandler>* _Nullable)handler;
383 @end
385 
386 #endif // FLUTTER_FLUTTERCHANNELS_H_
void(^ FlutterMethodCallHandler)(FlutterMethodCall *call, FlutterResult result)
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
void(^ FlutterEventSink)(id _Nullable event)
FLUTTER_EXPORT NSObject const * FlutterEndOfEventStream
void(^ FlutterMessageHandler)(id _Nullable message, FlutterReply callback)
void(^ FlutterResult)(id _Nullable result)
FLUTTER_EXPORT NSObject const * FlutterMethodNotImplemented
GdkEventButton * event
Definition: fl_view.cc:62
NS_ASSUME_NONNULL_BEGIN typedef void(^ FlutterReply)(id _Nullable reply)
#define FLUTTER_EXPORT