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://api.flutter.dev/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://api.flutter.dev/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://api.flutter.dev/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://api.flutter.dev/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  FlutterStandardDataTypeFloat32,
286  FlutterStandardDataTypeFloat64,
287 };
288 
289 /**
290  * A byte buffer holding `UInt8`, `SInt32`, `SInt64`, or `Float64` values, used
291  * with `FlutterStandardMessageCodec` and `FlutterStandardMethodCodec`.
292  *
293  * Two's complement encoding is used for signed integers. IEEE754
294  * double-precision representation is used for floats. The platform's native
295  * endianness is assumed.
296  */
298 @interface FlutterStandardTypedData : NSObject
299 /**
300  * Creates a `FlutterStandardTypedData` which interprets the specified data
301  * as plain bytes.
302  *
303  * @param data the byte data.
304  */
305 + (instancetype)typedDataWithBytes:(NSData*)data;
306 
307 /**
308  * Creates a `FlutterStandardTypedData` which interprets the specified data
309  * as 32-bit signed integers.
310  *
311  * @param data the byte data. The length must be divisible by 4.
312  */
313 + (instancetype)typedDataWithInt32:(NSData*)data;
314 
315 /**
316  * Creates a `FlutterStandardTypedData` which interprets the specified data
317  * as 64-bit signed integers.
318  *
319  * @param data the byte data. The length must be divisible by 8.
320  */
321 + (instancetype)typedDataWithInt64:(NSData*)data;
322 
323 /**
324  * Creates a `FlutterStandardTypedData` which interprets the specified data
325  * as 32-bit floats.
326  *
327  * @param data the byte data. The length must be divisible by 8.
328  */
329 + (instancetype)typedDataWithFloat32:(NSData*)data;
330 
331 /**
332  * Creates a `FlutterStandardTypedData` which interprets the specified data
333  * as 64-bit floats.
334  *
335  * @param data the byte data. The length must be divisible by 8.
336  */
337 + (instancetype)typedDataWithFloat64:(NSData*)data;
338 
339 /**
340  * The raw underlying data buffer.
341  */
342 @property(readonly, nonatomic) NSData* data;
343 
344 /**
345  * The type of the encoded values.
346  */
347 @property(readonly, nonatomic) FlutterStandardDataType type;
348 
349 /**
350  * The number of value items encoded.
351  */
352 @property(readonly, nonatomic) UInt32 elementCount;
353 
354 /**
355  * The number of bytes used by the encoding of a single value item.
356  */
357 @property(readonly, nonatomic) UInt8 elementSize;
358 @end
359 
360 /**
361  * An arbitrarily large integer value, used with `FlutterStandardMessageCodec`
362  * and `FlutterStandardMethodCodec`.
363  */
365 FLUTTER_UNAVAILABLE("Unavailable on 2018-08-31. Deprecated on 2018-01-09. "
366  "FlutterStandardBigInteger was needed because the Dart 1.0 int type had no "
367  "size limit. With Dart 2.0, the int type is a fixed-size, 64-bit signed "
368  "integer. If you need to communicate larger integers, use NSString encoding "
369  "instead.")
370 @interface FlutterStandardBigInteger : NSObject
371 @end
372 
373 /**
374  * A codec for method calls and enveloped results.
375  *
376  * Method calls are encoded as binary messages with enough structure that the
377  * codec can extract a method name `NSString` and an arguments `NSObject`,
378  * possibly `nil`. These data items are used to populate a `FlutterMethodCall`.
379  *
380  * Result envelopes are encoded as binary messages with enough structure that
381  * the codec can determine whether the result was successful or an error. In
382  * the former case, the codec can extract the result `NSObject`, possibly `nil`.
383  * In the latter case, the codec can extract an error code `NSString`, a
384  * human-readable `NSString` error message (possibly `nil`), and a custom
385  * error details `NSObject`, possibly `nil`. These data items are used to
386  * populate a `FlutterError`.
387  */
389 @protocol FlutterMethodCodec
390 /**
391  * Provides access to a shared instance this codec.
392  *
393  * @return The shared instance.
394  */
395 + (instancetype)sharedInstance;
396 
397 /**
398  * Encodes the specified method call into binary.
399  *
400  * @param methodCall The method call. The arguments value
401  * must be supported by this codec.
402  * @return The binary encoding.
403  */
404 - (NSData*)encodeMethodCall:(FlutterMethodCall*)methodCall;
405 
406 /**
407  * Decodes the specified method call from binary.
408  *
409  * @param methodCall The method call to decode.
410  * @return The decoded method call.
411  */
412 - (FlutterMethodCall*)decodeMethodCall:(NSData*)methodCall;
413 
414 /**
415  * Encodes the specified successful result into binary.
416  *
417  * @param result The result. Must be a value supported by this codec.
418  * @return The binary encoding.
419  */
420 - (NSData*)encodeSuccessEnvelope:(id _Nullable)result;
421 
422 /**
423  * Encodes the specified error result into binary.
424  *
425  * @param error The error object. The error details value must be supported
426  * by this codec.
427  * @return The binary encoding.
428  */
429 - (NSData*)encodeErrorEnvelope:(FlutterError*)error;
430 
431 /**
432  * Deccodes the specified result envelope from binary.
433  *
434  * @param envelope The error object.
435  * @return The result value, if the envelope represented a successful result,
436  * or a `FlutterError` instance, if not.
437  */
438 - (id _Nullable)decodeEnvelope:(NSData*)envelope;
439 @end
440 
441 /**
442  * A `FlutterMethodCodec` using UTF-8 encoded JSON method calls and result
443  * envelopes.
444  *
445  * This codec is guaranteed to be compatible with the corresponding
446  * [JSONMethodCodec](https://api.flutter.dev/flutter/services/JSONMethodCodec-class.html)
447  * on the Dart side. These parts of the Flutter SDK are evolved synchronously.
448  *
449  * Values supported as methods arguments and result payloads are
450  * those supported as top-level or leaf values by `FlutterJSONMessageCodec`.
451  */
453 @interface FlutterJSONMethodCodec : NSObject <FlutterMethodCodec>
454 @end
455 
456 /**
457  * A `FlutterMethodCodec` using the Flutter standard binary encoding.
458  *
459  * This codec is guaranteed to be compatible with the corresponding
460  * [StandardMethodCodec](https://api.flutter.dev/flutter/services/StandardMethodCodec-class.html)
461  * on the Dart side. These parts of the Flutter SDK are evolved synchronously.
462  *
463  * Values supported as method arguments and result payloads are those supported by
464  * `FlutterStandardMessageCodec`.
465  */
467 @interface FlutterStandardMethodCodec : NSObject <FlutterMethodCodec>
468 /**
469  * Create a `FlutterStandardMethodCodec` who will read and write to \p readerWriter.
470  */
471 + (instancetype)codecWithReaderWriter:(FlutterStandardReaderWriter*)readerWriter;
472 @end
473 
475 
476 #endif // FLUTTER_FLUTTERCODECS_H_
const uint8_t uint32_t uint32_t GError ** error
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
GAsyncResult * result
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
instancetype sharedInstance()
#define FLUTTER_UNAVAILABLE(msg)
Definition: FlutterMacros.h:38
int BOOL
Definition: windows_types.h:37
int32_t id
typedef NS_ENUM(NSInteger, FlutterStandardDataType)