[apple/libdispatch.git] / private / data_private.h

/*
 * Copyright (c) 2011-2013 Apple Inc. All rights reserved.
 *
 * @APPLE_APACHE_LICENSE_HEADER_START@
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * @APPLE_APACHE_LICENSE_HEADER_END@
 */

/*
 * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
 * which are subject to change in future releases of Mac OS X. Any applications
 * relying on these interfaces WILL break.
 */

#ifndef __DISPATCH_DATA_PRIVATE__
#define __DISPATCH_DATA_PRIVATE__

#ifndef __DISPATCH_INDIRECT__
#error "Please #include <dispatch/dispatch.h> instead of this file directly."
#include <dispatch/base.h> // for HeaderDoc
#endif

DISPATCH_ASSUME_NONNULL_BEGIN

__BEGIN_DECLS

/*!
 * @const DISPATCH_DATA_DESTRUCTOR_NONE
 * @discussion The destructor for dispatch data objects that require no buffer
 * memory management. This can be used to allow a data object to efficiently
 * encapsulate buffers that should not be copied or freed by the system.
 */
#define DISPATCH_DATA_DESTRUCTOR_NONE (_dispatch_data_destructor_none)
API_AVAILABLE(macos(10.8), ios(6.0))
DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(none);

/*!
 * @const DISPATCH_DATA_DESTRUCTOR_VM_DEALLOCATE
 * @discussion The destructor for dispatch data objects that have been created
 * from buffers that require deallocation using vm_deallocate.
 */
#define DISPATCH_DATA_DESTRUCTOR_VM_DEALLOCATE \
		(_dispatch_data_destructor_vm_deallocate)
API_AVAILABLE(macos(10.8), ios(6.0)) DISPATCH_LINUX_UNAVAILABLE()
DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(vm_deallocate);

/*!
 * @function dispatch_data_create_f
 * Creates a dispatch data object from the given contiguous buffer of memory. If
 * a non-default destructor is provided, ownership of the buffer remains with
 * the caller (i.e. the bytes will not be copied). The last release of the data
 * object will result in the invocation of the specified destructor function on
 * specified queue to free the buffer (passed as the context parameter).
 *
 * If the DISPATCH_DATA_DESTRUCTOR_FREE destructor is provided the buffer will
 * be freed via free(3) and the queue argument ignored.
 *
 * If the DISPATCH_DATA_DESTRUCTOR_DEFAULT destructor is provided, data object
 * creation will copy the buffer into internal memory managed by the system.
 *
 * @param buffer	A contiguous buffer of data.
 * @param size		The size of the contiguous buffer of data.
 * @param queue		The queue to which the destructor should be submitted.
 * @param destructor	The destructor function responsible for freeing the
 *			data buffer when it is no longer needed.
 * @result		A newly created dispatch data object.
 */
API_AVAILABLE(macos(10.9), ios(7.0))
DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW
dispatch_data_t
dispatch_data_create_f(const void *buffer,
	size_t size,
	dispatch_queue_t _Nullable queue,
	dispatch_function_t _Nullable destructor);

/*!
 * @function dispatch_data_create_alloc
 * Creates a dispatch data object representing a newly allocated memory region
 * of the given size. If a non-NULL reference to a pointer is provided, it is
 * filled with the location of the memory region.
 *
 * It is the responsibility of the application to ensure that the data object
 * becomes immutable (i.e. the returned memory region is not further modified)
 * once the dispatch data object is passed to other API.
 *
 * @param size		The size of the required allocation.
 * @param buffer_ptr	A pointer to a pointer variable to be filled with the
 *			location of the newly allocated memory region, or NULL.
 * @result		A newly created dispatch data object.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED
DISPATCH_WARN_RESULT DISPATCH_NOTHROW
dispatch_data_t
dispatch_data_create_alloc(size_t size, void *_Nullable *_Nullable buffer_ptr);

/*!
 * @typedef dispatch_data_applier_function_t
 * A function to be invoked for every contiguous memory region in a data object.
 *
 * @param context	Application-defined context parameter.
 * @param region	A data object representing the current region.
 * @param offset	The logical offset of the current region to the start
 *					of the data object.
 * @param buffer	The location of the memory for the current region.
 * @param size		The size of the memory for the current region.
 * @result		A Boolean indicating whether traversal should continue.
 */
typedef bool (*dispatch_data_applier_function_t)(void *_Nullable context,
	dispatch_data_t region, size_t offset, const void *buffer, size_t size);

/*!
 * @function dispatch_data_apply_f
 * Traverse the memory regions represented by the specified dispatch data object
 * in logical order and invoke the specified function once for every contiguous
 * memory region encountered.
 *
 * Each invocation of the function is passed a data object representing the
 * current region and its logical offset, along with the memory location and
 * extent of the region. These allow direct read access to the memory region,
 * but are only valid until the passed-in region object is released. Note that
 * the region object is released by the system when the function returns, it is
 * the responsibility of the application to retain it if the region object or
 * the associated memory location are needed after the function returns.
 *
 * @param data		The data object to traverse.
 * @param context	The application-defined context to pass to the function.
 * @param applier	The function to be invoked for every contiguous memory
 *			region in the data object.
 * @result		A Boolean indicating whether traversal completed
 *			successfully.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
bool
dispatch_data_apply_f(dispatch_data_t data, void *_Nullable context,
	dispatch_data_applier_function_t applier);

#if TARGET_OS_MAC
/*!
 * @function dispatch_data_make_memory_entry
 * Return a mach memory entry for the memory regions represented by the
 * specified dispatch data object.
 *
 * For data objects created with the DISPATCH_DATA_DESTRUCTOR_VM_DEALLOCATE
 * destructor, directly makes a memory entry from the represented region;
 * otherwise, makes a memory entry from newly allocated pages containing a copy
 * of the represented memory regions.
 *
 * @param data		The data object to make a memory entry for.
 * @result		A mach port for the newly made memory entry, or
 *			MACH_PORT_NULL if an error occurred.
 */
API_AVAILABLE(macos(10.9), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
mach_port_t
dispatch_data_make_memory_entry(dispatch_data_t data);
#endif

/*!
 * @functiongroup Dispatch data transform SPI
 */

/*!
 * @typedef dispatch_data_format_type_t
 *
 * @abstract
 * Data formats are used to specify the input and output types of data supplied
 * to dispatch_data_create_transform.
 */
typedef const struct dispatch_data_format_type_s *dispatch_data_format_type_t;

#if !TARGET_OS_WIN32
#define DISPATCH_DATA_FORMAT_TYPE_DECL(name) \
	DISPATCH_EXPORT const struct dispatch_data_format_type_s \
	_dispatch_data_format_type_##name
#else
#define DISPATCH_DATA_FORMAT_TYPE_DECL(name) \
	DISPATCH_EXPORT struct dispatch_data_format_type_s \
	_dispatch_data_format_type_##name
#endif

/*!
 * @const DISPATCH_DATA_FORMAT_TYPE_NONE
 * @discussion A data format denoting that the given input or output format is,
 * or should be, comprised of raw data bytes with no given encoding.
 */
#define DISPATCH_DATA_FORMAT_TYPE_NONE (&_dispatch_data_format_type_none)
API_AVAILABLE(macos(10.8), ios(6.0))
DISPATCH_DATA_FORMAT_TYPE_DECL(none);

/*!
 * @const DISPATCH_DATA_FORMAT_TYPE_BASE32
 * @discussion A data format denoting that the given input or output format is,
 * or should be, encoded in Base32 (RFC 4648) format. On input, this format will
 * skip whitespace characters. Cannot be used in conjunction with UTF format
 * types.
 */
#define DISPATCH_DATA_FORMAT_TYPE_BASE32 (&_dispatch_data_format_type_base32)
API_AVAILABLE(macos(10.8), ios(6.0))
DISPATCH_DATA_FORMAT_TYPE_DECL(base32);

/*!
 * @const DISPATCH_DATA_FORMAT_TYPE_BASE32HEX
 * @discussion A data format denoting that the given input or output format is,
 * or should be, encoded in Base32Hex (RFC 4648) format. On input, this format
 * will skip whitespace characters. Cannot be used in conjunction with UTF
 * format types.
 */
#define DISPATCH_DATA_FORMAT_TYPE_BASE32HEX \
		(&_dispatch_data_format_type_base32hex)
API_AVAILABLE(macos(10.9), ios(7.0))
DISPATCH_DATA_FORMAT_TYPE_DECL(base32hex);

/*!
 * @const DISPATCH_DATA_FORMAT_TYPE_BASE64
 * @discussion A data format denoting that the given input or output format is,
 * or should be, encoded in Base64 (RFC 4648) format. On input, this format will
 * skip whitespace characters. Cannot be used in conjunction with UTF format
 * types.
 */
#define DISPATCH_DATA_FORMAT_TYPE_BASE64 (&_dispatch_data_format_type_base64)
API_AVAILABLE(macos(10.8), ios(6.0))
DISPATCH_DATA_FORMAT_TYPE_DECL(base64);

/*!
 * @const DISPATCH_DATA_FORMAT_TYPE_UTF8
 * @discussion A data format denoting that the given input or output format is,
 * or should be, encoded in UTF-8 format. Is only valid when used in conjunction
 * with other UTF format types.
 */
#define DISPATCH_DATA_FORMAT_TYPE_UTF8 (&_dispatch_data_format_type_utf8)
API_AVAILABLE(macos(10.8), ios(6.0))
DISPATCH_DATA_FORMAT_TYPE_DECL(utf8);

/*!
 * @const DISPATCH_DATA_FORMAT_TYPE_UTF16LE
 * @discussion A data format denoting that the given input or output format is,
 * or should be, encoded in UTF-16LE format. Is only valid when used in
 * conjunction with other UTF format types.
 */
#define DISPATCH_DATA_FORMAT_TYPE_UTF16LE (&_dispatch_data_format_type_utf16le)
API_AVAILABLE(macos(10.8), ios(6.0))
DISPATCH_DATA_FORMAT_TYPE_DECL(utf16le);

/*!
 * @const DISPATCH_DATA_FORMAT_TYPE_UTF16BE
 * @discussion A data format denoting that the given input or output format is,
 * or should be, encoded in UTF-16BE format. Is only valid when used in
 * conjunction with other UTF format types.
 */
#define DISPATCH_DATA_FORMAT_TYPE_UTF16BE (&_dispatch_data_format_type_utf16be)
API_AVAILABLE(macos(10.8), ios(6.0))
DISPATCH_DATA_FORMAT_TYPE_DECL(utf16be);

/*!
 * @const DISPATCH_DATA_FORMAT_TYPE_UTFANY
 * @discussion A data format denoting that dispatch_data_create_transform should
 * attempt to automatically detect the input type based on the presence of a
 * byte order mark character at the beginning of the data. In the absence of a
 * BOM, the data will be assumed to be in UTF-8 format. Only valid as an input
 * format.
 */
#define DISPATCH_DATA_FORMAT_TYPE_UTF_ANY (&_dispatch_data_format_type_utf_any)
API_AVAILABLE(macos(10.8), ios(6.0))
DISPATCH_DATA_FORMAT_TYPE_DECL(utf_any);

/*!
 * @function dispatch_data_create_transform
 * Returns a new dispatch data object after transforming the given data object
 * from the supplied format, into the given output format.
 *
 * @param data
 * The data object representing the region(s) of memory to transform.
 * @param input_type
 * Flags specifying the input format of the source dispatch_data_t
 *
 * @param output_type
 * Flags specifying the expected output format of the resulting transformation.
 *
 * @result
 * A newly created dispatch data object, dispatch_data_empty if no has been
 * produced, or NULL if an error occurred.
 */

API_AVAILABLE(macos(10.8), ios(6.0))
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_RETURNS_RETAINED
DISPATCH_WARN_RESULT DISPATCH_NOTHROW
dispatch_data_t
dispatch_data_create_with_transform(dispatch_data_t data,
	dispatch_data_format_type_t input_type,
	dispatch_data_format_type_t output_type);

__END_DECLS

DISPATCH_ASSUME_NONNULL_END

#endif // __DISPATCH_DATA_PRIVATE__
Commit	Line	Data
c093abd6	1	/*
517da941	2	* Copyright (c) 2011-2013 Apple Inc. All rights reserved.
c093abd6 A	3	*
	4	* @APPLE_APACHE_LICENSE_HEADER_START@
	5	*
	6	* Licensed under the Apache License, Version 2.0 (the "License");
	7	* you may not use this file except in compliance with the License.
	8	* You may obtain a copy of the License at
	9	*
	10	* http://www.apache.org/licenses/LICENSE-2.0
	11	*
	12	* Unless required by applicable law or agreed to in writing, software
	13	* distributed under the License is distributed on an "AS IS" BASIS,
	14	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	15	* See the License for the specific language governing permissions and
	16	* limitations under the License.
	17	*
	18	* @APPLE_APACHE_LICENSE_HEADER_END@
	19	*/
	20
	21	/*
	22	* IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
	23	* which are subject to change in future releases of Mac OS X. Any applications
	24	* relying on these interfaces WILL break.
	25	*/
	26
	27	#ifndef __DISPATCH_DATA_PRIVATE__
	28	#define __DISPATCH_DATA_PRIVATE__
	29
	30	#ifndef __DISPATCH_INDIRECT__
	31	#error "Please #include <dispatch/dispatch.h> instead of this file directly."
	32	#include <dispatch/base.h> // for HeaderDoc
	33	#endif
	34
beb15981 A	35	DISPATCH_ASSUME_NONNULL_BEGIN
beb15981 A	36
c093abd6 A	37	__BEGIN_DECLS
c093abd6 A	38
c093abd6 A	39	/*!
c093abd6 A	40	* @const DISPATCH_DATA_DESTRUCTOR_NONE
517da941 A	41	* @discussion The destructor for dispatch data objects that require no buffer
	42	* memory management. This can be used to allow a data object to efficiently
	43	* encapsulate buffers that should not be copied or freed by the system.
c093abd6 A	44	*/
c093abd6 A	45	#define DISPATCH_DATA_DESTRUCTOR_NONE (_dispatch_data_destructor_none)
6b746eb4	46	API_AVAILABLE(macos(10.8), ios(6.0))
517da941	47	DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(none);
c093abd6 A	48
	49	/*!
	50	* @const DISPATCH_DATA_DESTRUCTOR_VM_DEALLOCATE
	51	* @discussion The destructor for dispatch data objects that have been created
	52	* from buffers that require deallocation using vm_deallocate.
	53	*/
	54	#define DISPATCH_DATA_DESTRUCTOR_VM_DEALLOCATE \
	55	(_dispatch_data_destructor_vm_deallocate)
6b746eb4	56	API_AVAILABLE(macos(10.8), ios(6.0)) DISPATCH_LINUX_UNAVAILABLE()
517da941 A	57	DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(vm_deallocate);
	58
	59	/*!
	60	* @function dispatch_data_create_f
	61	* Creates a dispatch data object from the given contiguous buffer of memory. If
	62	* a non-default destructor is provided, ownership of the buffer remains with
	63	* the caller (i.e. the bytes will not be copied). The last release of the data
	64	* object will result in the invocation of the specified destructor function on
	65	* specified queue to free the buffer (passed as the context parameter).
	66	*
	67	* If the DISPATCH_DATA_DESTRUCTOR_FREE destructor is provided the buffer will
	68	* be freed via free(3) and the queue argument ignored.
	69	*
	70	* If the DISPATCH_DATA_DESTRUCTOR_DEFAULT destructor is provided, data object
	71	* creation will copy the buffer into internal memory managed by the system.
	72	*
	73	* @param buffer A contiguous buffer of data.
	74	* @param size The size of the contiguous buffer of data.
	75	* @param queue The queue to which the destructor should be submitted.
	76	* @param destructor The destructor function responsible for freeing the
	77	* data buffer when it is no longer needed.
	78	* @result A newly created dispatch data object.
	79	*/
6b746eb4	80	API_AVAILABLE(macos(10.9), ios(7.0))
517da941 A	81	DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW
	82	dispatch_data_t
	83	dispatch_data_create_f(const void *buffer,
	84	size_t size,
beb15981 A	85	dispatch_queue_t _Nullable queue,
beb15981 A	86	dispatch_function_t _Nullable destructor);
517da941 A	87
	88	/*!
	89	* @function dispatch_data_create_alloc
	90	* Creates a dispatch data object representing a newly allocated memory region
	91	* of the given size. If a non-NULL reference to a pointer is provided, it is
	92	* filled with the location of the memory region.
	93	*
	94	* It is the responsibility of the application to ensure that the data object
	95	* becomes immutable (i.e. the returned memory region is not further modified)
	96	* once the dispatch data object is passed to other API.
	97	*
	98	* @param size The size of the required allocation.
	99	* @param buffer_ptr A pointer to a pointer variable to be filled with the
	100	* location of the newly allocated memory region, or NULL.
	101	* @result A newly created dispatch data object.
	102	*/
6b746eb4	103	API_AVAILABLE(macos(10.9), ios(6.0))
517da941 A	104	DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED
	105	DISPATCH_WARN_RESULT DISPATCH_NOTHROW
	106	dispatch_data_t
beb15981	107	dispatch_data_create_alloc(size_t size, void _Nullable _Nullable buffer_ptr);
517da941 A	108
	109	/*!
	110	* @typedef dispatch_data_applier_function_t
	111	* A function to be invoked for every contiguous memory region in a data object.
	112	*
	113	* @param context Application-defined context parameter.
	114	* @param region A data object representing the current region.
	115	* @param offset The logical offset of the current region to the start
	116	* of the data object.
	117	* @param buffer The location of the memory for the current region.
	118	* @param size The size of the memory for the current region.
	119	* @result A Boolean indicating whether traversal should continue.
	120	*/
beb15981	121	typedef bool (dispatch_data_applier_function_t)(void _Nullable context,
517da941 A	122	dispatch_data_t region, size_t offset, const void *buffer, size_t size);
	123
	124	/*!
	125	* @function dispatch_data_apply_f
	126	* Traverse the memory regions represented by the specified dispatch data object
	127	* in logical order and invoke the specified function once for every contiguous
	128	* memory region encountered.
	129	*
	130	* Each invocation of the function is passed a data object representing the
	131	* current region and its logical offset, along with the memory location and
	132	* extent of the region. These allow direct read access to the memory region,
	133	* but are only valid until the passed-in region object is released. Note that
	134	* the region object is released by the system when the function returns, it is
	135	* the responsibility of the application to retain it if the region object or
	136	* the associated memory location are needed after the function returns.
	137	*
	138	* @param data The data object to traverse.
	139	* @param context The application-defined context to pass to the function.
	140	* @param applier The function to be invoked for every contiguous memory
	141	* region in the data object.
	142	* @result A Boolean indicating whether traversal completed
	143	* successfully.
	144	*/
6b746eb4	145	API_AVAILABLE(macos(10.9), ios(6.0))
517da941 A	146	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
517da941 A	147	bool
beb15981	148	dispatch_data_apply_f(dispatch_data_t data, void *_Nullable context,
517da941 A	149	dispatch_data_applier_function_t applier);
	150
	151	#if TARGET_OS_MAC
	152	/*!
	153	* @function dispatch_data_make_memory_entry
	154	* Return a mach memory entry for the memory regions represented by the
	155	* specified dispatch data object.
	156	*
	157	* For data objects created with the DISPATCH_DATA_DESTRUCTOR_VM_DEALLOCATE
	158	* destructor, directly makes a memory entry from the represented region;
	159	* otherwise, makes a memory entry from newly allocated pages containing a copy
	160	* of the represented memory regions.
	161	*
	162	* @param data The data object to make a memory entry for.
	163	* @result A mach port for the newly made memory entry, or
beb15981	164	* MACH_PORT_NULL if an error occurred.
517da941	165	*/
6b746eb4	166	API_AVAILABLE(macos(10.9), ios(6.0))
517da941 A	167	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
517da941 A	168	mach_port_t
98cf8cd2	169	dispatch_data_make_memory_entry(dispatch_data_t data);
517da941 A	170	#endif
	171
	172	/*!
	173	* @functiongroup Dispatch data transform SPI
	174	*/
c093abd6 A	175
	176	/*!
	177	* @typedef dispatch_data_format_type_t
	178	*
	179	* @abstract
	180	* Data formats are used to specify the input and output types of data supplied
	181	* to dispatch_data_create_transform.
	182	*/
	183	typedef const struct dispatch_data_format_type_s *dispatch_data_format_type_t;
	184
517da941 A	185	#if !TARGET_OS_WIN32
	186	#define DISPATCH_DATA_FORMAT_TYPE_DECL(name) \
	187	DISPATCH_EXPORT const struct dispatch_data_format_type_s \
	188	_dispatch_data_format_type_##name
	189	#else
	190	#define DISPATCH_DATA_FORMAT_TYPE_DECL(name) \
	191	DISPATCH_EXPORT struct dispatch_data_format_type_s \
	192	_dispatch_data_format_type_##name
	193	#endif
	194
c093abd6 A	195	/*!
	196	* @const DISPATCH_DATA_FORMAT_TYPE_NONE
	197	* @discussion A data format denoting that the given input or output format is,
	198	* or should be, comprised of raw data bytes with no given encoding.
	199	*/
	200	#define DISPATCH_DATA_FORMAT_TYPE_NONE (&_dispatch_data_format_type_none)
6b746eb4	201	API_AVAILABLE(macos(10.8), ios(6.0))
517da941	202	DISPATCH_DATA_FORMAT_TYPE_DECL(none);
c093abd6 A	203
	204	/*!
	205	* @const DISPATCH_DATA_FORMAT_TYPE_BASE32
	206	* @discussion A data format denoting that the given input or output format is,
	207	* or should be, encoded in Base32 (RFC 4648) format. On input, this format will
	208	* skip whitespace characters. Cannot be used in conjunction with UTF format
	209	* types.
	210	*/
	211	#define DISPATCH_DATA_FORMAT_TYPE_BASE32 (&_dispatch_data_format_type_base32)
6b746eb4	212	API_AVAILABLE(macos(10.8), ios(6.0))
517da941 A	213	DISPATCH_DATA_FORMAT_TYPE_DECL(base32);
	214
	215	/*!
	216	* @const DISPATCH_DATA_FORMAT_TYPE_BASE32HEX
	217	* @discussion A data format denoting that the given input or output format is,
	218	* or should be, encoded in Base32Hex (RFC 4648) format. On input, this format
	219	* will skip whitespace characters. Cannot be used in conjunction with UTF
	220	* format types.
	221	*/
	222	#define DISPATCH_DATA_FORMAT_TYPE_BASE32HEX \
	223	(&_dispatch_data_format_type_base32hex)
6b746eb4	224	API_AVAILABLE(macos(10.9), ios(7.0))
517da941	225	DISPATCH_DATA_FORMAT_TYPE_DECL(base32hex);
c093abd6 A	226
	227	/*!
	228	* @const DISPATCH_DATA_FORMAT_TYPE_BASE64
	229	* @discussion A data format denoting that the given input or output format is,
	230	* or should be, encoded in Base64 (RFC 4648) format. On input, this format will
	231	* skip whitespace characters. Cannot be used in conjunction with UTF format
	232	* types.
	233	*/
	234	#define DISPATCH_DATA_FORMAT_TYPE_BASE64 (&_dispatch_data_format_type_base64)
6b746eb4	235	API_AVAILABLE(macos(10.8), ios(6.0))
517da941	236	DISPATCH_DATA_FORMAT_TYPE_DECL(base64);
c093abd6 A	237
	238	/*!
	239	* @const DISPATCH_DATA_FORMAT_TYPE_UTF8
	240	* @discussion A data format denoting that the given input or output format is,
	241	* or should be, encoded in UTF-8 format. Is only valid when used in conjunction
	242	* with other UTF format types.
	243	*/
	244	#define DISPATCH_DATA_FORMAT_TYPE_UTF8 (&_dispatch_data_format_type_utf8)
6b746eb4	245	API_AVAILABLE(macos(10.8), ios(6.0))
517da941	246	DISPATCH_DATA_FORMAT_TYPE_DECL(utf8);
c093abd6 A	247
	248	/*!
	249	* @const DISPATCH_DATA_FORMAT_TYPE_UTF16LE
	250	* @discussion A data format denoting that the given input or output format is,
	251	* or should be, encoded in UTF-16LE format. Is only valid when used in
	252	* conjunction with other UTF format types.
	253	*/
	254	#define DISPATCH_DATA_FORMAT_TYPE_UTF16LE (&_dispatch_data_format_type_utf16le)
6b746eb4	255	API_AVAILABLE(macos(10.8), ios(6.0))
517da941	256	DISPATCH_DATA_FORMAT_TYPE_DECL(utf16le);
c093abd6 A	257
	258	/*!
	259	* @const DISPATCH_DATA_FORMAT_TYPE_UTF16BE
	260	* @discussion A data format denoting that the given input or output format is,
	261	* or should be, encoded in UTF-16BE format. Is only valid when used in
	262	* conjunction with other UTF format types.
	263	*/
	264	#define DISPATCH_DATA_FORMAT_TYPE_UTF16BE (&_dispatch_data_format_type_utf16be)
6b746eb4	265	API_AVAILABLE(macos(10.8), ios(6.0))
517da941	266	DISPATCH_DATA_FORMAT_TYPE_DECL(utf16be);
c093abd6 A	267
	268	/*!
	269	* @const DISPATCH_DATA_FORMAT_TYPE_UTFANY
	270	* @discussion A data format denoting that dispatch_data_create_transform should
	271	* attempt to automatically detect the input type based on the presence of a
	272	* byte order mark character at the beginning of the data. In the absence of a
	273	* BOM, the data will be assumed to be in UTF-8 format. Only valid as an input
	274	* format.
	275	*/
	276	#define DISPATCH_DATA_FORMAT_TYPE_UTF_ANY (&_dispatch_data_format_type_utf_any)
6b746eb4	277	API_AVAILABLE(macos(10.8), ios(6.0))
517da941	278	DISPATCH_DATA_FORMAT_TYPE_DECL(utf_any);
c093abd6 A	279
	280	/*!
	281	* @function dispatch_data_create_transform
	282	* Returns a new dispatch data object after transforming the given data object
	283	* from the supplied format, into the given output format.
	284	*
	285	* @param data
	286	* The data object representing the region(s) of memory to transform.
	287	* @param input_type
	288	* Flags specifying the input format of the source dispatch_data_t
	289	*
	290	* @param output_type
beb15981	291	* Flags specifying the expected output format of the resulting transformation.
c093abd6 A	292	*
	293	* @result
	294	* A newly created dispatch data object, dispatch_data_empty if no has been
	295	* produced, or NULL if an error occurred.
	296	*/
	297
6b746eb4	298	API_AVAILABLE(macos(10.8), ios(6.0))
c093abd6 A	299	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_RETURNS_RETAINED
	300	DISPATCH_WARN_RESULT DISPATCH_NOTHROW
	301	dispatch_data_t
	302	dispatch_data_create_with_transform(dispatch_data_t data,
	303	dispatch_data_format_type_t input_type,
	304	dispatch_data_format_type_t output_type);
	305
c093abd6 A	306	__END_DECLS
c093abd6 A	307
beb15981 A	308	DISPATCH_ASSUME_NONNULL_END
beb15981 A	309
c093abd6	310	#endif // __DISPATCH_DATA_PRIVATE__