CommonBaseXX.h

/*
 * Copyright (c) 2011 Apple Inc. All Rights Reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */


#ifndef COMMON_BASE_XX_H
#define COMMON_BASE_XX_H

#if !defined(COMMON_NUMERICS_H)
#include "CommonNumerics.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

/*!
    @enum       CNEncodings
    @abstract   Encodings available through CommonBaseXX().

    @constant   kCNEncodingBase64   		Base64 Encoding.
    @constant   kCNEncodingBase32       	Base32 Encoding.
    @constant   kCNEncodingBase32HEX        Base32 Encoding -
    @constant   kCNEncodingBase32Recovery   Base32 Simplified Encoding.
*/
enum {
    kCNEncodingBase64   			= 0x0001,
	kCNEncodingBase32   			= 0x0002,
    kCNEncodingBase32Recovery       = 0x0003,
    kCNEncodingBase32HEX            = 0x0004,
    kCNEncodingBase16               = 0x0005,
    kCNEncodingCustom               = 0xcafe
};
typedef uint32_t CNEncodings;

/*!
 @enum       kCNEncodingDirection
 @abstract   Determine whether the CNEncoderRef is to be used
             to encode or decode.

 @constant   kCNEncode   		Encode (base256 to baseXX)
 @constant   kCNDecode       	Decode (baseXX to base256)
 */

enum {
    kCNEncode            = 0x0001,
    kCNDecode            = 0x0002,
};
typedef uint32_t CNEncodingDirection;

/*!
    @typedef    CNEncoderRef
    @abstract   Opaque reference to a CNEncoder object.
 */

typedef struct _CNEncoder *CNEncoderRef;

/*!
    @function   CNEncode
    @abstract   One-Shot baseXX encode or decode.
    @param      encoding selects one of the base encodings above.
    @param      direction   Designate the direction (encode or decode)
    @param      in          The bytes to be processed.
    @param		inLen		The number of bytes to be processed.
    @param		out			The destination of the processed data.
    @param		outLen		The length of the processed data.
    @result     kCCSuccess or one of kCCParamErr, kCCMemoryFailure.

 */

CNStatus
CNEncode(CNEncodings encoding,
                  CNEncodingDirection direction,
                  const void *in, const size_t inLen,
                  void *out,  size_t *outLen)
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0);




/*!
    @function   CCEncoderCreate
    @abstract   Create a base encoder context.
    @param      encoding    selects one of the base encodings above.
    @param      direction   Designate the direction (encode or decode) for this
                            CNEncoderRef.
    @param      coderRef  A (required) pointer to the returned CNEncoderRef.
*/

CNStatus
CNEncoderCreate(CNEncodings encoding,
                         CNEncodingDirection direction,
                         CNEncoderRef *encoderRef)  /* RETURNED */
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0);

/*!
    @function   CCEncoderCreateCustom
    @abstract   Create a custom base encoder context.
    @param      name        A name for this encoder (optional)
    @param      baseNum     The base of the encoding (16, 32, 64)
    @param      charMap     A string containing the characters to map an encoded
                            byte to for output.
    @param      padding     The character to use for padding (usually '=')
    @param      direction   Designate the direction (encode or decode) for this
                            CNEncoderRef.
    @param      coderRef  A (required) pointer to the returned CNEncoderRef.
 */

CNStatus
CNEncoderCreateCustom(
                               const void *name,
                               const uint8_t baseNum,
                               const void *charMap,
                               const char padChar,
                               CNEncodingDirection direction,
                         CNEncoderRef *coderRef)  /* RETURNED */
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0);

/*!
     @function   CNEncoderRelease
     @abstract   Release a CNEncoderRef and associated objects.
 */
CNStatus
CNEncoderRelease(CNEncoderRef *coderRef)
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0);


/*!
    @function   CNEncoderGetOutputLength
    @abstract   Determine the size required to hold the result of processing the
				input.

    @param      coderRef    A CNEncoderRef obtained through CNEncoderCreate()
                            or CNEncoderCreateCustom().

	@param		inLen		The number of bytes to be processed.

    @result     The length required for the encoding.  Zero (0) will be returned in
				the result of a NULL input pointer for the "in" parameter.
*/

size_t
CNEncoderGetOutputLength(CNEncoderRef coderRef, const size_t inLen)
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);

/*!
     @function   CNEncoderGetOutputLengthFromEncoding
     @abstract   Determine the size required to hold the result of processing the
                 input given an encoding constant and direction and length.

     @param      encoding    selects one of the base encodings above.
     @param      direction   Designate the direction (encode or decode) for this
                             CNEncoderRef.

     @param		 inLen		The number of bytes to be processed.

     @result     The length required for the encoding.  Zero (0) will be returned in
                 the result of a NULL input pointer for the "in" parameter.
 */

size_t
CNEncoderGetOutputLengthFromEncoding(CNEncodings encoding,
                                         CNEncodingDirection direction,
                                         const size_t inLen)
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);

/*!
    @function   CNEncoderUpdate
    @abstract   Encode or decode the input string to or from the designated
                encoded format.

	@param      coderRef  A CNEncoderRef obtained through CNEncoderCreate()
                            or CNEncoderCreateCustom().

	@param      in          The bytes to be processed.

	@param		inLen		The number of bytes to be processed.

	@param		out			The destination of the processed data.

	@param		outLen		The length of the processed data.

    @result     kCCSuccess or one of kCCParamErr, kCCMemoryFailure.
*/

CNStatus
CNEncoderUpdate(CNEncoderRef coderRef, const void *in, const size_t inLen, void *out,
         size_t *outLen)
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);


/*!
 @function   CNEncoderFinal
 @abstract   Complete coding for all available inputs, padding where necessary.

 @param      coderRef  A CNEncoderRef obtained through CNEncoderCreate()
                        or CNEncoderCreateCustom().

 @param		out			The destination of the processed data.

 @param		outLen		The length of the processed data.

 @result     kCCSuccess or one of kCCParamErr, kCCMemoryFailure.
 */

CNStatus
CNEncoderFinal(CNEncoderRef coderRef, void *out, size_t *outLen)
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);


/*!
 @function   CNEncoderBlocksize
 @abstract   Get the number of bytes per block of input (base256) to output (base of encoder).

 @param      encoding    The encoding format.

 @param      inputSize   The number of raw bytes upon which an encoding operation should be performed
                         if padding should not be added.  If CNEncode is called with this many bytes
                         the resulting coded bytes will not need padding.
 @param      outputSize  The output block size in bytes for this encoding.

 @result     kCCSuccess or kCCParamErr.
 */



CNStatus
CNEncoderBlocksize(CNEncodings encoding, size_t *inputSize, size_t *outputSize)
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);

/*!
 @function   CNEncoderBlocksizeFromRef
 @abstract   Get the number of bytes per block of input (base256) to output (base of encoder).

 @param      encoderRef  A CNEncoderRef gotten from CNEncoderCreate or CNEncoderCreateCustom.

 @param      inputSize   The number of raw bytes upon which an encoding operation should be performed
                        if padding should not be added.  If CNEncode is called with this many bytes
                        the resulting coded bytes will not need padding.
 @param      outputSize  The output block size in bytes for this encoding.

 @result     kCCSuccess or kCCParamErr.
 */

CNStatus
CNEncoderBlocksizeFromRef(CNEncoderRef encoderRef, size_t *inputSize, size_t *outputSize)
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);


#ifdef __cplusplus
}
#endif

#endif /* COMMON_BASE_XX_H */