[macOS] Add FLEEventChannel (#174)

Adds more parity with mobile Flutter plugin APIs.

Fixes #173

Author: cloudwebrtc

library/macos/FLEEventChannel.h

@@ -0,0 +1,107 @@
+// Copyright 2018 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#import <Foundation/Foundation.h>
+
+#import "FLEBinaryMessenger.h"
+#import "FLEMethodCodec.h"
+
+/**
+ * An event sink callback.
+ *
+ * @param event The event.
+ */
+typedef void (^FLEEventSink)(id _Nullable event);
+
+/**
+ * A constant used with `FLEEventChannel` to indicate end of stream.
+ */
+extern NSString const *_Nonnull FLEEndOfEventStream;
+
+/**
+ * A strategy for exposing an event stream to the Flutter side.
+ */
+@protocol FLEStreamHandler
+
+/**
+ * Sets up an event stream and begins 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 `FLEMethodError` to emit an error event. Invoke the
+ *     callback with `FLEEndOfEventStream` to indicate that no more
+ *     events will be emitted. Any other value, including `nil` are emitted as
+ *     successful events.
+ * @return A FLEMethodError instance, if setup fails.
+ */
+- (nullable FLEMethodError *)onListenWithArguments:(nullable id)arguments
+                                         eventSink:(FLEEventSink _Nonnull)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 FLEMethodError instance, if teardown fails.
+ */
+- (nullable FLEMethodError *)onCancelWithArguments:(nullable id)arguments;
+
+@end
+
+/**
+ * A channel for communicating with the Flutter side using event streams.
+ */
+@interface FLEEventChannel : NSObject
+
+/**
+ * Creates a `FLEEventChannel` 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.
+ *
+ * The channel uses `FLEMethodCodec` to decode stream setup and
+ * teardown requests, and to encode event envelopes.
+ *
+ * @param name The channel name.
+ * @param messenger The binary messenger.
+ * @param codec The method codec.
+ * @return A new channel.
+ */
++ (nonnull instancetype)eventChannelWithName:(nonnull NSString *)name
+                             binaryMessenger:(nonnull id<FLEBinaryMessenger>)messenger
+                                       codec:(nonnull id<FLEMethodCodec>)codec;
+
+/**
+ * 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:(nullable id<FLEStreamHandler>)handler;
+
+@end

library/macos/FLEEventChannel.m

@@ -0,0 +1,102 @@
+// Copyright 2018 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#import "FLEEventChannel.h"
+
+NSString const *FLEEndOfEventStream = @"EndOfEventStream";
+
+@implementation FLEEventChannel {
+  NSString *_name;
+  __weak id<FLEBinaryMessenger> _messenger;
+  id<FLEMethodCodec> _codec;
+}
+
++ (instancetype)eventChannelWithName:(NSString *)name
+                     binaryMessenger:(id<FLEBinaryMessenger>)messenger
+                               codec:(id<FLEMethodCodec>)codec {
+  return [[[self class] alloc] initWithName:name binaryMessenger:messenger codec:codec];
+}
+
+- (instancetype)initWithName:(NSString *)name
+             binaryMessenger:(id<FLEBinaryMessenger>)messenger
+                       codec:(id<FLEMethodCodec>)codec {
+  self = [super init];
+  if (self) {
+    _name = [name copy];
+    _messenger = messenger;
+    _codec = codec;
+  }
+  return self;
+}
+
+- (void)setStreamHandler:(NSObject<FLEStreamHandler> *)handler {
+  if (!handler) {
+    [_messenger setMessageHandlerOnChannel:_name binaryMessageHandler:nil];
+    return;
+  }
+
+  id<FLEMethodCodec> codec = _codec;
+  __weak id<FLEBinaryMessenger> messenger = _messenger;
+  NSString *name = _name;
+  FLEEventSink eventSink = ^(id event) {
+    if (event == FLEEndOfEventStream) {
+      [messenger sendOnChannel:name message:nil];
+    } else if ([event isKindOfClass:[FLEMethodError class]]) {
+      [messenger sendOnChannel:name message:[codec encodeErrorEnvelope:(FLEMethodError *)event]];
+    } else {
+      [messenger sendOnChannel:name message:[codec encodeSuccessEnvelope:event]];
+    }
+  };
+
+  __block FLEEventSink currentSink = nil;
+  FLEBinaryMessageHandler messageHandler = ^(NSData *message, FLEBinaryReply callback) {
+    FLEMethodCall *call = [codec decodeMethodCall:message];
+    if ([call.methodName isEqual:@"listen"]) {
+      if (currentSink) {
+        FLEMethodError *error = [handler onCancelWithArguments:nil];
+        if (error) {
+          NSLog(@"Failed to cancel existing stream: %@. %@ (%@)", error.code, error.message,
+                error.details);
+        }
+      }
+      currentSink = eventSink;
+      FLEMethodError *error = [handler onListenWithArguments:call.arguments eventSink:currentSink];
+      if (error) {
+        callback([codec encodeErrorEnvelope:error]);
+      } else {
+        callback([codec encodeSuccessEnvelope:nil]);
+      }
+    } else if ([call.methodName isEqual:@"cancel"]) {
+      if (!currentSink) {
+        callback([codec
+            encodeErrorEnvelope:[[FLEMethodError alloc] initWithCode:@"error"
+                                                             message:@"No active stream to cancel"
+                                                             details:nil]]);
+        return;
+      }
+      currentSink = nil;
+      FLEMethodError *error = [handler onCancelWithArguments:call.arguments];
+      if (error) {
+        callback([codec encodeErrorEnvelope:error]);
+      } else {
+        callback([codec encodeSuccessEnvelope:nil]);
+      }
+    } else {
+      callback(nil);
+    }
+  };
+  [_messenger setMessageHandlerOnChannel:_name binaryMessageHandler:messageHandler];
+}
+
+@end

library/macos/FlutterEmbedderMac.h

@@ -14,6 +14,7 @@
 
 #import "FLEBasicMessageChannel.h"
 #import "FLEBinaryMessenger.h"
+#import "FLEEventChannel.h"
 #import "FLEJSONMessageCodec.h"
 #import "FLEJSONMethodCodec.h"
 #import "FLEMessageCodec.h"

library/macos/FlutterEmbedderMac.xcodeproj/project.pbxproj

@@ -30,6 +30,8 @@
 		1E2492411FCF50BE00DD3BBB /* FlutterEmbedderMac.h in Headers */ = {isa = PBXBuildFile; fileRef = 1E2492371FCF50BE00DD3BBB /* FlutterEmbedderMac.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		1EEF8E071FD1F0C300DD563C /* FLEView.h in Headers */ = {isa = PBXBuildFile; fileRef = 1EEF8E051FD1F0C300DD563C /* FLEView.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		1EEF8E081FD1F0C300DD563C /* FLEView.m in Sources */ = {isa = PBXBuildFile; fileRef = 1EEF8E061FD1F0C300DD563C /* FLEView.m */; };
+		2CCADF9A21C74690001B4026 /* FLEEventChannel.m in Sources */ = {isa = PBXBuildFile; fileRef = 2CCADF9821C74690001B4026 /* FLEEventChannel.m */; };
+		2CCADF9B21C74690001B4026 /* FLEEventChannel.h in Headers */ = {isa = PBXBuildFile; fileRef = 2CCADF9921C74690001B4026 /* FLEEventChannel.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		3389A6872159359200A27898 /* FLEBinaryMessenger.h in Headers */ = {isa = PBXBuildFile; fileRef = 3389A6862159359200A27898 /* FLEBinaryMessenger.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		3389A68D215949CB00A27898 /* FLEMethodError.m in Sources */ = {isa = PBXBuildFile; fileRef = 3389A68C215949CB00A27898 /* FLEMethodError.m */; };
 		3389A68F215949D600A27898 /* FLEMethodError.h in Headers */ = {isa = PBXBuildFile; fileRef = 3389A68E215949D600A27898 /* FLEMethodError.h */; settings = {ATTRIBUTES = (Public, ); }; };
@@ -90,6 +92,8 @@
 		1E2492381FCF50BE00DD3BBB /* Info.plist */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.plist; path = Info.plist; sourceTree = "<group>"; };
 		1EEF8E051FD1F0C300DD563C /* FLEView.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = FLEView.h; sourceTree = "<group>"; };
 		1EEF8E061FD1F0C300DD563C /* FLEView.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = FLEView.m; sourceTree = "<group>"; };
+		2CCADF9821C74690001B4026 /* FLEEventChannel.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = FLEEventChannel.m; sourceTree = "<group>"; };
+		2CCADF9921C74690001B4026 /* FLEEventChannel.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = FLEEventChannel.h; sourceTree = "<group>"; };
 		3389A6862159359200A27898 /* FLEBinaryMessenger.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = FLEBinaryMessenger.h; sourceTree = "<group>"; };
 		3389A68C215949CB00A27898 /* FLEMethodError.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = FLEMethodError.m; sourceTree = "<group>"; };
 		3389A68E215949D600A27898 /* FLEMethodError.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = FLEMethodError.h; sourceTree = "<group>"; };
@@ -132,6 +136,7 @@
 				1E2492371FCF50BE00DD3BBB /* FlutterEmbedderMac.h */,
 				1E2492451FCF536200DD3BBB /* Public */,
 				33C0FA1821B845EF008F8959 /* FLEBasicMessageChannel.m */,
+				2CCADF9821C74690001B4026 /* FLEEventChannel.m */,
 				33C0FA1C21B84810008F8959 /* FLEJSONMessageCodec.m */,
 				33A87EB520F6BCDB0086D21D /* FLEJSONMethodCodec.m */,
 				33C0FA2521B84AA4008F8959 /* FLEMethodCall.m */,
@@ -163,6 +168,7 @@
 			children = (
 				33C0FA1921B845F0008F8959 /* FLEBasicMessageChannel.h */,
 				3389A6862159359200A27898 /* FLEBinaryMessenger.h */,
+				2CCADF9921C74690001B4026 /* FLEEventChannel.h */,
 				33C0FA1E21B84810008F8959 /* FLEJSONMessageCodec.h */,
 				33C0FA1D21B84810008F8959 /* FLEJSONMethodCodec.h */,
 				33C0FA1F21B84810008F8959 /* FLEMessageCodec.h */,
@@ -197,6 +203,7 @@
 			files = (
 				33C0FA2621B84AA4008F8959 /* FLEMethodCall.h in Headers */,
 				1E24923B1FCF50BE00DD3BBB /* FLEPlugin.h in Headers */,
+				2CCADF9B21C74690001B4026 /* FLEEventChannel.h in Headers */,
 				3389A6872159359200A27898 /* FLEBinaryMessenger.h in Headers */,
 				33D7B59920A4F54400296EFC /* FLEMethodChannel.h in Headers */,
 				1E24923F1FCF50BE00DD3BBB /* FLEViewController.h in Headers */,
@@ -317,6 +324,7 @@
 				1E24923E1FCF50BE00DD3BBB /* FLETextInputPlugin.m in Sources */,
 				1EEF8E081FD1F0C300DD563C /* FLEView.m in Sources */,
 				33A87EB720F6BCDB0086D21D /* FLEJSONMethodCodec.m in Sources */,
+				2CCADF9A21C74690001B4026 /* FLEEventChannel.m in Sources */,
 				AA8AE8BA1FD948BA00B6FB31 /* FLETextInputModel.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;