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 __BEGIN_DECLS 36 37 /*! 38 * @const DISPATCH_DATA_DESTRUCTOR_NONE 39 * @discussion The destructor for dispatch data objects that require no buffer 40 * memory management. This can be used to allow a data object to efficiently 41 * encapsulate buffers that should not be copied or freed by the system. 42 */ 43 #define DISPATCH_DATA_DESTRUCTOR_NONE (_dispatch_data_destructor_none) 44 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 45 DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(none); 46 47 /*! 48 * @const DISPATCH_DATA_DESTRUCTOR_VM_DEALLOCATE 49 * @discussion The destructor for dispatch data objects that have been created 50 * from buffers that require deallocation using vm_deallocate. 51 */ 52 #define DISPATCH_DATA_DESTRUCTOR_VM_DEALLOCATE \ 53 (_dispatch_data_destructor_vm_deallocate) 54 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 55 DISPATCH_DATA_DESTRUCTOR_TYPE_DECL(vm_deallocate); 56 57 /*! 58 * @function dispatch_data_create_f 59 * Creates a dispatch data object from the given contiguous buffer of memory. If 60 * a non-default destructor is provided, ownership of the buffer remains with 61 * the caller (i.e. the bytes will not be copied). The last release of the data 62 * object will result in the invocation of the specified destructor function on 63 * specified queue to free the buffer (passed as the context parameter). 64 * 65 * If the DISPATCH_DATA_DESTRUCTOR_FREE destructor is provided the buffer will 66 * be freed via free(3) and the queue argument ignored. 67 * 68 * If the DISPATCH_DATA_DESTRUCTOR_DEFAULT destructor is provided, data object 69 * creation will copy the buffer into internal memory managed by the system. 70 * 71 * @param buffer A contiguous buffer of data. 72 * @param size The size of the contiguous buffer of data. 73 * @param queue The queue to which the destructor should be submitted. 74 * @param destructor The destructor function responsible for freeing the 75 * data buffer when it is no longer needed. 76 * @result A newly created dispatch data object. 77 */ 78 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_7_0) 79 DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW 80 dispatch_data_t 81 dispatch_data_create_f(const void *buffer, 82 size_t size, 83 dispatch_queue_t queue, 84 dispatch_function_t destructor); 85 86 /*! 87 * @function dispatch_data_create_alloc 88 * Creates a dispatch data object representing a newly allocated memory region 89 * of the given size. If a non-NULL reference to a pointer is provided, it is 90 * filled with the location of the memory region. 91 * 92 * It is the responsibility of the application to ensure that the data object 93 * becomes immutable (i.e. the returned memory region is not further modified) 94 * once the dispatch data object is passed to other API. 95 * 96 * @param size The size of the required allocation. 97 * @param buffer_ptr A pointer to a pointer variable to be filled with the 98 * location of the newly allocated memory region, or NULL. 99 * @result A newly created dispatch data object. 100 */ 101 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0) 102 DISPATCH_EXPORT DISPATCH_RETURNS_RETAINED 103 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 104 dispatch_data_t 105 dispatch_data_create_alloc(size_t size, void** buffer_ptr); 106 107 /*! 108 * @typedef dispatch_data_applier_function_t 109 * A function to be invoked for every contiguous memory region in a data object. 110 * 111 * @param context Application-defined context parameter. 112 * @param region A data object representing the current region. 113 * @param offset The logical offset of the current region to the start 114 * of the data object. 115 * @param buffer The location of the memory for the current region. 116 * @param size The size of the memory for the current region. 117 * @result A Boolean indicating whether traversal should continue. 118 */ 119 typedef bool (*dispatch_data_applier_function_t)(void *context, 120 dispatch_data_t region, size_t offset, const void *buffer, size_t size); 121 122 /*! 123 * @function dispatch_data_apply_f 124 * Traverse the memory regions represented by the specified dispatch data object 125 * in logical order and invoke the specified function once for every contiguous 126 * memory region encountered. 127 * 128 * Each invocation of the function is passed a data object representing the 129 * current region and its logical offset, along with the memory location and 130 * extent of the region. These allow direct read access to the memory region, 131 * but are only valid until the passed-in region object is released. Note that 132 * the region object is released by the system when the function returns, it is 133 * the responsibility of the application to retain it if the region object or 134 * the associated memory location are needed after the function returns. 135 * 136 * @param data The data object to traverse. 137 * @param context The application-defined context to pass to the function. 138 * @param applier The function to be invoked for every contiguous memory 139 * region in the data object. 140 * @result A Boolean indicating whether traversal completed 141 * successfully. 142 */ 143 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0) 144 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 145 bool 146 dispatch_data_apply_f(dispatch_data_t data, void *context, 147 dispatch_data_applier_function_t applier); 148 149 #if TARGET_OS_MAC 150 /*! 151 * @function dispatch_data_make_memory_entry 152 * Return a mach memory entry for the memory regions represented by the 153 * specified dispatch data object. 154 * 155 * For data objects created with the DISPATCH_DATA_DESTRUCTOR_VM_DEALLOCATE 156 * destructor, directly makes a memory entry from the represented region; 157 * otherwise, makes a memory entry from newly allocated pages containing a copy 158 * of the represented memory regions. 159 * 160 * @param data The data object to make a memory entry for. 161 * @result A mach port for the newly made memory entry, or 162 * MACH_PORT_NULL if an error ocurred. 163 */ 164 __OSX_AVAILABLE_STARTING(__MAC_10_9,__IPHONE_6_0) 165 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW 166 mach_port_t 167 dispatch_data_make_memory_entry(dispatch_data_t data); 168 #endif 169 170 /*! 171 * @functiongroup Dispatch data transform SPI 172 */ 173 174 /*! 175 * @typedef dispatch_data_format_type_t 176 * 177 * @abstract 178 * Data formats are used to specify the input and output types of data supplied 179 * to dispatch_data_create_transform. 180 */ 181 typedef const struct dispatch_data_format_type_s *dispatch_data_format_type_t; 182 183 #if !TARGET_OS_WIN32 184 #define DISPATCH_DATA_FORMAT_TYPE_DECL(name) \ 185 DISPATCH_EXPORT const struct dispatch_data_format_type_s \ 186 _dispatch_data_format_type_##name 187 #else 188 #define DISPATCH_DATA_FORMAT_TYPE_DECL(name) \ 189 DISPATCH_EXPORT struct dispatch_data_format_type_s \ 190 _dispatch_data_format_type_##name 191 #endif 192 193 /*! 194 * @const DISPATCH_DATA_FORMAT_TYPE_NONE 195 * @discussion A data format denoting that the given input or output format is, 196 * or should be, comprised of raw data bytes with no given encoding. 197 */ 198 #define DISPATCH_DATA_FORMAT_TYPE_NONE (&_dispatch_data_format_type_none) 199 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 200 DISPATCH_DATA_FORMAT_TYPE_DECL(none); 201 202 /*! 203 * @const DISPATCH_DATA_FORMAT_TYPE_BASE32 204 * @discussion A data format denoting that the given input or output format is, 205 * or should be, encoded in Base32 (RFC 4648) format. On input, this format will 206 * skip whitespace characters. Cannot be used in conjunction with UTF format 207 * types. 208 */ 209 #define DISPATCH_DATA_FORMAT_TYPE_BASE32 (&_dispatch_data_format_type_base32) 210 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 211 DISPATCH_DATA_FORMAT_TYPE_DECL(base32); 212 213 /*! 214 * @const DISPATCH_DATA_FORMAT_TYPE_BASE32HEX 215 * @discussion A data format denoting that the given input or output format is, 216 * or should be, encoded in Base32Hex (RFC 4648) format. On input, this format 217 * will skip whitespace characters. Cannot be used in conjunction with UTF 218 * format types. 219 */ 220 #define DISPATCH_DATA_FORMAT_TYPE_BASE32HEX \ 221 (&_dispatch_data_format_type_base32hex) 222 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 223 DISPATCH_DATA_FORMAT_TYPE_DECL(base32hex); 224 225 /*! 226 * @const DISPATCH_DATA_FORMAT_TYPE_BASE64 227 * @discussion A data format denoting that the given input or output format is, 228 * or should be, encoded in Base64 (RFC 4648) format. On input, this format will 229 * skip whitespace characters. Cannot be used in conjunction with UTF format 230 * types. 231 */ 232 #define DISPATCH_DATA_FORMAT_TYPE_BASE64 (&_dispatch_data_format_type_base64) 233 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 234 DISPATCH_DATA_FORMAT_TYPE_DECL(base64); 235 236 /*! 237 * @const DISPATCH_DATA_FORMAT_TYPE_UTF8 238 * @discussion A data format denoting that the given input or output format is, 239 * or should be, encoded in UTF-8 format. Is only valid when used in conjunction 240 * with other UTF format types. 241 */ 242 #define DISPATCH_DATA_FORMAT_TYPE_UTF8 (&_dispatch_data_format_type_utf8) 243 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 244 DISPATCH_DATA_FORMAT_TYPE_DECL(utf8); 245 246 /*! 247 * @const DISPATCH_DATA_FORMAT_TYPE_UTF16LE 248 * @discussion A data format denoting that the given input or output format is, 249 * or should be, encoded in UTF-16LE format. Is only valid when used in 250 * conjunction with other UTF format types. 251 */ 252 #define DISPATCH_DATA_FORMAT_TYPE_UTF16LE (&_dispatch_data_format_type_utf16le) 253 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 254 DISPATCH_DATA_FORMAT_TYPE_DECL(utf16le); 255 256 /*! 257 * @const DISPATCH_DATA_FORMAT_TYPE_UTF16BE 258 * @discussion A data format denoting that the given input or output format is, 259 * or should be, encoded in UTF-16BE format. Is only valid when used in 260 * conjunction with other UTF format types. 261 */ 262 #define DISPATCH_DATA_FORMAT_TYPE_UTF16BE (&_dispatch_data_format_type_utf16be) 263 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 264 DISPATCH_DATA_FORMAT_TYPE_DECL(utf16be); 265 266 /*! 267 * @const DISPATCH_DATA_FORMAT_TYPE_UTFANY 268 * @discussion A data format denoting that dispatch_data_create_transform should 269 * attempt to automatically detect the input type based on the presence of a 270 * byte order mark character at the beginning of the data. In the absence of a 271 * BOM, the data will be assumed to be in UTF-8 format. Only valid as an input 272 * format. 273 */ 274 #define DISPATCH_DATA_FORMAT_TYPE_UTF_ANY (&_dispatch_data_format_type_utf_any) 275 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 276 DISPATCH_DATA_FORMAT_TYPE_DECL(utf_any); 277 278 /*! 279 * @function dispatch_data_create_transform 280 * Returns a new dispatch data object after transforming the given data object 281 * from the supplied format, into the given output format. 282 * 283 * @param data 284 * The data object representing the region(s) of memory to transform. 285 * @param input_type 286 * Flags specifying the input format of the source dispatch_data_t 287 * 288 * @param output_type 289 * Flags specifying the expected output format of the resulting transfomation. 290 * 291 * @result 292 * A newly created dispatch data object, dispatch_data_empty if no has been 293 * produced, or NULL if an error occurred. 294 */ 295 296 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0) 297 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_RETURNS_RETAINED 298 DISPATCH_WARN_RESULT DISPATCH_NOTHROW 299 dispatch_data_t 300 dispatch_data_create_with_transform(dispatch_data_t data, 301 dispatch_data_format_type_t input_type, 302 dispatch_data_format_type_t output_type); 303 304 __END_DECLS 305 306 #endif // __DISPATCH_DATA_PRIVATE__ 307