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 5part of engine; 6 7/// A message encoding/decoding mechanism. 8/// 9/// Both operations throw an exception, if conversion fails. Such situations 10/// should be treated as programming errors. 11/// 12/// See also: 13/// 14/// * [BasicMessageChannel], which use [MessageCodec]s for communication 15/// between Flutter and platform plugins. 16abstract class MessageCodec<T> { 17 /// Encodes the specified [message] in binary. 18 /// 19 /// Returns null if the message is null. 20 ByteData encodeMessage(T message); 21 22 /// Decodes the specified [message] from binary. 23 /// 24 /// Returns null if the message is null. 25 T decodeMessage(ByteData message); 26} 27 28/// An command object representing the invocation of a named method. 29@immutable 30class MethodCall { 31 /// Creates a [MethodCall] representing the invocation of [method] with the 32 /// specified [arguments]. 33 const MethodCall(this.method, [this.arguments]) : assert(method != null); 34 35 /// The name of the method to be called. 36 final String method; 37 38 /// The arguments for the method. 39 /// 40 /// Must be a valid value for the [MethodCodec] used. 41 final dynamic arguments; 42 43 @override 44 String toString() => '$runtimeType($method, $arguments)'; 45} 46 47/// A codec for method calls and enveloped results. 48/// 49/// All operations throw an exception, if conversion fails. 50/// 51/// See also: 52/// 53/// * [MethodChannel], which use [MethodCodec]s for communication 54/// between Flutter and platform plugins. 55/// * [EventChannel], which use [MethodCodec]s for communication 56/// between Flutter and platform plugins. 57abstract class MethodCodec { 58 /// Encodes the specified [methodCall] into binary. 59 ByteData encodeMethodCall(MethodCall methodCall); 60 61 /// Decodes the specified [methodCall] from binary. 62 MethodCall decodeMethodCall(ByteData methodCall); 63 64 /// Decodes the specified result [envelope] from binary. 65 /// 66 /// Throws [PlatformException], if [envelope] represents an error, otherwise 67 /// returns the enveloped result. 68 dynamic decodeEnvelope(ByteData envelope); 69 70 /// Encodes a successful [result] into a binary envelope. 71 ByteData encodeSuccessEnvelope(dynamic result); 72 73 /// Encodes an error result into a binary envelope. 74 /// 75 /// The specified error [code], human-readable error [message], and error 76 /// [details] correspond to the fields of [PlatformException]. 77 ByteData encodeErrorEnvelope( 78 {@required String code, String message, dynamic details}); 79} 80 81/// Thrown to indicate that a platform interaction failed in the platform 82/// plugin. 83/// 84/// See also: 85/// 86/// * [MethodCodec], which throws a [PlatformException], if a received result 87/// envelope represents an error. 88/// * [MethodChannel.invokeMethod], which completes the returned future 89/// with a [PlatformException], if invoking the platform plugin method 90/// results in an error envelope. 91/// * [EventChannel.receiveBroadcastStream], which emits 92/// [PlatformException]s as error events, whenever an event received from the 93/// platform plugin is wrapped in an error envelope. 94class PlatformException implements Exception { 95 /// Creates a [PlatformException] with the specified error [code] and optional 96 /// [message], and with the optional error [details] which must be a valid 97 /// value for the [MethodCodec] involved in the interaction. 98 PlatformException({ 99 @required this.code, 100 this.message, 101 this.details, 102 }) : assert(code != null); 103 104 /// An error code. 105 final String code; 106 107 /// A human-readable error message, possibly null. 108 final String message; 109 110 /// Error details, possibly null. 111 final dynamic details; 112 113 @override 114 String toString() => 'PlatformException($code, $message, $details)'; 115} 116 117/// Thrown to indicate that a platform interaction failed to find a handling 118/// plugin. 119/// 120/// See also: 121/// 122/// * [MethodChannel.invokeMethod], which completes the returned future 123/// with a [MissingPluginException], if no plugin handler for the method call 124/// was found. 125/// * [OptionalMethodChannel.invokeMethod], which completes the returned future 126/// with null, if no plugin handler for the method call was found. 127class MissingPluginException implements Exception { 128 /// Creates a [MissingPluginException] with an optional human-readable 129 /// error message. 130 MissingPluginException([this.message]); 131 132 /// A human-readable error message, possibly null. 133 final String message; 134 135 @override 136 String toString() => 'MissingPluginException($message)'; 137} 138