// Copyright 2013 The Flutter Authors. All rights reserved. // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. #ifndef FLUTTER_SHELL_PLATFORM_DARWIN_COMMON_FRAMEWORK_HEADERS_FLUTTERCHANNELS_H_ #define FLUTTER_SHELL_PLATFORM_DARWIN_COMMON_FRAMEWORK_HEADERS_FLUTTERCHANNELS_H_ #import "FlutterBinaryMessenger.h" #import "FlutterCodecs.h" NS_ASSUME_NONNULL_BEGIN /** * A message reply callback. * * Used for submitting a reply back to a Flutter message sender. Also used in * the dual capacity for handling a message reply received from Flutter. * * @param reply The reply. */ typedef void (^FlutterReply)(id _Nullable reply); /** * A strategy for handling incoming messages from Flutter and to send * asynchronous replies back to Flutter. * * @param message The message. * @param callback A callback for submitting a reply to the sender which can be invoked from any * thread. */ typedef void (^FlutterMessageHandler)(id _Nullable message, FlutterReply callback); /** * A channel for communicating with the Flutter side using basic, asynchronous * message passing. */ FLUTTER_DARWIN_EXPORT @interface FlutterBasicMessageChannel : NSObject /** * Creates a `FlutterBasicMessageChannel` with the specified name and binary * messenger. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * The channel uses `FlutterStandardMessageCodec` to encode and decode messages. * * @param name The channel name. * @param messenger The binary messenger. */ + (instancetype)messageChannelWithName:(NSString*)name binaryMessenger:(NSObject*)messenger; /** * Creates a `FlutterBasicMessageChannel` with the specified name, binary * messenger, and message codec. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * @param name The channel name. * @param messenger The binary messenger. * @param codec The message codec. */ + (instancetype)messageChannelWithName:(NSString*)name binaryMessenger:(NSObject*)messenger codec:(NSObject*)codec; /** * Initializes a `FlutterBasicMessageChannel` with the specified name, binary * messenger, and message codec. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * @param name The channel name. * @param messenger The binary messenger. * @param codec The message codec. */ - (instancetype)initWithName:(NSString*)name binaryMessenger:(NSObject*)messenger codec:(NSObject*)codec; /** * Initializes a `FlutterBasicMessageChannel` with the specified name, binary * messenger, and message codec. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * @param name The channel name. * @param messenger The binary messenger. * @param codec The message codec. * @param taskQueue The FlutterTaskQueue that executes the handler (see -[FlutterBinaryMessenger makeBackgroundTaskQueue]). */ - (instancetype)initWithName:(NSString*)name binaryMessenger:(NSObject*)messenger codec:(NSObject*)codec taskQueue:(NSObject* _Nullable)taskQueue; /** * Sends the specified message to the Flutter side, ignoring any reply. * * @param message The message. Must be supported by the codec of this * channel. */ - (void)sendMessage:(id _Nullable)message; /** * Sends the specified message to the Flutter side, expecting an asynchronous * reply. * * @param message The message. Must be supported by the codec of this channel. * @param callback A callback to be invoked with the message reply from Flutter. */ - (void)sendMessage:(id _Nullable)message reply:(FlutterReply _Nullable)callback; /** * Registers a message handler with this channel. * * Replaces any existing handler. Use a `nil` handler for unregistering the * existing handler. * * @param handler The message handler. */ - (void)setMessageHandler:(FlutterMessageHandler _Nullable)handler; /** * Adjusts the number of messages that will get buffered when sending messages to * channels that aren't fully set up yet. For example, the engine isn't running * yet or the channel's message handler isn't set up on the Dart side yet. * * @param name The channel name. * @param messenger The binary messenger. * @param newSize The number of messages that will get buffered. */ + (void)resizeChannelWithName:(NSString*)name binaryMessenger:(NSObject*)messenger size:(NSInteger)newSize; /** * Adjusts the number of messages that will get buffered when sending messages to * channels that aren't fully set up yet. For example, the engine isn't running * yet or the channel's message handler isn't set up on the Dart side yet. * * @param newSize The number of messages that will get buffered. */ - (void)resizeChannelBuffer:(NSInteger)newSize; /** * Defines whether the channel should show warning messages when discarding messages * due to overflow. * * @param warns When false, the channel is expected to overflow and warning messages * will not be shown. * @param name The channel name. * @param messenger The binary messenger. */ + (void)setWarnsOnOverflow:(BOOL)warns forChannelWithName:(NSString*)name binaryMessenger:(NSObject*)messenger; /** * Defines whether the channel should show warning messages when discarding messages * due to overflow. * * @param warns When false, the channel is expected to overflow and warning messages * will not be shown. */ - (void)setWarnsOnOverflow:(BOOL)warns; @end /** * A method call result callback. * * Used for submitting a method call result back to a Flutter caller. Also used in * the dual capacity for handling a method call result received from Flutter. * * @param result The result. */ typedef void (^FlutterResult)(id _Nullable result); /** * A strategy for handling method calls. * * @param call The incoming method call. * @param result A callback to asynchronously submit the result of the call. * Invoke the callback with a `FlutterError` to indicate that the call failed. * Invoke the callback with `FlutterMethodNotImplemented` to indicate that the * method was unknown. Any other values, including `nil`, are interpreted as * successful results. This can be invoked from any thread. */ typedef void (^FlutterMethodCallHandler)(FlutterMethodCall* call, FlutterResult result); /** * A constant used with `FlutterMethodCallHandler` to respond to the call of an * unknown method. */ FLUTTER_DARWIN_EXPORT extern NSObject const* FlutterMethodNotImplemented; /** * A channel for communicating with the Flutter side using invocation of * asynchronous methods. */ FLUTTER_DARWIN_EXPORT @interface FlutterMethodChannel : NSObject /** * Creates a `FlutterMethodChannel` with the specified name and binary messenger. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * The channel uses `FlutterStandardMethodCodec` to encode and decode method calls * and result envelopes. * * @param name The channel name. * @param messenger The binary messenger. */ + (instancetype)methodChannelWithName:(NSString*)name binaryMessenger:(NSObject*)messenger; /** * Creates a `FlutterMethodChannel` with the specified name, binary messenger, and * method codec. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * @param name The channel name. * @param messenger The binary messenger. * @param codec The method codec. */ + (instancetype)methodChannelWithName:(NSString*)name binaryMessenger:(NSObject*)messenger codec:(NSObject*)codec; /** * Initializes a `FlutterMethodChannel` with the specified name, binary messenger, * and method codec. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * @param name The channel name. * @param messenger The binary messenger. * @param codec The method codec. */ - (instancetype)initWithName:(NSString*)name binaryMessenger:(NSObject*)messenger codec:(NSObject*)codec; /** * Initializes a `FlutterMethodChannel` with the specified name, binary messenger, * method codec, and task queue. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * @param name The channel name. * @param messenger The binary messenger. * @param codec The method codec. * @param taskQueue The FlutterTaskQueue that executes the handler (see -[FlutterBinaryMessenger makeBackgroundTaskQueue]). */ - (instancetype)initWithName:(NSString*)name binaryMessenger:(NSObject*)messenger codec:(NSObject*)codec taskQueue:(NSObject* _Nullable)taskQueue; // clang-format off /** * Invokes the specified Flutter method with the specified arguments, expecting * no results. * * @see [MethodChannel.setMethodCallHandler](https://api.flutter.dev/flutter/services/MethodChannel/setMethodCallHandler.html) * * @param method The name of the method to invoke. * @param arguments The arguments. Must be a value supported by the codec of this * channel. */ // clang-format on - (void)invokeMethod:(NSString*)method arguments:(id _Nullable)arguments; /** * Invokes the specified Flutter method with the specified arguments, expecting * an asynchronous result. * * @param method The name of the method to invoke. * @param arguments The arguments. Must be a value supported by the codec of this * channel. * @param callback A callback that will be invoked with the asynchronous result. * The result will be a `FlutterError` instance, if the method call resulted * in an error on the Flutter side. Will be `FlutterMethodNotImplemented`, if * the method called was not implemented on the Flutter side. Any other value, * including `nil`, should be interpreted as successful results. */ - (void)invokeMethod:(NSString*)method arguments:(id _Nullable)arguments result:(FlutterResult _Nullable)callback; /** * Registers a handler for method calls from the Flutter side. * * Replaces any existing handler. Use a `nil` handler for unregistering the * existing handler. * * @param handler The method call handler. */ - (void)setMethodCallHandler:(FlutterMethodCallHandler _Nullable)handler; /** * Adjusts the number of messages that will get buffered when sending messages to * channels that aren't fully set up yet. For example, the engine isn't running * yet or the channel's message handler isn't set up on the Dart side yet. */ - (void)resizeChannelBuffer:(NSInteger)newSize; @end /** * An event sink callback. * * @param event The event. */ typedef void (^FlutterEventSink)(id _Nullable event); /** * A strategy for exposing an event stream to the Flutter side. */ FLUTTER_DARWIN_EXPORT @protocol FlutterStreamHandler /** * Sets up an event stream and begin emitting events. * * Invoked when the first listener is registered with the Stream associated to * this channel on the Flutter side. * * @param arguments Arguments for the stream. * @param events A callback to asynchronously emit events. Invoke the * callback with a `FlutterError` to emit an error event. Invoke the * callback with `FlutterEndOfEventStream` to indicate that no more * events will be emitted. Any other value, including `nil` are emitted as * successful events. * @return A FlutterError instance, if setup fails. */ - (FlutterError* _Nullable)onListenWithArguments:(id _Nullable)arguments eventSink:(FlutterEventSink)events; /** * Tears down an event stream. * * Invoked when the last listener is deregistered from the Stream associated to * this channel on the Flutter side. * * The channel implementation may call this method with `nil` arguments * to separate a pair of two consecutive set up requests. Such request pairs * may occur during Flutter hot restart. * * @param arguments Arguments for the stream. * @return A FlutterError instance, if teardown fails. */ - (FlutterError* _Nullable)onCancelWithArguments:(id _Nullable)arguments; @end /** * A constant used with `FlutterEventChannel` to indicate end of stream. */ FLUTTER_DARWIN_EXPORT extern NSObject const* FlutterEndOfEventStream; /** * A channel for communicating with the Flutter side using event streams. */ FLUTTER_DARWIN_EXPORT @interface FlutterEventChannel : NSObject /** * Creates a `FlutterEventChannel` with the specified name and binary messenger. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterViewController`. * * The channel uses `FlutterStandardMethodCodec` to decode stream setup and * teardown requests, and to encode event envelopes. * * @param name The channel name. * @param messenger The binary messenger. */ + (instancetype)eventChannelWithName:(NSString*)name binaryMessenger:(NSObject*)messenger; /** * Creates a `FlutterEventChannel` with the specified name, binary messenger, * and method codec. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterViewController`. * * @param name The channel name. * @param messenger The binary messenger. * @param codec The method codec. */ + (instancetype)eventChannelWithName:(NSString*)name binaryMessenger:(NSObject*)messenger codec:(NSObject*)codec; /** * Initializes a `FlutterEventChannel` with the specified name, binary messenger, * and method codec. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * @param name The channel name. * @param messenger The binary messenger. * @param codec The method codec. */ - (instancetype)initWithName:(NSString*)name binaryMessenger:(NSObject*)messenger codec:(NSObject*)codec; /** * Initializes a `FlutterEventChannel` with the specified name, binary messenger, * method codec and task queue. * * The channel name logically identifies the channel; identically named channels * interfere with each other's communication. * * The binary messenger is a facility for sending raw, binary messages to the * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. * * @param name The channel name. * @param messenger The binary messenger. * @param codec The method codec. * @param taskQueue The FlutterTaskQueue that executes the handler (see -[FlutterBinaryMessenger makeBackgroundTaskQueue]). */ - (instancetype)initWithName:(NSString*)name binaryMessenger:(NSObject*)messenger codec:(NSObject*)codec taskQueue:(NSObject* _Nullable)taskQueue; /** * Registers a handler for stream setup requests from the Flutter side. * * Replaces any existing handler. Use a `nil` handler for unregistering the * existing handler. * * @param handler The stream handler. */ - (void)setStreamHandler:(NSObject* _Nullable)handler; @end NS_ASSUME_NONNULL_END #endif // FLUTTER_SHELL_PLATFORM_DARWIN_COMMON_FRAMEWORK_HEADERS_FLUTTERCHANNELS_H_