| 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_FLUTTERCHANNELS_H_
6 #define FLUTTER_FLUTTERCHANNELS_H_
7
8 #import "FlutterBinaryMessenger.h"
9 #import "FlutterCodecs.h"
10
11 @protocol FlutterTaskQueue;
12
13 NS_ASSUME_NONNULL_BEGIN
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 */
38 FLUTTER_DARWIN_EXPORT
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 */
208 typedef void (^FlutterMethodCallHandler)(FlutterMethodCall* call, FlutterResult result);
209
210 /**
211 * A constant used with `FlutterMethodCallHandler` to respond to the call of an
212 * unknown method.
213 */
214 FLUTTER_DARWIN_EXPORT
215 extern NSObject const* FlutterMethodNotImplemented;
216
217 /**
218 * A channel for communicating with the Flutter side using invocation of
219 * asynchronous methods.
220 */
221 FLUTTER_DARWIN_EXPORT
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 */
357 FLUTTER_DARWIN_EXPORT
358 @protocol FlutterStreamHandler
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 */
395 FLUTTER_DARWIN_EXPORT
396 extern NSObject const* FlutterEndOfEventStream;
397
398 /**
399 * A channel for communicating with the Flutter side using event streams.
400 */
401 FLUTTER_DARWIN_EXPORT
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
487 NS_ASSUME_NONNULL_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: FlutterBinaryMessengerRelayTest.mm: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