1/*
2 * Copyright (c) 2011,2013 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     */
45    enum {
46        kCNEncodingBase64   			= 0x0001,
47        kCNEncodingBase32   			= 0x0002,
48        kCNEncodingBase32Recovery       = 0x0003,
49        kCNEncodingBase32HEX            = 0x0004,
50        kCNEncodingBase16               = 0x0005,
51        kCNEncodingCustom               = 0xcafe
52    };
53    typedef 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
64    enum {
65        kCNEncode            = 0x0001,
66        kCNDecode            = 0x0002,
67    };
68    typedef uint32_t CNEncodingDirection;
69
70    /*!
71     @typedef    CNEncoderRef
72     @abstract   Opaque reference to a CNEncoder object.
73     */
74
75    typedef 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
90    CNStatus
91    CNEncode(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
109    CNStatus
110    CNEncoderCreate(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
128    CNStatus
129    CNEncoderCreateCustom(
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     */
142    CNStatus
143    CNEncoderRelease(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
161    size_t
162    CNEncoderGetOutputLength(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
180    size_t
181    CNEncoderGetOutputLengthFromEncoding(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
205    CNStatus
206    CNEncoderUpdate(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
225    CNStatus
226    CNEncoderFinal(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
246    CNStatus
247    CNEncoderBlocksize(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
264    CNStatus
265    CNEncoderBlocksizeFromRef(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