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