Flattens the specified descriptor and stores the data in the supplied buffer.
- macOS 10.0+
- Core Services
A pointer to the descriptor to be flattened. See
A pointer to memory, allocated by the application, where the flattened data will be stored. See the
bufferparameter for information on how large a buffer you should allocate.
The size of the buffer pointed to by buffer. Prior to calling
AEFlatten, you call the
AESizefunction to determine the required size of the buffer for the flatten operation.
Of Flattened Desc
bufferis too small,
errand doesn’t store any data in the buffer.
AEBuffer Too Small
A pointer to a size variable. On return, the variable contains the actual size of the flattened data. You can specify
NULLfor this parameter if you do not care about the returned size.
A result code. See Result Codes.
Flattening a descriptor serializes the data it contains. That is, it reduces a complex, possibly deeply nested structure to a series of bytes that can conveniently be stored. The descriptor can be reconstituted from the stored bytes with the
Applications can be scriptable and work with Apple events without needing to flatten and unflatten descriptors. Flattening is a special-purpose capability that is useful in circumstances where it may be convenient to store data by saving and restoring a descriptor, rather than having to manually extract the data from it, store the data as a separate step, then manually recreate the descriptor (if necessary). For example, you might use flattening to store a preference setting received through an Apple event.
Flattening and unflattening should work without loss of data on descriptors that represent
AERecord structures. You can also use the process with
Apple descriptors. However, keep in mind that Apple events may contain attributes that are relevant only to a running process, and these attributes may not keep their meaning when the event is reconstituted.
Flattening and unflattening works across OS versions, including between Mac OS 9 and macOS.
Flattening is endian-neutral. That is, you can save flattened data on a machine that is either big-endian or little-endian, then retrieve and unflatten the data on either type of machine, without any special steps by your application.
Thread safe starting in OS X v10.2.