| 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
12 NS_ASSUME_NONNULL_BEGIN
13
14 /**
15 * A message encoding/decoding mechanism.
16 */
17 FLUTTER_DARWIN_EXPORT
18 @protocol FlutterMessageCodec
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 */
51 FLUTTER_DARWIN_EXPORT
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 */
62 FLUTTER_DARWIN_EXPORT
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 */
80 FLUTTER_DARWIN_EXPORT
81 @interface FlutterJSONMessageCodec : NSObject <FlutterMessageCodec>
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 */
91 FLUTTER_DARWIN_EXPORT
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 */
131 FLUTTER_DARWIN_EXPORT
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 */
171 FLUTTER_DARWIN_EXPORT
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 */
208 FLUTTER_DARWIN_EXPORT
209 @interface FlutterStandardMessageCodec : NSObject <FlutterMessageCodec>
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 */
219 FLUTTER_DARWIN_EXPORT
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 */
245 FLUTTER_DARWIN_EXPORT
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 */
299 FLUTTER_DARWIN_EXPORT
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 */
366 FLUTTER_DARWIN_EXPORT
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 */
390 FLUTTER_DARWIN_EXPORT
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 */
454 FLUTTER_DARWIN_EXPORT
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 */
468 FLUTTER_DARWIN_EXPORT
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
476 NS_ASSUME_NONNULL_END
477
478 #endif // FLUTTER_SHELL_PLATFORM_DARWIN_COMMON_FRAMEWORK_HEADERS_FLUTTERCODECS_H_
NS_ENUM
typedef NS_ENUM(NSInteger, FlutterStandardDataType)
Definition: FlutterCodecs.h:281
FlutterMacros.h
NS_ASSUME_NONNULL_BEGIN
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
NS_ASSUME_NONNULL_END
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
FLUTTER_UNAVAILABLE
#define FLUTTER_UNAVAILABLE(msg)
Definition: FlutterMacros.h:38
FLUTTER_DARWIN_EXPORT
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
FlutterBinaryCodec
Definition: FlutterCodecs.h:52
FlutterError
Definition: FlutterCodecs.h:247
FlutterError::message
NSString * message
Definition: FlutterCodecs.h:265
FlutterError::code
NSString * code
Definition: FlutterCodecs.h:260
FlutterError::details
id details
Definition: FlutterCodecs.h:270
FlutterJSONMessageCodec
Definition: FlutterCodecs.h:81
FlutterJSONMethodCodec
Definition: FlutterCodecs.h:455
FlutterMethodCall
Definition: FlutterCodecs.h:221
FlutterMethodCall::method
NSString * method
Definition: FlutterCodecs.h:233
FlutterMethodCall::arguments
id arguments
Definition: FlutterCodecs.h:238
FlutterStandardMessageCodec
Definition: FlutterCodecs.h:209
FlutterStandardMethodCodec
Definition: FlutterCodecs.h:469
FlutterStandardReader
Definition: FlutterCodecs.h:133
-[FlutterStandardReader readByte]
UInt8 readByte()
Definition: FlutterStandardCodec.mm:376
-[FlutterStandardReader readSize]
UInt32 readSize()
Definition: FlutterStandardCodec.mm:380
-[FlutterStandardReader readValue]
nullable id readValue()
Definition: FlutterStandardCodec.mm:400
-[FlutterStandardReader readUTF8]
NSString * readUTF8()
Definition: FlutterStandardCodec.mm:391
-[FlutterStandardReader hasMore]
BOOL hasMore()
Definition: FlutterStandardCodec.mm:367
FlutterStandardReaderWriter
Definition: FlutterCodecs.h:173
FlutterStandardTypedData
Definition: FlutterCodecs.h:301
FlutterStandardTypedData::elementSize
UInt8 elementSize
Definition: FlutterCodecs.h:359
FlutterStandardTypedData::elementCount
UInt32 elementCount
Definition: FlutterCodecs.h:354
FlutterStandardTypedData::type
FlutterStandardDataType type
Definition: FlutterCodecs.h:349
FlutterStandardTypedData::data
NSData * data
Definition: FlutterCodecs.h:344
FlutterStandardWriter
Definition: FlutterCodecs.h:93
FlutterStringCodec
Definition: FlutterCodecs.h:63
FlutterMessageCodec-p
Definition: FlutterCodecs.h:18
+[FlutterMessageCodec-p sharedInstance]
instancetype sharedInstance()