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