Flutter iOS Embedder
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 
11 @protocol FlutterTaskQueue;
12 
14 /**
15  * A message reply callback.
16  *
17  * Used for submitting a reply back to a Flutter message sender. Also used in
18  * the dual capacity for handling a message reply received from Flutter.
19  *
20  * @param reply The reply.
21  */
22 typedef void (^FlutterReply)(id _Nullable reply);
23 
24 /**
25  * A strategy for handling incoming messages from Flutter and to send
26  * asynchronous replies back to Flutter.
27  *
28  * @param message The message.
29  * @param callback A callback for submitting a reply to the sender which can be invoked from any
30  * thread.
31  */
32 typedef void (^FlutterMessageHandler)(id _Nullable message, FlutterReply callback);
33 
34 /**
35  * A channel for communicating with the Flutter side using basic, asynchronous
36  * message passing.
37  */
39 @interface FlutterBasicMessageChannel : NSObject
40 /**
41  * Creates a `FlutterBasicMessageChannel` with the specified name and binary
42  * messenger.
43  *
44  * The channel name logically identifies the channel; identically named channels
45  * interfere with each other's communication.
46  *
47  * The binary messenger is a facility for sending raw, binary messages to the
48  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
49  *
50  * The channel uses `FlutterStandardMessageCodec` to encode and decode messages.
51  *
52  * @param name The channel name.
53  * @param messenger The binary messenger.
54  */
55 + (instancetype)messageChannelWithName:(NSString*)name
56  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger;
57 
58 /**
59  * Creates a `FlutterBasicMessageChannel` with the specified name, binary
60  * messenger, and message codec.
61  *
62  * The channel name logically identifies the channel; identically named channels
63  * interfere with each other's communication.
64  *
65  * The binary messenger is a facility for sending raw, binary messages to the
66  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
67  *
68  * @param name The channel name.
69  * @param messenger The binary messenger.
70  * @param codec The message codec.
71  */
72 + (instancetype)messageChannelWithName:(NSString*)name
73  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
74  codec:(NSObject<FlutterMessageCodec>*)codec;
75 
76 /**
77  * Initializes a `FlutterBasicMessageChannel` with the specified name, binary
78  * messenger, and message codec.
79  *
80  * The channel name logically identifies the channel; identically named channels
81  * interfere with each other's communication.
82  *
83  * The binary messenger is a facility for sending raw, binary messages to the
84  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
85  *
86  * @param name The channel name.
87  * @param messenger The binary messenger.
88  * @param codec The message codec.
89  */
90 - (instancetype)initWithName:(NSString*)name
91  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
92  codec:(NSObject<FlutterMessageCodec>*)codec;
93 
94 /**
95  * Initializes a `FlutterBasicMessageChannel` with the specified name, binary
96  * messenger, and message codec.
97  *
98  * The channel name logically identifies the channel; identically named channels
99  * interfere with each other's communication.
100  *
101  * The binary messenger is a facility for sending raw, binary messages to the
102  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
103  *
104  * @param name The channel name.
105  * @param messenger The binary messenger.
106  * @param codec The message codec.
107  * @param taskQueue The FlutterTaskQueue that executes the handler (see
108  -[FlutterBinaryMessenger makeBackgroundTaskQueue]).
109  */
110 - (instancetype)initWithName:(NSString*)name
111  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
112  codec:(NSObject<FlutterMessageCodec>*)codec
113  taskQueue:(NSObject<FlutterTaskQueue>* _Nullable)taskQueue;
114 
115 /**
116  * Sends the specified message to the Flutter side, ignoring any reply.
117  *
118  * @param message The message. Must be supported by the codec of this
119  * channel.
120  */
121 - (void)sendMessage:(id _Nullable)message;
122 
123 /**
124  * Sends the specified message to the Flutter side, expecting an asynchronous
125  * reply.
126  *
127  * @param message The message. Must be supported by the codec of this channel.
128  * @param callback A callback to be invoked with the message reply from Flutter.
129  */
130 - (void)sendMessage:(id _Nullable)message reply:(FlutterReply _Nullable)callback;
131 
132 /**
133  * Registers a message handler with this channel.
134  *
135  * Replaces any existing handler. Use a `nil` handler for unregistering the
136  * existing handler.
137  *
138  * @param handler The message handler.
139  */
140 - (void)setMessageHandler:(FlutterMessageHandler _Nullable)handler;
141 
142 /**
143  * Adjusts the number of messages that will get buffered when sending messages to
144  * channels that aren't fully set up yet. For example, the engine isn't running
145  * yet or the channel's message handler isn't set up on the Dart side yet.
146  *
147  * @param name The channel name.
148  * @param messenger The binary messenger.
149  * @param newSize The number of messages that will get buffered.
150  */
151 + (void)resizeChannelWithName:(NSString*)name
152  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
153  size:(NSInteger)newSize;
154 
155 /**
156  * Adjusts the number of messages that will get buffered when sending messages to
157  * channels that aren't fully set up yet. For example, the engine isn't running
158  * yet or the channel's message handler isn't set up on the Dart side yet.
159  *
160  * @param newSize The number of messages that will get buffered.
161  */
162 - (void)resizeChannelBuffer:(NSInteger)newSize;
163 
164 /**
165  * Defines whether the channel should show warning messages when discarding messages
166  * due to overflow.
167  *
168  * @param warns When false, the channel is expected to overflow and warning messages
169  * will not be shown.
170  * @param name The channel name.
171  * @param messenger The binary messenger.
172  */
173 + (void)setWarnsOnOverflow:(BOOL)warns
174  forChannelWithName:(NSString*)name
175  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger;
176 
177 /**
178  * Defines whether the channel should show warning messages when discarding messages
179  * due to overflow.
180  *
181  * @param warns When false, the channel is expected to overflow and warning messages
182  * will not be shown.
183  */
184 - (void)setWarnsOnOverflow:(BOOL)warns;
185 
186 @end
187 
188 /**
189  * A method call result callback.
190  *
191  * Used for submitting a method call result back to a Flutter caller. Also used in
192  * the dual capacity for handling a method call result received from Flutter.
193  *
194  * @param result The result.
195  */
196 typedef void (^FlutterResult)(id _Nullable result);
197 
198 /**
199  * A strategy for handling method calls.
200  *
201  * @param call The incoming method call.
202  * @param result A callback to asynchronously submit the result of the call.
203  * Invoke the callback with a `FlutterError` to indicate that the call failed.
204  * Invoke the callback with `FlutterMethodNotImplemented` to indicate that the
205  * method was unknown. Any other values, including `nil`, are interpreted as
206  * successful results. This can be invoked from any thread.
207  */
209 
210 /**
211  * A constant used with `FlutterMethodCallHandler` to respond to the call of an
212  * unknown method.
213  */
215 extern NSObject const* FlutterMethodNotImplemented;
216 
217 /**
218  * A channel for communicating with the Flutter side using invocation of
219  * asynchronous methods.
220  */
222 @interface FlutterMethodChannel : NSObject
223 /**
224  * Creates a `FlutterMethodChannel` with the specified name and binary messenger.
225  *
226  * The channel name logically identifies the channel; identically named channels
227  * interfere with each other's communication.
228  *
229  * The binary messenger is a facility for sending raw, binary messages to the
230  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
231  *
232  * The channel uses `FlutterStandardMethodCodec` to encode and decode method calls
233  * and result envelopes.
234  *
235  * @param name The channel name.
236  * @param messenger The binary messenger.
237  */
238 + (instancetype)methodChannelWithName:(NSString*)name
239  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger;
240 
241 /**
242  * Creates a `FlutterMethodChannel` with the specified name, binary messenger, and
243  * method codec.
244  *
245  * The channel name logically identifies the channel; identically named channels
246  * interfere with each other's communication.
247  *
248  * The binary messenger is a facility for sending raw, binary messages to the
249  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
250  *
251  * @param name The channel name.
252  * @param messenger The binary messenger.
253  * @param codec The method codec.
254  */
255 + (instancetype)methodChannelWithName:(NSString*)name
256  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
257  codec:(NSObject<FlutterMethodCodec>*)codec;
258 
259 /**
260  * Initializes a `FlutterMethodChannel` with the specified name, binary messenger,
261  * and method codec.
262  *
263  * The channel name logically identifies the channel; identically named channels
264  * interfere with each other's communication.
265  *
266  * The binary messenger is a facility for sending raw, binary messages to the
267  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
268  *
269  * @param name The channel name.
270  * @param messenger The binary messenger.
271  * @param codec The method codec.
272  */
273 - (instancetype)initWithName:(NSString*)name
274  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
275  codec:(NSObject<FlutterMethodCodec>*)codec;
276 
277 /**
278  * Initializes a `FlutterMethodChannel` with the specified name, binary messenger,
279  * method codec, and task queue.
280  *
281  * The channel name logically identifies the channel; identically named channels
282  * interfere with each other's communication.
283  *
284  * The binary messenger is a facility for sending raw, binary messages to the
285  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
286  *
287  * @param name The channel name.
288  * @param messenger The binary messenger.
289  * @param codec The method codec.
290  * @param taskQueue The FlutterTaskQueue that executes the handler (see
291  -[FlutterBinaryMessenger makeBackgroundTaskQueue]).
292  */
293 - (instancetype)initWithName:(NSString*)name
294  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
295  codec:(NSObject<FlutterMethodCodec>*)codec
296  taskQueue:(NSObject<FlutterTaskQueue>* _Nullable)taskQueue;
297 
298 // clang-format off
299 /**
300  * Invokes the specified Flutter method with the specified arguments, expecting
301  * no results.
302  *
303  * @see [MethodChannel.setMethodCallHandler](https://api.flutter.dev/flutter/services/MethodChannel/setMethodCallHandler.html)
304  *
305  * @param method The name of the method to invoke.
306  * @param arguments The arguments. Must be a value supported by the codec of this
307  * channel.
308  */
309 // clang-format on
310 - (void)invokeMethod:(NSString*)method arguments:(id _Nullable)arguments;
311 
312 /**
313  * Invokes the specified Flutter method with the specified arguments, expecting
314  * an asynchronous result.
315  *
316  * @param method The name of the method to invoke.
317  * @param arguments The arguments. Must be a value supported by the codec of this
318  * channel.
319  * @param callback A callback that will be invoked with the asynchronous result.
320  * The result will be a `FlutterError` instance, if the method call resulted
321  * in an error on the Flutter side. Will be `FlutterMethodNotImplemented`, if
322  * the method called was not implemented on the Flutter side. Any other value,
323  * including `nil`, should be interpreted as successful results.
324  */
325 - (void)invokeMethod:(NSString*)method
326  arguments:(id _Nullable)arguments
327  result:(FlutterResult _Nullable)callback;
328 /**
329  * Registers a handler for method calls from the Flutter side.
330  *
331  * Replaces any existing handler. Use a `nil` handler for unregistering the
332  * existing handler.
333  *
334  * @param handler The method call handler.
335  */
336 - (void)setMethodCallHandler:(FlutterMethodCallHandler _Nullable)handler;
337 
338 /**
339  * Adjusts the number of messages that will get buffered when sending messages to
340  * channels that aren't fully set up yet. For example, the engine isn't running
341  * yet or the channel's message handler isn't set up on the Dart side yet.
342  */
343 - (void)resizeChannelBuffer:(NSInteger)newSize;
344 
345 @end
346 
347 /**
348  * An event sink callback.
349  *
350  * @param event The event.
351  */
352 typedef void (^FlutterEventSink)(id _Nullable event);
353 
354 /**
355  * A strategy for exposing an event stream to the Flutter side.
356  */
359 /**
360  * Sets up an event stream and begin emitting events.
361  *
362  * Invoked when the first listener is registered with the Stream associated to
363  * this channel on the Flutter side.
364  *
365  * @param arguments Arguments for the stream.
366  * @param events A callback to asynchronously emit events. Invoke the
367  * callback with a `FlutterError` to emit an error event. Invoke the
368  * callback with `FlutterEndOfEventStream` to indicate that no more
369  * events will be emitted. Any other value, including `nil` are emitted as
370  * successful events.
371  * @return A FlutterError instance, if setup fails.
372  */
373 - (FlutterError* _Nullable)onListenWithArguments:(id _Nullable)arguments
374  eventSink:(FlutterEventSink)events;
375 
376 /**
377  * Tears down an event stream.
378  *
379  * Invoked when the last listener is deregistered from the Stream associated to
380  * this channel on the Flutter side.
381  *
382  * The channel implementation may call this method with `nil` arguments
383  * to separate a pair of two consecutive set up requests. Such request pairs
384  * may occur during Flutter hot restart.
385  *
386  * @param arguments Arguments for the stream.
387  * @return A FlutterError instance, if teardown fails.
388  */
389 - (FlutterError* _Nullable)onCancelWithArguments:(id _Nullable)arguments;
390 @end
391 
392 /**
393  * A constant used with `FlutterEventChannel` to indicate end of stream.
394  */
396 extern NSObject const* FlutterEndOfEventStream;
397 
398 /**
399  * A channel for communicating with the Flutter side using event streams.
400  */
402 @interface FlutterEventChannel : NSObject
403 /**
404  * Creates a `FlutterEventChannel` with the specified name and binary messenger.
405  *
406  * The channel name logically identifies the channel; identically named channels
407  * interfere with each other's communication.
408  *
409  * The binary messenger is a facility for sending raw, binary messages to the
410  * Flutter side. This protocol is implemented by `FlutterViewController`.
411  *
412  * The channel uses `FlutterStandardMethodCodec` to decode stream setup and
413  * teardown requests, and to encode event envelopes.
414  *
415  * @param name The channel name.
416  * @param messenger The binary messenger.
417  */
418 + (instancetype)eventChannelWithName:(NSString*)name
419  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger;
420 
421 /**
422  * Creates a `FlutterEventChannel` with the specified name, binary messenger,
423  * and method codec.
424  *
425  * The channel name logically identifies the channel; identically named channels
426  * interfere with each other's communication.
427  *
428  * The binary messenger is a facility for sending raw, binary messages to the
429  * Flutter side. This protocol is implemented by `FlutterViewController`.
430  *
431  * @param name The channel name.
432  * @param messenger The binary messenger.
433  * @param codec The method codec.
434  */
435 + (instancetype)eventChannelWithName:(NSString*)name
436  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
437  codec:(NSObject<FlutterMethodCodec>*)codec;
438 
439 /**
440  * Initializes a `FlutterEventChannel` with the specified name, binary messenger,
441  * and method codec.
442  *
443  * The channel name logically identifies the channel; identically named channels
444  * interfere with each other's communication.
445  *
446  * The binary messenger is a facility for sending raw, binary messages to the
447  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
448  *
449  * @param name The channel name.
450  * @param messenger The binary messenger.
451  * @param codec The method codec.
452  */
453 - (instancetype)initWithName:(NSString*)name
454  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
455  codec:(NSObject<FlutterMethodCodec>*)codec;
456 
457 /**
458  * Initializes a `FlutterEventChannel` with the specified name, binary messenger,
459  * method codec and task queue.
460  *
461  * The channel name logically identifies the channel; identically named channels
462  * interfere with each other's communication.
463  *
464  * The binary messenger is a facility for sending raw, binary messages to the
465  * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`.
466  *
467  * @param name The channel name.
468  * @param messenger The binary messenger.
469  * @param codec The method codec.
470  * @param taskQueue The FlutterTaskQueue that executes the handler (see
471  -[FlutterBinaryMessenger makeBackgroundTaskQueue]).
472  */
473 - (instancetype)initWithName:(NSString*)name
474  binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger
475  codec:(NSObject<FlutterMethodCodec>*)codec
476  taskQueue:(NSObject<FlutterTaskQueue>* _Nullable)taskQueue;
477 /**
478  * Registers a handler for stream setup requests from the Flutter side.
479  *
480  * Replaces any existing handler. Use a `nil` handler for unregistering the
481  * existing handler.
482  *
483  * @param handler The stream handler.
484  */
485 - (void)setStreamHandler:(NSObject<FlutterStreamHandler>* _Nullable)handler;
486 @end
488 
489 #endif // FLUTTER_FLUTTERCHANNELS_H_
FlutterBasicMessageChannel
Definition: FlutterChannels.h:39
FlutterMethodChannel
Definition: FlutterChannels.h:222
FlutterMethodNotImplemented
FLUTTER_DARWIN_EXPORT NSObject const * FlutterMethodNotImplemented
NS_ASSUME_NONNULL_END
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
FlutterError
Definition: FlutterCodecs.h:246
NS_ASSUME_NONNULL_BEGIN
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
FlutterMethodCallHandler
void(^ FlutterMethodCallHandler)(FlutterMethodCall *call, FlutterResult result)
Definition: FlutterChannels.h:208
FlutterEventChannel
Definition: FlutterChannels.h:402
FlutterEndOfEventStream
FLUTTER_DARWIN_EXPORT NSObject const * FlutterEndOfEventStream
FlutterMethodCall
Definition: FlutterCodecs.h:220
FlutterBinaryMessenger.h
FlutterTaskQueue-p
Definition: platform_message_handler_ios.h:16
FlutterResult
void(^ FlutterResult)(id _Nullable result)
Definition: FlutterChannels.h:196
FlutterCodecs.h
FlutterReply
NS_ASSUME_NONNULL_BEGIN typedef void(^ FlutterReply)(id _Nullable reply)
FlutterEventSink
void(^ FlutterEventSink)(id _Nullable event)
Definition: FlutterChannels.h:352
FlutterMessageCodec-p
Definition: FlutterCodecs.h:18
FlutterStreamHandler-p
Definition: FlutterChannels.h:358
FLUTTER_DARWIN_EXPORT
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
FlutterMessageHandler
void(^ FlutterMessageHandler)(id _Nullable message, FlutterReply callback)
Definition: FlutterChannels.h:32
FlutterBinaryMessenger-p
Definition: FlutterBinaryMessenger.h:48