private/data_private.h

   1 /*
   2  * Copyright (c) 2011 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 #ifdef __BLOCKS__
  38
  39 /*!
  40  * @const DISPATCH_DATA_DESTRUCTOR_NONE
  41  * @discussion The destructor for dispatch data objects that require no
  42  * management. This can be used to allow a data object to efficiently
  43  * encapsulate data 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_EXPORT const dispatch_block_t _dispatch_data_destructor_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)
  57 DISPATCH_EXPORT const dispatch_block_t _dispatch_data_destructor_vm_deallocate;
  58
  59 /*!
  60  * @typedef dispatch_data_format_type_t
  61  *
  62  * @abstract
  63  * Data formats are used to specify the input and output types of data supplied
  64  * to dispatch_data_create_transform.
  65  */
  66 typedef const struct dispatch_data_format_type_s *dispatch_data_format_type_t;
  67
  68 /*!
  69  * @const DISPATCH_DATA_FORMAT_TYPE_NONE
  70  * @discussion A data format denoting that the given input or output format is,
  71  * or should be, comprised of raw data bytes with no given encoding.
  72  */
  73 #define DISPATCH_DATA_FORMAT_TYPE_NONE (&_dispatch_data_format_type_none)
  74 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
  75 DISPATCH_EXPORT
  76 const struct dispatch_data_format_type_s _dispatch_data_format_type_none;
  77
  78 /*!
  79  * @const DISPATCH_DATA_FORMAT_TYPE_BASE32
  80  * @discussion A data format denoting that the given input or output format is,
  81  * or should be, encoded in Base32 (RFC 4648) format. On input, this format will
  82  * skip whitespace characters. Cannot be used in conjunction with UTF format
  83  * types.
  84  */
  85 #define DISPATCH_DATA_FORMAT_TYPE_BASE32 (&_dispatch_data_format_type_base32)
  86 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
  87 DISPATCH_EXPORT
  88 const struct dispatch_data_format_type_s _dispatch_data_format_type_base32;
  89
  90 /*!
  91  * @const DISPATCH_DATA_FORMAT_TYPE_BASE64
  92  * @discussion A data format denoting that the given input or output format is,
  93  * or should be, encoded in Base64 (RFC 4648) format. On input, this format will
  94  * skip whitespace characters. Cannot be used in conjunction with UTF format
  95  * types.
  96  */
  97 #define DISPATCH_DATA_FORMAT_TYPE_BASE64 (&_dispatch_data_format_type_base64)
  98 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
  99 DISPATCH_EXPORT
 100 const struct dispatch_data_format_type_s _dispatch_data_format_type_base64;
 101
 102 /*!
 103  * @const DISPATCH_DATA_FORMAT_TYPE_UTF8
 104  * @discussion A data format denoting that the given input or output format is,
 105  * or should be, encoded in UTF-8 format. Is only valid when used in conjunction
 106  * with other UTF format types.
 107  */
 108 #define DISPATCH_DATA_FORMAT_TYPE_UTF8 (&_dispatch_data_format_type_utf8)
 109 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 110 DISPATCH_EXPORT
 111 const struct dispatch_data_format_type_s _dispatch_data_format_type_utf8;
 112
 113 /*!
 114  * @const DISPATCH_DATA_FORMAT_TYPE_UTF16LE
 115  * @discussion A data format denoting that the given input or output format is,
 116  * or should be, encoded in UTF-16LE format. Is only valid when used in
 117  * conjunction with other UTF format types.
 118  */
 119 #define DISPATCH_DATA_FORMAT_TYPE_UTF16LE (&_dispatch_data_format_type_utf16le)
 120 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 121 DISPATCH_EXPORT
 122 const struct dispatch_data_format_type_s _dispatch_data_format_type_utf16le;
 123
 124 /*!
 125  * @const DISPATCH_DATA_FORMAT_TYPE_UTF16BE
 126  * @discussion A data format denoting that the given input or output format is,
 127  * or should be, encoded in UTF-16BE format. Is only valid when used in
 128  * conjunction with other UTF format types.
 129  */
 130 #define DISPATCH_DATA_FORMAT_TYPE_UTF16BE (&_dispatch_data_format_type_utf16be)
 131 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 132 DISPATCH_EXPORT
 133 const struct dispatch_data_format_type_s _dispatch_data_format_type_utf16be;
 134
 135 /*!
 136  * @const DISPATCH_DATA_FORMAT_TYPE_UTFANY
 137  * @discussion A data format denoting that dispatch_data_create_transform should
 138  * attempt to automatically detect the input type based on the presence of a
 139  * byte order mark character at the beginning of the data. In the absence of a
 140  * BOM, the data will be assumed to be in UTF-8 format. Only valid as an input
 141  * format.
 142  */
 143 #define DISPATCH_DATA_FORMAT_TYPE_UTF_ANY (&_dispatch_data_format_type_utf_any)
 144 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 145 DISPATCH_EXPORT
 146 const struct dispatch_data_format_type_s _dispatch_data_format_type_utf_any;
 147
 148 /*!
 149  * @function dispatch_data_create_transform
 150  * Returns a new dispatch data object after transforming the given data object
 151  * from the supplied format, into the given output format.
 152  *
 153  * @param data
 154  * The data object representing the region(s) of memory to transform.
 155  * @param input_type
 156  * Flags specifying the input format of the source dispatch_data_t
 157  *
 158  * @param output_type
 159  * Flags specifying the expected output format of the resulting transfomation.
 160  *
 161  * @result
 162  * A newly created dispatch data object, dispatch_data_empty if no has been
 163  * produced, or NULL if an error occurred.
 164  */
 165
 166 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0)
 167 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_RETURNS_RETAINED
 168 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 169 dispatch_data_t
 170 dispatch_data_create_with_transform(dispatch_data_t data,
 171         dispatch_data_format_type_t input_type,
 172         dispatch_data_format_type_t output_type);
 173
 174 #endif /* __BLOCKS__ */
 175
 176 __END_DECLS
 177
 178 #endif // __DISPATCH_DATA_PRIVATE__