| 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_SHELL_PLATFORM_DARWIN_COMMON_FRAMEWORK_HEADERS_FLUTTERCHANNELS_H_
6 #define FLUTTER_SHELL_PLATFORM_DARWIN_COMMON_FRAMEWORK_HEADERS_FLUTTERCHANNELS_H_
7
8 #import "FlutterBinaryMessenger.h"
9 #import "FlutterCodecs.h"
10
11 NS_ASSUME_NONNULL_BEGIN
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 */
36 FLUTTER_DARWIN_EXPORT
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 */
206 typedef void (^FlutterMethodCallHandler)(FlutterMethodCall* call, FlutterResult result);
207
208 /**
209 * A constant used with `FlutterMethodCallHandler` to respond to the call of an
210 * unknown method.
211 */
212 FLUTTER_DARWIN_EXPORT
213 extern NSObject const* FlutterMethodNotImplemented;
214
215 /**
216 * A channel for communicating with the Flutter side using invocation of
217 * asynchronous methods.
218 */
219 FLUTTER_DARWIN_EXPORT
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.dev/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 */
355 FLUTTER_DARWIN_EXPORT
356 @protocol FlutterStreamHandler
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 */
393 FLUTTER_DARWIN_EXPORT
394 extern NSObject const* FlutterEndOfEventStream;
395
396 /**
397 * A channel for communicating with the Flutter side using event streams.
398 */
399 FLUTTER_DARWIN_EXPORT
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
485 NS_ASSUME_NONNULL_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