private/data_private.h

   1 /*
   2  * Copyright (c) 2011-2013 Apple Inc. All rights reserved.
   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
  35 DISPATCH_ASSUME_NONNULL_BEGIN
  36
  37 __BEGIN_DECLS
  38
  39 /*!
  40  * @const DISPATCH_DATA_DESTRUCTOR_NONE
  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.
  44  */
  45 #define DISPATCH_DATA_DESTRUCTOR_NONE (_dispatch_data_destructor_none)
  46 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
  47 DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(none);
  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)
  56 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) DISPATCH_LINUX_UNAVAILABLE()
  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  */
  80 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0)
  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,
  85         dispatch_queue_t _Nullable queue,
  86         dispatch_function_t _Nullable destructor);
  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  */
 103 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 104 DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED
 105 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 106 dispatch_data_t
 107 dispatch_data_create_alloc(size_t size, void *_Nullable *_Nullable buffer_ptr);
 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  */
 121 typedef bool (*dispatch_data_applier_function_t)(void *_Nullable context,
 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  */
 145 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 146 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 147 bool
 148 dispatch_data_apply_f(dispatch_data_t data, void *_Nullable context,
 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
 164  *                      MACH_PORT_NULL if an error occurred.
 165  */
 166 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0)
 167 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
 168 mach_port_t
 169 dispatch_data_make_memory_entry(dispatch_data_t data);
 170 #endif
 171
 172 /*!
 173  * @functiongroup Dispatch data transform SPI
 174  */
 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
 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
 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)
 201 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 202 DISPATCH_DATA_FORMAT_TYPE_DECL(none);
 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)
 212 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 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)
 224 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
 225 DISPATCH_DATA_FORMAT_TYPE_DECL(base32hex);
 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)
 235 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 236 DISPATCH_DATA_FORMAT_TYPE_DECL(base64);
 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)
 245 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 246 DISPATCH_DATA_FORMAT_TYPE_DECL(utf8);
 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)
 255 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 256 DISPATCH_DATA_FORMAT_TYPE_DECL(utf16le);
 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)
 265 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 266 DISPATCH_DATA_FORMAT_TYPE_DECL(utf16be);
 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)
 277 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 278 DISPATCH_DATA_FORMAT_TYPE_DECL(utf_any);
 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
 291  * Flags specifying the expected output format of the resulting transformation.
 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
 298 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 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
 306 __END_DECLS
 307
 308 DISPATCH_ASSUME_NONNULL_END
 309
 310 #endif // __DISPATCH_DATA_PRIVATE__