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 #include "FlutterBinaryMessenger.h" 9 #include "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. 28 */ 29 typedef void (^FlutterMessageHandler)(id _Nullable message, FlutterReply callback); 30 31 /** 32 * A channel for communicating with the Flutter side using basic, asynchronous 33 * message passing. 34 */ 35 FLUTTER_EXPORT 36 @interface FlutterBasicMessageChannel : NSObject 37 /** 38 * Creates a `FlutterBasicMessageChannel` with the specified name and binary 39 * messenger. 40 * 41 * The channel name logically identifies the channel; identically named channels 42 * interfere with each other's communication. 43 * 44 * The binary messenger is a facility for sending raw, binary messages to the 45 * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. 46 * 47 * The channel uses `FlutterStandardMessageCodec` to encode and decode messages. 48 * 49 * @param name The channel name. 50 * @param messenger The binary messenger. 51 */ 52 + (instancetype)messageChannelWithName:(NSString*)name 53 binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger; 54 55 /** 56 * Creates a `FlutterBasicMessageChannel` with the specified name, binary 57 * messenger, and message codec. 58 * 59 * The channel name logically identifies the channel; identically named channels 60 * interfere with each other's communication. 61 * 62 * The binary messenger is a facility for sending raw, binary messages to the 63 * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. 64 * 65 * @param name The channel name. 66 * @param messenger The binary messenger. 67 * @param codec The message codec. 68 */ 69 + (instancetype)messageChannelWithName:(NSString*)name 70 binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger 71 codec:(NSObject<FlutterMessageCodec>*)codec; 72 73 /** 74 * Initializes a `FlutterBasicMessageChannel` with the specified name, binary 75 * messenger, and message codec. 76 * 77 * The channel name logically identifies the channel; identically named channels 78 * interfere with each other's communication. 79 * 80 * The binary messenger is a facility for sending raw, binary messages to the 81 * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. 82 * 83 * @param name The channel name. 84 * @param messenger The binary messenger. 85 * @param codec The message codec. 86 */ 87 - (instancetype)initWithName:(NSString*)name 88 binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger 89 codec:(NSObject<FlutterMessageCodec>*)codec; 90 91 /** 92 * Sends the specified message to the Flutter side, ignoring any reply. 93 * 94 * @param message The message. Must be supported by the codec of this 95 * channel. 96 */ 97 - (void)sendMessage:(id _Nullable)message; 98 99 /** 100 * Sends the specified message to the Flutter side, expecting an asynchronous 101 * reply. 102 * 103 * @param message The message. Must be supported by the codec of this channel. 104 * @param callback A callback to be invoked with the message reply from Flutter. 105 */ 106 - (void)sendMessage:(id _Nullable)message reply:(FlutterReply _Nullable)callback; 107 108 /** 109 * Registers a message handler with this channel. 110 * 111 * Replaces any existing handler. Use a `nil` handler for unregistering the 112 * existing handler. 113 * 114 * @param handler The message handler. 115 */ 116 - (void)setMessageHandler:(FlutterMessageHandler _Nullable)handler; 117 @end 118 119 /** 120 * A method call result callback. 121 * 122 * Used for submitting a method call result back to a Flutter caller. Also used in 123 * the dual capacity for handling a method call result received from Flutter. 124 * 125 * @param result The result. 126 */ 127 typedef void (^FlutterResult)(id _Nullable result); 128 129 /** 130 * A strategy for handling method calls. 131 * 132 * @param call The incoming method call. 133 * @param result A callback to asynchronously submit the result of the call. 134 * Invoke the callback with a `FlutterError` to indicate that the call failed. 135 * Invoke the callback with `FlutterMethodNotImplemented` to indicate that the 136 * method was unknown. Any other values, including `nil`, are interpreted as 137 * successful results. 138 */ 139 typedef void (^FlutterMethodCallHandler)(FlutterMethodCall* call, FlutterResult result); 140 141 /** 142 * A constant used with `FlutterMethodCallHandler` to respond to the call of an 143 * unknown method. 144 */ 145 FLUTTER_EXPORT 146 extern NSObject const* FlutterMethodNotImplemented; 147 148 /** 149 * A channel for communicating with the Flutter side using invocation of 150 * asynchronous methods. 151 */ 152 FLUTTER_EXPORT 153 @interface FlutterMethodChannel : NSObject 154 /** 155 * Creates a `FlutterMethodChannel` with the specified name and binary messenger. 156 * 157 * The channel name logically identifies the channel; identically named channels 158 * interfere with each other's communication. 159 * 160 * The binary messenger is a facility for sending raw, binary messages to the 161 * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. 162 * 163 * The channel uses `FlutterStandardMethodCodec` to encode and decode method calls 164 * and result envelopes. 165 * 166 * @param name The channel name. 167 * @param messenger The binary messenger. 168 */ 169 + (instancetype)methodChannelWithName:(NSString*)name 170 binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger; 171 172 /** 173 * Creates a `FlutterMethodChannel` with the specified name, binary messenger, and 174 * method codec. 175 * 176 * The channel name logically identifies the channel; identically named channels 177 * interfere with each other's communication. 178 * 179 * The binary messenger is a facility for sending raw, binary messages to the 180 * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. 181 * 182 * @param name The channel name. 183 * @param messenger The binary messenger. 184 * @param codec The method codec. 185 */ 186 + (instancetype)methodChannelWithName:(NSString*)name 187 binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger 188 codec:(NSObject<FlutterMethodCodec>*)codec; 189 190 /** 191 * Initializes a `FlutterMethodChannel` with the specified name, binary messenger, 192 * and method codec. 193 * 194 * The channel name logically identifies the channel; identically named channels 195 * interfere with each other's communication. 196 * 197 * The binary messenger is a facility for sending raw, binary messages to the 198 * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. 199 * 200 * @param name The channel name. 201 * @param messenger The binary messenger. 202 * @param codec The method codec. 203 */ 204 - (instancetype)initWithName:(NSString*)name 205 binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger 206 codec:(NSObject<FlutterMethodCodec>*)codec; 207 208 // clang-format off 209 /** 210 * Invokes the specified Flutter method with the specified arguments, expecting 211 * no results. 212 * 213 * @see [MethodChannel.setMethodCallHandler](https://docs.flutter.io/flutter/services/MethodChannel/setMethodCallHandler.html) 214 * 215 * @param method The name of the method to invoke. 216 * @param arguments The arguments. Must be a value supported by the codec of this 217 * channel. 218 */ 219 // clang-format on 220 - (void)invokeMethod:(NSString*)method arguments:(id _Nullable)arguments; 221 222 /** 223 * Invokes the specified Flutter method with the specified arguments, expecting 224 * an asynchronous result. 225 * 226 * @param method The name of the method to invoke. 227 * @param arguments The arguments. Must be a value supported by the codec of this 228 * channel. 229 * @param callback A callback that will be invoked with the asynchronous result. 230 * The result will be a `FlutterError` instance, if the method call resulted 231 * in an error on the Flutter side. Will be `FlutterMethodNotImplemented`, if 232 * the method called was not implemented on the Flutter side. Any other value, 233 * including `nil`, should be interpreted as successful results. 234 */ 235 - (void)invokeMethod:(NSString*)method 236 arguments:(id _Nullable)arguments 237 result:(FlutterResult _Nullable)callback 238 // TODO: Add macOS support for replies once 239 // https://github.com/flutter/flutter/issues/18852 is fixed. 240 API_UNAVAILABLE(macos); 241 242 /** 243 * Registers a handler for method calls from the Flutter side. 244 * 245 * Replaces any existing handler. Use a `nil` handler for unregistering the 246 * existing handler. 247 * 248 * @param handler The method call handler. 249 */ 250 - (void)setMethodCallHandler:(FlutterMethodCallHandler _Nullable)handler; 251 @end 252 253 /** 254 * An event sink callback. 255 * 256 * @param event The event. 257 */ 258 typedef void (^FlutterEventSink)(id _Nullable event); 259 260 /** 261 * A strategy for exposing an event stream to the Flutter side. 262 */ 263 FLUTTER_EXPORT 264 @protocol FlutterStreamHandler 265 /** 266 * Sets up an event stream and begin emitting events. 267 * 268 * Invoked when the first listener is registered with the Stream associated to 269 * this channel on the Flutter side. 270 * 271 * @param arguments Arguments for the stream. 272 * @param events A callback to asynchronously emit events. Invoke the 273 * callback with a `FlutterError` to emit an error event. Invoke the 274 * callback with `FlutterEndOfEventStream` to indicate that no more 275 * events will be emitted. Any other value, including `nil` are emitted as 276 * successful events. 277 * @return A FlutterError instance, if setup fails. 278 */ 279 - (FlutterError* _Nullable)onListenWithArguments:(id _Nullable)arguments 280 eventSink:(FlutterEventSink)events; 281 282 /** 283 * Tears down an event stream. 284 * 285 * Invoked when the last listener is deregistered from the Stream associated to 286 * this channel on the Flutter side. 287 * 288 * The channel implementation may call this method with `nil` arguments 289 * to separate a pair of two consecutive set up requests. Such request pairs 290 * may occur during Flutter hot restart. 291 * 292 * @param arguments Arguments for the stream. 293 * @return A FlutterError instance, if teardown fails. 294 */ 295 - (FlutterError* _Nullable)onCancelWithArguments:(id _Nullable)arguments; 296 @end 297 298 /** 299 * A constant used with `FlutterEventChannel` to indicate end of stream. 300 */ 301 FLUTTER_EXPORT 302 extern NSObject const* FlutterEndOfEventStream; 303 304 /** 305 * A channel for communicating with the Flutter side using event streams. 306 */ 307 FLUTTER_EXPORT 308 @interface FlutterEventChannel : NSObject 309 /** 310 * Creates a `FlutterEventChannel` with the specified name and binary messenger. 311 * 312 * The channel name logically identifies the channel; identically named channels 313 * interfere with each other's communication. 314 * 315 * The binary messenger is a facility for sending raw, binary messages to the 316 * Flutter side. This protocol is implemented by `FlutterViewController`. 317 * 318 * The channel uses `FlutterStandardMethodCodec` to decode stream setup and 319 * teardown requests, and to encode event envelopes. 320 * 321 * @param name The channel name. 322 * @param messenger The binary messenger. 323 */ 324 + (instancetype)eventChannelWithName:(NSString*)name 325 binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger; 326 327 /** 328 * Creates a `FlutterEventChannel` with the specified name, binary messenger, 329 * and method codec. 330 * 331 * The channel name logically identifies the channel; identically named channels 332 * interfere with each other's communication. 333 * 334 * The binary messenger is a facility for sending raw, binary messages to the 335 * Flutter side. This protocol is implemented by `FlutterViewController`. 336 * 337 * @param name The channel name. 338 * @param messenger The binary messenger. 339 * @param codec The method codec. 340 */ 341 + (instancetype)eventChannelWithName:(NSString*)name 342 binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger 343 codec:(NSObject<FlutterMethodCodec>*)codec; 344 345 /** 346 * Initializes a `FlutterEventChannel` with the specified name, binary messenger, 347 * and method codec. 348 * 349 * The channel name logically identifies the channel; identically named channels 350 * interfere with each other's communication. 351 * 352 * The binary messenger is a facility for sending raw, binary messages to the 353 * Flutter side. This protocol is implemented by `FlutterEngine` and `FlutterViewController`. 354 * 355 * @param name The channel name. 356 * @param messenger The binary messenger. 357 * @param codec The method codec. 358 */ 359 - (instancetype)initWithName:(NSString*)name 360 binaryMessenger:(NSObject<FlutterBinaryMessenger>*)messenger 361 codec:(NSObject<FlutterMethodCodec>*)codec; 362 /** 363 * Registers a handler for stream setup requests from the Flutter side. 364 * 365 * Replaces any existing handler. Use a `nil` handler for unregistering the 366 * existing handler. 367 * 368 * @param handler The stream handler. 369 */ 370 - (void)setStreamHandler:(NSObject<FlutterStreamHandler>* _Nullable)handler; 371 @end 372 NS_ASSUME_NONNULL_END 373 374 #endif // FLUTTER_FLUTTERCHANNELS_H_ 375