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