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