diff --git a/packages/flutter/lib/src/services/message_codec.dart b/packages/flutter/lib/src/services/message_codec.dart index 7cf3620b59..b36043872f 100644 --- a/packages/flutter/lib/src/services/message_codec.dart +++ b/packages/flutter/lib/src/services/message_codec.dart @@ -21,12 +21,12 @@ import 'platform_channel.dart'; abstract class MessageCodec { /// Encodes the specified [message] in binary. /// - /// Returns `null` if the message is `null`. + /// Returns null if the message is null. ByteData encodeMessage(T message); /// Decodes the specified [message] from binary. /// - /// Returns `null` if the message is `null`. + /// Returns null if the message is null. T decodeMessage(ByteData message); } @@ -155,10 +155,10 @@ class PlatformException implements Exception { /// An error code. final String code; - /// A human-readable error message, possibly `null`. + /// A human-readable error message, possibly null. final String message; - /// Error details, possibly `null`. + /// Error details, possibly null. final dynamic details; @override @@ -174,13 +174,13 @@ class PlatformException implements Exception { /// with a [MissingPluginException], if no plugin handler for the method call /// was found. /// * [OptionalMethodChannel.invokeMethod], which completes the returned future -/// with `null`, if no plugin handler for the method call was found. +/// with null, if no plugin handler for the method call was found. class MissingPluginException implements Exception { /// Creates a [MissingPluginException] with an optional human-readable /// error message. MissingPluginException([this.message]); - /// A human-readable error message, possibly `null`. + /// A human-readable error message, possibly null. final String message; @override diff --git a/packages/flutter/lib/src/services/message_codecs.dart b/packages/flutter/lib/src/services/message_codecs.dart index 9e10b51f54..a369889b79 100644 --- a/packages/flutter/lib/src/services/message_codecs.dart +++ b/packages/flutter/lib/src/services/message_codecs.dart @@ -10,6 +10,9 @@ import 'package:flutter/foundation.dart' show ReadBuffer, WriteBuffer, required; import 'message_codec.dart'; /// [MessageCodec] with unencoded binary messages represented using [ByteData]. +/// +/// On Android, messages will be represented using `java.nio.ByteBuffer`. +/// On iOS, messages will be represented using `NSData`. class BinaryCodec implements MessageCodec { /// Creates a [MessageCodec] with unencoded binary messages represented using /// [ByteData]. @@ -23,6 +26,9 @@ class BinaryCodec implements MessageCodec { } /// [MessageCodec] with UTF-8 encoded String messages. +/// +/// On Android, messages will be represented using `java.util.String`. +/// On iOS, messages will be represented using `NSString`. class StringCodec implements MessageCodec { /// Creates a [MessageCodec] with UTF-8 encoded String messages. const StringCodec(); @@ -47,12 +53,20 @@ class StringCodec implements MessageCodec { /// /// Supported messages are acyclic values of these forms: /// -/// * `null` +/// * null /// * [bool]s /// * [num]s /// * [String]s /// * [List]s of supported values /// * [Map]s from strings to supported values +/// +/// On Android, messages are decoded using the `org.json` library. +/// On iOS, messages are decoded using the `NSJSONSerialization` library. +/// In both cases, the use of top-level simple messages (null, [bool], [num], +/// and [String]) is supported (by the Flutter SDK). The decoded value will be +/// null/nil for null, and identical to what would result from decoding a +/// singleton JSON array with a Boolean, number, or string value, and then +/// extracting its single element. class JSONMessageCodec implements MessageCodec { // The codec serializes messages as defined by the JSON codec of the // dart:convert package. The format used must match the Android and @@ -156,13 +170,45 @@ class JSONMethodCodec implements MethodCodec { /// /// Supported messages are acyclic values of these forms: /// -/// * `null` +/// * null /// * [bool]s /// * [num]s /// * [String]s /// * [Uint8List]s, [Int32List]s, [Int64List]s, [Float64List]s /// * [List]s of supported values /// * [Map]s from supported values to supported values +/// +/// On Android, messages are represented as follows: +/// +/// * null: null +/// * [bool]: `java.lang.Boolean` +/// * [int]: `java.lang.Integer` for values that are representable using 32-bit +/// two's complement; otherwise, `java.lang.Long` for values that are +/// representable using 64-bit two's complement; otherwise, +/// `java.math.BigInteger`. +/// * [double]: `java.lang.Double` +/// * [String]: `java.lang.String` +/// * [Uint8List]: `byte[]` +/// * [Int32List]: `int[]` +/// * [Int64List]: `long[]` +/// * [Float64List]: `double[]` +/// * [List]: `java.util.ArrayList` +/// * [Map]: `java.util.HashMap` +/// +/// On iOS, messages are represented as follows: +/// +/// * null: nil +/// * [bool]: `NSNumber numberWithBool:` +/// * [int]: `NSNumber numberWithInt:` for values that are representable using +/// 32-bit two's complement; otherwise, `NSNumber numberWithLong:` for values +/// that are representable using 64-bit two's complement; otherwise, +/// `FlutterStandardBigInteger`. +/// * [double]: `NSNumber numberWithDouble:` +/// * [String]: `NSString` +/// * [Uint8List], [Int32List], [Int64List], [Float64List]: +/// `FlutterStandardTypedData` +/// * [List]: `NSArray` +/// * [Map]: `NSDictionary` class StandardMessageCodec implements MessageCodec { // The codec serializes messages as outlined below. This format must // match the Android and iOS counterparts. diff --git a/packages/flutter/lib/src/services/platform_channel.dart b/packages/flutter/lib/src/services/platform_channel.dart index a766ff9af8..880af4c127 100644 --- a/packages/flutter/lib/src/services/platform_channel.dart +++ b/packages/flutter/lib/src/services/platform_channel.dart @@ -21,7 +21,7 @@ import 'platform_messages.dart'; /// platform side. The Dart type of messages sent and received is [T], /// but only the values supported by the specified [MessageCodec] can be used. /// The use of unsupported values should be considered programming errors, and -/// will result in exceptions being thrown. The `null` message is supported +/// will result in exceptions being thrown. The null message is supported /// for all codecs. /// /// The logical identity of the channel is given by its name. Identically named @@ -31,32 +31,32 @@ import 'platform_messages.dart'; class BasicMessageChannel { /// Creates a [BasicMessageChannel] with the specified [name] and [codec]. /// - /// Neither [name] nor [codec] may be `null`. + /// Neither [name] nor [codec] may be null. const BasicMessageChannel(this.name, this.codec); - /// The logical channel on which communication happens, not `null`. + /// The logical channel on which communication happens, not null. final String name; - /// The message codec used by this channel, not `null`. + /// The message codec used by this channel, not null. final MessageCodec codec; /// Sends the specified [message] to the platform plugins on this channel. /// /// Returns a [Future] which completes to the received response, which may - /// be `null`. + /// be null. Future send(T message) async { return codec.decodeMessage(await BinaryMessages.send(name, codec.encodeMessage(message))); } /// Sets a callback for receiving messages from the platform plugins on this - /// channel. Messages may be `null`. + /// channel. Messages may be null. /// /// The given callback will replace the currently registered callback for this - /// channel, if any. To remove the handler, pass `null` as the `handler` + /// channel, if any. To remove the handler, pass null as the `handler` /// argument. /// /// The handler's return value is sent back to the platform plugins as a - /// message reply. It may be `null`. + /// message reply. It may be null. void setMessageHandler(Future handler(T message)) { if (handler == null) { BinaryMessages.setMessageHandler(name, null); @@ -68,13 +68,13 @@ class BasicMessageChannel { } /// Sets a mock callback for intercepting messages sent on this channel. - /// Messages may be `null`. + /// Messages may be null. /// /// The given callback will replace the currently registered mock callback for - /// this channel, if any. To remove the mock handler, pass `null` as the + /// this channel, if any. To remove the mock handler, pass null as the /// `handler` argument. /// - /// The handler's return value is used as a message reply. It may be `null`. + /// The handler's return value is used as a message reply. It may be null. /// /// This is intended for testing. Messages intercepted in this manner are not /// sent to platform plugins. @@ -99,7 +99,7 @@ class BasicMessageChannel { /// platform side. The Dart type of arguments and results is `dynamic`, /// but only values supported by the specified [MethodCodec] can be used. /// The use of unsupported values should be considered programming errors, and -/// will result in exceptions being thrown. The `null` value is supported +/// will result in exceptions being thrown. The null value is supported /// for all codecs. /// /// The logical identity of the channel is given by its name. Identically named @@ -112,20 +112,20 @@ class MethodChannel { /// The [codec] used will be [StandardMethodCodec], unless otherwise /// specified. /// - /// Neither [name] nor [codec] may be `null`. + /// Neither [name] nor [codec] may be null. const MethodChannel(this.name, [this.codec = const StandardMethodCodec()]); - /// The logical channel on which communication happens, not `null`. + /// The logical channel on which communication happens, not null. final String name; - /// The message codec used by this channel, not `null`. + /// The message codec used by this channel, not null. final MethodCodec codec; /// Invokes a [method] on this channel with the specified [arguments]. /// /// Returns a [Future] which completes to one of the following: /// - /// * a result (possibly `null`), on successful invocation; + /// * a result (possibly null), on successful invocation; /// * a [PlatformException], if the invocation failed in the platform plugin; /// * a [MissingPluginException], if the method has not been implemented by a /// platform plugin. @@ -143,7 +143,7 @@ class MethodChannel { /// Sets a callback for receiving method calls on this channel. /// /// The given callback will replace the currently registered callback for this - /// channel, if any. To remove the handler, pass `null` as the + /// channel, if any. To remove the handler, pass null as the /// `handler` argument. /// /// If the future returned by the handler completes with a result, that value @@ -164,7 +164,7 @@ class MethodChannel { /// Sets a mock callback for intercepting method invocations on this channel. /// /// The given callback will replace the currently registered mock callback for - /// this channel, if any. To remove the mock handler, pass `null` as the + /// this channel, if any. To remove the mock handler, pass null as the /// `handler` argument. /// /// Later calls to [invokeMethod] will result in a successful result, @@ -238,20 +238,20 @@ class EventChannel { /// The [codec] used will be [StandardMethodCodec], unless otherwise /// specified. /// - /// Neither [name] nor [codec] may be `null`. + /// Neither [name] nor [codec] may be null. const EventChannel(this.name, [this.codec = const StandardMethodCodec()]); - /// The logical channel on which communication happens, not `null`. + /// The logical channel on which communication happens, not null. final String name; - /// The message codec used by this channel, not `null`. + /// The message codec used by this channel, not null. final MethodCodec codec; /// Sets up a broadcast stream for receiving events on this channel. /// /// Returns a broadcast [Stream] which emits events to listeners as follows: /// - /// * a decoded data event (possibly `null`) for each successful event + /// * a decoded data event (possibly null) for each successful event /// received from the platform plugin; /// * an error event containing a [PlatformException] for each error event /// received from the platform plugin; diff --git a/packages/flutter/lib/src/services/platform_messages.dart b/packages/flutter/lib/src/services/platform_messages.dart index 8cb40ba483..19a0131b22 100644 --- a/packages/flutter/lib/src/services/platform_messages.dart +++ b/packages/flutter/lib/src/services/platform_messages.dart @@ -92,7 +92,7 @@ class BinaryMessages { /// given channel, without decoding them. /// /// The given callback will replace the currently registered callback for that - /// channel, if any. To remove the handler, pass `null` as the `handler` + /// channel, if any. To remove the handler, pass null as the `handler` /// argument. /// /// The handler's return value, if non-null, is sent as a response, unencoded. @@ -107,7 +107,7 @@ class BinaryMessages { /// this class, on the given channel, without decoding them. /// /// The given callback will replace the currently registered mock callback for - /// that channel, if any. To remove the mock handler, pass `null` as the + /// that channel, if any. To remove the mock handler, pass null as the /// `handler` argument. /// /// The handler's return value, if non-null, is used as a response, unencoded.