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_FLUTTERCODECS_H_ 6 #define FLUTTER_FLUTTERCODECS_H_ 7 8 #import <Foundation/Foundation.h> 9 #include "FlutterMacros.h" 10 11 NS_ASSUME_NONNULL_BEGIN 12 13 /** 14 A message encoding/decoding mechanism. 15 */ 16 FLUTTER_EXPORT 17 @protocol FlutterMessageCodec 18 /** 19 * Returns a shared instance of this `FlutterMessageCodec`. 20 */ 21 + (instancetype)sharedInstance; 22 23 /** 24 * Encodes the specified message into binary. 25 * 26 * @param message The message. 27 * @return The binary encoding, or `nil`, if `message` was `nil`. 28 */ 29 - (NSData* _Nullable)encode:(id _Nullable)message; 30 31 /** 32 * Decodes the specified message from binary. 33 * 34 * @param message The message. 35 * @return The decoded message, or `nil`, if `message` was `nil`. 36 */ 37 - (id _Nullable)decode:(NSData* _Nullable)message; 38 @end 39 40 /** 41 * A `FlutterMessageCodec` using unencoded binary messages, represented as 42 * `NSData` instances. 43 * 44 * This codec is guaranteed to be compatible with the corresponding 45 * [BinaryCodec](https://docs.flutter.io/flutter/services/BinaryCodec-class.html) 46 * on the Dart side. These parts of the Flutter SDK are evolved synchronously. 47 * 48 * On the Dart side, messages are represented using `ByteData`. 49 */ 50 FLUTTER_EXPORT 51 @interface FlutterBinaryCodec : NSObject <FlutterMessageCodec> 52 @end 53 54 /** 55 * A `FlutterMessageCodec` using UTF-8 encoded `NSString` messages. 56 * 57 * This codec is guaranteed to be compatible with the corresponding 58 * [StringCodec](https://docs.flutter.io/flutter/services/StringCodec-class.html) 59 * on the Dart side. These parts of the Flutter SDK are evolved synchronously. 60 */ 61 FLUTTER_EXPORT 62 @interface FlutterStringCodec : NSObject <FlutterMessageCodec> 63 @end 64 65 /** 66 * A `FlutterMessageCodec` using UTF-8 encoded JSON messages. 67 * 68 * This codec is guaranteed to be compatible with the corresponding 69 * [JSONMessageCodec](https://docs.flutter.io/flutter/services/JSONMessageCodec-class.html) 70 * on the Dart side. These parts of the Flutter SDK are evolved synchronously. 71 * 72 * Supports values accepted by `NSJSONSerialization` plus top-level 73 * `nil`, `NSNumber`, and `NSString`. 74 * 75 * On the Dart side, JSON messages are handled by the JSON facilities of the 76 * [`dart:convert`](https://api.dartlang.org/stable/dart-convert/JSON-constant.html) 77 * package. 78 */ 79 FLUTTER_EXPORT 80 @interface FlutterJSONMessageCodec : NSObject <FlutterMessageCodec> 81 @end 82 83 /** 84 * A writer of the Flutter standard binary encoding. 85 * 86 * See `FlutterStandardMessageCodec` for details on the encoding. 87 * 88 * The encoding is extensible via subclasses overriding `writeValue`. 89 */ 90 FLUTTER_EXPORT 91 @interface FlutterStandardWriter : NSObject 92 - (instancetype)initWithData:(NSMutableData*)data; 93 - (void)writeByte:(UInt8)value; 94 - (void)writeBytes:(const void*)bytes length:(NSUInteger)length; 95 - (void)writeData:(NSData*)data; 96 - (void)writeSize:(UInt32)size; 97 - (void)writeAlignment:(UInt8)alignment; 98 - (void)writeUTF8:(NSString*)value; 99 - (void)writeValue:(id)value; 100 @end 101 102 /** 103 * A reader of the Flutter standard binary encoding. 104 * 105 * See `FlutterStandardMessageCodec` for details on the encoding. 106 * 107 * The encoding is extensible via subclasses overriding `readValueOfType`. 108 */ 109 FLUTTER_EXPORT 110 @interface FlutterStandardReader : NSObject 111 - (instancetype)initWithData:(NSData*)data; 112 - (BOOL)hasMore; 113 - (UInt8)readByte; 114 - (void)readBytes:(void*)destination length:(NSUInteger)length; 115 - (NSData*)readData:(NSUInteger)length; 116 - (UInt32)readSize; 117 - (void)readAlignment:(UInt8)alignment; 118 - (NSString*)readUTF8; 119 - (nullable id)readValue; 120 - (nullable id)readValueOfType:(UInt8)type; 121 @end 122 123 /** 124 * A factory of compatible reader/writer instances using the Flutter standard 125 * binary encoding or extensions thereof. 126 */ 127 FLUTTER_EXPORT 128 @interface FlutterStandardReaderWriter : NSObject 129 - (FlutterStandardWriter*)writerWithData:(NSMutableData*)data; 130 - (FlutterStandardReader*)readerWithData:(NSData*)data; 131 @end 132 133 /** 134 * A `FlutterMessageCodec` using the Flutter standard binary encoding. 135 * 136 * This codec is guaranteed to be compatible with the corresponding 137 * [StandardMessageCodec](https://docs.flutter.io/flutter/services/StandardMessageCodec-class.html) 138 * on the Dart side. These parts of the Flutter SDK are evolved synchronously. 139 * 140 * Supported messages are acyclic values of these forms: 141 * 142 * - `nil` or `NSNull` 143 * - `NSNumber` (including their representation of Boolean values) 144 * - `NSString` 145 * - `FlutterStandardTypedData` 146 * - `NSArray` of supported values 147 * - `NSDictionary` with supported keys and values 148 * 149 * On the Dart side, these values are represented as follows: 150 * 151 * - `nil` or `NSNull`: null 152 * - `NSNumber`: `bool`, `int`, or `double`, depending on the contained value. 153 * - `NSString`: `String` 154 * - `FlutterStandardTypedData`: `Uint8List`, `Int32List`, `Int64List`, or `Float64List` 155 * - `NSArray`: `List` 156 * - `NSDictionary`: `Map` 157 */ 158 FLUTTER_EXPORT 159 @interface FlutterStandardMessageCodec : NSObject <FlutterMessageCodec> 160 + (instancetype)codecWithReaderWriter:(FlutterStandardReaderWriter*)readerWriter; 161 @end 162 163 /** 164 Command object representing a method call on a `FlutterMethodChannel`. 165 */ 166 FLUTTER_EXPORT 167 @interface FlutterMethodCall : NSObject 168 /** 169 * Creates a method call for invoking the specified named method with the 170 * specified arguments. 171 * 172 * @param method the name of the method to call. 173 * @param arguments the arguments value. 174 */ 175 + (instancetype)methodCallWithMethodName:(NSString*)method arguments:(id _Nullable)arguments; 176 177 /** 178 * The method name. 179 */ 180 @property(readonly, nonatomic) NSString* method; 181 182 /** 183 * The arguments. 184 */ 185 @property(readonly, nonatomic, nullable) id arguments; 186 @end 187 188 /** 189 * Error object representing an unsuccessful outcome of invoking a method 190 * on a `FlutterMethodChannel`, or an error event on a `FlutterEventChannel`. 191 */ 192 FLUTTER_EXPORT 193 @interface FlutterError : NSObject 194 /** 195 * Creates a `FlutterError` with the specified error code, message, and details. 196 * 197 * @param code An error code string for programmatic use. 198 * @param message A human-readable error message. 199 * @param details Custom error details. 200 */ 201 + (instancetype)errorWithCode:(NSString*)code 202 message:(NSString* _Nullable)message 203 details:(id _Nullable)details; 204 /** 205 The error code. 206 */ 207 @property(readonly, nonatomic) NSString* code; 208 209 /** 210 The error message. 211 */ 212 @property(readonly, nonatomic, nullable) NSString* message; 213 214 /** 215 The error details. 216 */ 217 @property(readonly, nonatomic, nullable) id details; 218 @end 219 220 /** 221 * Type of numeric data items encoded in a `FlutterStandardDataType`. 222 * 223 * - FlutterStandardDataTypeUInt8: plain bytes 224 * - FlutterStandardDataTypeInt32: 32-bit signed integers 225 * - FlutterStandardDataTypeInt64: 64-bit signed integers 226 * - FlutterStandardDataTypeFloat64: 64-bit floats 227 */ 228 typedef NS_ENUM(NSInteger, FlutterStandardDataType) { 229 FlutterStandardDataTypeUInt8, 230 FlutterStandardDataTypeInt32, 231 FlutterStandardDataTypeInt64, 232 FlutterStandardDataTypeFloat64, 233 }; 234 235 /** 236 * A byte buffer holding `UInt8`, `SInt32`, `SInt64`, or `Float64` values, used 237 * with `FlutterStandardMessageCodec` and `FlutterStandardMethodCodec`. 238 * 239 * Two's complement encoding is used for signed integers. IEEE754 240 * double-precision representation is used for floats. The platform's native 241 * endianness is assumed. 242 */ 243 FLUTTER_EXPORT 244 @interface FlutterStandardTypedData : NSObject 245 /** 246 * Creates a `FlutterStandardTypedData` which interprets the specified data 247 * as plain bytes. 248 * 249 * @param data the byte data. 250 */ 251 + (instancetype)typedDataWithBytes:(NSData*)data; 252 253 /** 254 * Creates a `FlutterStandardTypedData` which interprets the specified data 255 * as 32-bit signed integers. 256 * 257 * @param data the byte data. The length must be divisible by 4. 258 */ 259 + (instancetype)typedDataWithInt32:(NSData*)data; 260 261 /** 262 * Creates a `FlutterStandardTypedData` which interprets the specified data 263 * as 64-bit signed integers. 264 * 265 * @param data the byte data. The length must be divisible by 8. 266 */ 267 + (instancetype)typedDataWithInt64:(NSData*)data; 268 269 /** 270 * Creates a `FlutterStandardTypedData` which interprets the specified data 271 * as 64-bit floats. 272 * 273 * @param data the byte data. The length must be divisible by 8. 274 */ 275 + (instancetype)typedDataWithFloat64:(NSData*)data; 276 277 /** 278 * The raw underlying data buffer. 279 */ 280 @property(readonly, nonatomic) NSData* data; 281 282 /** 283 * The type of the encoded values. 284 */ 285 @property(readonly, nonatomic) FlutterStandardDataType type; 286 287 /** 288 * The number of value items encoded. 289 */ 290 @property(readonly, nonatomic) UInt32 elementCount; 291 292 /** 293 * The number of bytes used by the encoding of a single value item. 294 */ 295 @property(readonly, nonatomic) UInt8 elementSize; 296 @end 297 298 /** 299 * An arbitrarily large integer value, used with `FlutterStandardMessageCodec` 300 * and `FlutterStandardMethodCodec`. 301 */ 302 FLUTTER_EXPORT 303 FLUTTER_UNAVAILABLE("Unavailable on 2018-08-31. Deprecated on 2018-01-09. " 304 "FlutterStandardBigInteger was needed because the Dart 1.0 int type had no " 305 "size limit. With Dart 2.0, the int type is a fixed-size, 64-bit signed " 306 "integer. If you need to communicate larger integers, use NSString encoding " 307 "instead.") 308 @interface FlutterStandardBigInteger : NSObject 309 @end 310 311 /** 312 * A codec for method calls and enveloped results. 313 * 314 * Method calls are encoded as binary messages with enough structure that the 315 * codec can extract a method name `NSString` and an arguments `NSObject`, 316 * possibly `nil`. These data items are used to populate a `FlutterMethodCall`. 317 * 318 * Result envelopes are encoded as binary messages with enough structure that 319 * the codec can determine whether the result was successful or an error. In 320 * the former case, the codec can extract the result `NSObject`, possibly `nil`. 321 * In the latter case, the codec can extract an error code `NSString`, a 322 * human-readable `NSString` error message (possibly `nil`), and a custom 323 * error details `NSObject`, possibly `nil`. These data items are used to 324 * populate a `FlutterError`. 325 */ 326 FLUTTER_EXPORT 327 @protocol FlutterMethodCodec 328 /** 329 * Provides access to a shared instance this codec. 330 * 331 * @return The shared instance. 332 */ 333 + (instancetype)sharedInstance; 334 335 /** 336 * Encodes the specified method call into binary. 337 * 338 * @param methodCall The method call. The arguments value 339 * must be supported by this codec. 340 * @return The binary encoding. 341 */ 342 - (NSData*)encodeMethodCall:(FlutterMethodCall*)methodCall; 343 344 /** 345 * Decodes the specified method call from binary. 346 * 347 * @param methodCall The method call to decode. 348 * @return The decoded method call. 349 */ 350 - (FlutterMethodCall*)decodeMethodCall:(NSData*)methodCall; 351 352 /** 353 * Encodes the specified successful result into binary. 354 * 355 * @param result The result. Must be a value supported by this codec. 356 * @return The binary encoding. 357 */ 358 - (NSData*)encodeSuccessEnvelope:(id _Nullable)result; 359 360 /** 361 * Encodes the specified error result into binary. 362 * 363 * @param error The error object. The error details value must be supported 364 * by this codec. 365 * @return The binary encoding. 366 */ 367 - (NSData*)encodeErrorEnvelope:(FlutterError*)error; 368 369 /** 370 * Deccodes the specified result envelope from binary. 371 * 372 * @param envelope The error object. 373 * @return The result value, if the envelope represented a successful result, 374 * or a `FlutterError` instance, if not. 375 */ 376 - (id _Nullable)decodeEnvelope:(NSData*)envelope; 377 @end 378 379 /** 380 * A `FlutterMethodCodec` using UTF-8 encoded JSON method calls and result 381 * envelopes. 382 * 383 * This codec is guaranteed to be compatible with the corresponding 384 * [JSONMethodCodec](https://docs.flutter.io/flutter/services/JSONMethodCodec-class.html) 385 * on the Dart side. These parts of the Flutter SDK are evolved synchronously. 386 * 387 * Values supported as methods arguments and result payloads are 388 * those supported as top-level or leaf values by `FlutterJSONMessageCodec`. 389 */ 390 FLUTTER_EXPORT 391 @interface FlutterJSONMethodCodec : NSObject <FlutterMethodCodec> 392 @end 393 394 /** 395 * A `FlutterMethodCodec` using the Flutter standard binary encoding. 396 * 397 * This codec is guaranteed to be compatible with the corresponding 398 * [StandardMethodCodec](https://docs.flutter.io/flutter/services/StandardMethodCodec-class.html) 399 * on the Dart side. These parts of the Flutter SDK are evolved synchronously. 400 * 401 * Values supported as method arguments and result payloads are those supported by 402 * `FlutterStandardMessageCodec`. 403 */ 404 FLUTTER_EXPORT 405 @interface FlutterStandardMethodCodec : NSObject <FlutterMethodCodec> 406 + (instancetype)codecWithReaderWriter:(FlutterStandardReaderWriter*)readerWriter; 407 @end 408 409 NS_ASSUME_NONNULL_END 410 411 #endif // FLUTTER_FLUTTERCODECS_H_ 412