| 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_FLUTTERCODECS_H_
6 #define FLUTTER_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 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 */
297 FLUTTER_DARWIN_EXPORT
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, assign) FlutterStandardDataType type;
348
349 /**
350 * The number of value items encoded.
351 */
352 @property(readonly, nonatomic, assign) UInt32 elementCount;
353
354 /**
355 * The number of bytes used by the encoding of a single value item.
356 */
357 @property(readonly, nonatomic, assign) UInt8 elementSize;
358 @end
359
360 /**
361 * An arbitrarily large integer value, used with `FlutterStandardMessageCodec`
362 * and `FlutterStandardMethodCodec`.
363 */
364 FLUTTER_DARWIN_EXPORT
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 */
388 FLUTTER_DARWIN_EXPORT
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 */
452 FLUTTER_DARWIN_EXPORT
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 */
466 FLUTTER_DARWIN_EXPORT
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
474 NS_ASSUME_NONNULL_END
475
476 #endif // FLUTTER_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:347
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:352
FlutterStandardTypedData::elementSize
UInt8 elementSize
Definition: FlutterCodecs.h:357
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:298
-[FlutterStandardReader readValue]
nullable id readValue()
Definition: FlutterStandardCodec.mm:400
FlutterMessageCodec-p
Definition: FlutterCodecs.h:18
FlutterStandardTypedData::data
NSData * data
Definition: FlutterCodecs.h:342
FlutterJSONMethodCodec
Definition: FlutterCodecs.h:453
FLUTTER_DARWIN_EXPORT
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
-[FlutterStandardReader readUTF8]
NSString * readUTF8()
Definition: FlutterStandardCodec.mm:391
FlutterStandardMethodCodec
Definition: FlutterCodecs.h:467
FlutterBinaryCodec
Definition: FlutterCodecs.h:52
FlutterMethodCall::arguments
id arguments
Definition: FlutterCodecs.h:238
+[FlutterMessageCodec-p sharedInstance]
instancetype sharedInstance()
FlutterJSONMessageCodec
Definition: FlutterCodecs.h:81