1/* 2 * Copyright (c) 2011 Apple Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24 25#ifndef COMMON_BASE_XX_H 26#define COMMON_BASE_XX_H 27 28#if !defined(COMMON_NUMERICS_H) 29#include <CommonNumerics/CommonNumerics.h> 30#endif 31 32#ifdef __cplusplus 33extern "C" { 34#endif 35 36/*! 37 @enum CNEncodings 38 @abstract Encodings available through CommonBaseXX(). 39 40 @constant kCNEncodingBase64 Base64 Encoding. 41 @constant kCNEncodingBase32 Base32 Encoding. 42 @constant kCNEncodingBase32HEX Base32 Encoding - 43 @constant kCNEncodingBase32Recovery Base32 Simplified Encoding. 44*/ 45enum { 46 kCNEncodingBase64 = 0x0001, 47 kCNEncodingBase32 = 0x0002, 48 kCNEncodingBase32Recovery = 0x0003, 49 kCNEncodingBase32HEX = 0x0004, 50 kCNEncodingBase16 = 0x0005, 51 kCNEncodingCustom = 0xcafe 52}; 53typedef uint32_t CNEncodings; 54 55/*! 56 @enum kCNEncodingDirection 57 @abstract Determine whether the CNEncoderRef is to be used 58 to encode or decode. 59 60 @constant kCNEncode Encode (base256 to baseXX) 61 @constant kCNDecode Decode (baseXX to base256) 62 */ 63 64enum { 65 kCNEncode = 0x0001, 66 kCNDecode = 0x0002, 67}; 68typedef uint32_t CNEncodingDirection; 69 70/*! 71 @typedef CNEncoderRef 72 @abstract Opaque reference to a CNEncoder object. 73 */ 74 75typedef struct _CNEncoder *CNEncoderRef; 76 77/*! 78 @function CNEncode 79 @abstract One-Shot baseXX encode or decode. 80 @param encoding selects one of the base encodings above. 81 @param direction Designate the direction (encode or decode) 82 @param in The bytes to be processed. 83 @param inLen The number of bytes to be processed. 84 @param out The destination of the processed data. 85 @param outLen The length of the processed data. 86 @result kCCSuccess or one of kCCParamErr, kCCMemoryFailure. 87 88 */ 89 90CNStatus 91CNEncode(CNEncodings encoding, 92 CNEncodingDirection direction, 93 const void *in, const size_t inLen, 94 void *out, size_t *outLen) 95__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0); 96 97 98 99 100/*! 101 @function CCEncoderCreate 102 @abstract Create a base encoder context. 103 @param encoding selects one of the base encodings above. 104 @param direction Designate the direction (encode or decode) for this 105 CNEncoderRef. 106 @param coderRef A (required) pointer to the returned CNEncoderRef. 107*/ 108 109CNStatus 110CNEncoderCreate(CNEncodings encoding, 111 CNEncodingDirection direction, 112 CNEncoderRef *encoderRef) /* RETURNED */ 113__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0); 114 115/*! 116 @function CCEncoderCreateCustom 117 @abstract Create a custom base encoder context. 118 @param name A name for this encoder (optional) 119 @param baseNum The base of the encoding (16, 32, 64) 120 @param charMap A string containing the characters to map an encoded 121 byte to for output. 122 @param padding The character to use for padding (usually '=') 123 @param direction Designate the direction (encode or decode) for this 124 CNEncoderRef. 125 @param coderRef A (required) pointer to the returned CNEncoderRef. 126 */ 127 128CNStatus 129CNEncoderCreateCustom( 130 const void *name, 131 const uint8_t baseNum, 132 const void *charMap, 133 const char padChar, 134 CNEncodingDirection direction, 135 CNEncoderRef *coderRef) /* RETURNED */ 136__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0); 137 138/*! 139 @function CNEncoderRelease 140 @abstract Release a CNEncoderRef and associated objects. 141 */ 142CNStatus 143CNEncoderRelease(CNEncoderRef *coderRef) 144__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0); 145 146 147/*! 148 @function CNEncoderGetOutputLength 149 @abstract Determine the size required to hold the result of processing the 150 input. 151 152 @param coderRef A CNEncoderRef obtained through CNEncoderCreate() 153 or CNEncoderCreateCustom(). 154 155 @param inLen The number of bytes to be processed. 156 157 @result The length required for the encoding. Zero (0) will be returned in 158 the result of a NULL input pointer for the "in" parameter. 159*/ 160 161size_t 162CNEncoderGetOutputLength(CNEncoderRef coderRef, const size_t inLen) 163__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0); 164 165/*! 166 @function CNEncoderGetOutputLengthFromEncoding 167 @abstract Determine the size required to hold the result of processing the 168 input given an encoding constant and direction and length. 169 170 @param encoding selects one of the base encodings above. 171 @param direction Designate the direction (encode or decode) for this 172 CNEncoderRef. 173 174 @param inLen The number of bytes to be processed. 175 176 @result The length required for the encoding. Zero (0) will be returned in 177 the result of a NULL input pointer for the "in" parameter. 178 */ 179 180size_t 181CNEncoderGetOutputLengthFromEncoding(CNEncodings encoding, 182 CNEncodingDirection direction, 183 const size_t inLen) 184__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0); 185 186/*! 187 @function CNEncoderUpdate 188 @abstract Encode or decode the input string to or from the designated 189 encoded format. 190 191 @param coderRef A CNEncoderRef obtained through CNEncoderCreate() 192 or CNEncoderCreateCustom(). 193 194 @param in The bytes to be processed. 195 196 @param inLen The number of bytes to be processed. 197 198 @param out The destination of the processed data. 199 200 @param outLen The length of the processed data. 201 202 @result kCCSuccess or one of kCCParamErr, kCCMemoryFailure. 203*/ 204 205CNStatus 206CNEncoderUpdate(CNEncoderRef coderRef, const void *in, const size_t inLen, void *out, 207 size_t *outLen) 208__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0); 209 210 211/*! 212 @function CNEncoderFinal 213 @abstract Complete coding for all available inputs, padding where necessary. 214 215 @param coderRef A CNEncoderRef obtained through CNEncoderCreate() 216 or CNEncoderCreateCustom(). 217 218 @param out The destination of the processed data. 219 220 @param outLen The length of the processed data. 221 222 @result kCCSuccess or one of kCCParamErr, kCCMemoryFailure. 223 */ 224 225CNStatus 226CNEncoderFinal(CNEncoderRef coderRef, void *out, size_t *outLen) 227__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0); 228 229 230/*! 231 @function CNEncoderBlocksize 232 @abstract Get the number of bytes per block of input (base256) to output (base of encoder). 233 234 @param encoding The encoding format. 235 236 @param inputSize The number of raw bytes upon which an encoding operation should be performed 237 if padding should not be added. If CNEncode is called with this many bytes 238 the resulting coded bytes will not need padding. 239 @param outputSize The output block size in bytes for this encoding. 240 241 @result kCCSuccess or kCCParamErr. 242 */ 243 244 245 246CNStatus 247CNEncoderBlocksize(CNEncodings encoding, size_t *inputSize, size_t *outputSize) 248__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0); 249 250/*! 251 @function CNEncoderBlocksizeFromRef 252 @abstract Get the number of bytes per block of input (base256) to output (base of encoder). 253 254 @param encoderRef A CNEncoderRef gotten from CNEncoderCreate or CNEncoderCreateCustom. 255 256 @param inputSize The number of raw bytes upon which an encoding operation should be performed 257 if padding should not be added. If CNEncode is called with this many bytes 258 the resulting coded bytes will not need padding. 259 @param outputSize The output block size in bytes for this encoding. 260 261 @result kCCSuccess or kCCParamErr. 262 */ 263 264CNStatus 265CNEncoderBlocksizeFromRef(CNEncoderRef encoderRef, size_t *inputSize, size_t *outputSize) 266__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0); 267 268 269#ifdef __cplusplus 270} 271#endif 272 273#endif /* COMMON_BASE_XX_H */ 274