base64.h

00001 // Copyright (c) Microsoft. All rights reserved.
00002 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
00003 
00004 /** @file base64.h
00005 *   @brief Prototypes for functions related to encoding/decoding
00006 *   a @c buffer using standard base64 encoding.
00007 */
00008 
00009 #ifndef BASE64_H
00010 #define BASE64_H
00011 
00012 #include "azure_c_shared_utility/strings.h"
00013 #include "azure_c_shared_utility/buffer_.h"
00014 
00015 #ifdef __cplusplus
00016 #include <cstddef>
00017 extern "C" {
00018 #else
00019 #include <stddef.h>
00020 #endif
00021 
00022 #include "azure_c_shared_utility/umock_c_prod.h"
00023 
00024 
00025 /**
00026  * @brief   Base64 encodes a buffer and returns the resulting string.
00027  *
00028  * @param   input   The buffer that needs to be base64 encoded.
00029  *
00030  *          Base64_Encode takes as a parameter a pointer to a BUFFER. If @p input is @c NULL then
00031  *          @c Base64_Encode returns @c NULL. The size of the BUFFER pointed to by @p input may
00032  *          be zero. If when allocating memory to produce the encoding a failure occurs, then @c
00033  *          Base64_Encode returns @c NULL. Otherwise
00034  *          @c Base64_Encode returns a pointer to a STRING. That string contains the
00035  *          base 64 encoding of the @p input. This encoding of @p input will not contain embedded
00036  *          line feeds.
00037  *
00038  * @return  A @c STRING_HANDLE containing the base64 encoding of @p input.
00039  */
00040 MOCKABLE_FUNCTION(, STRING_HANDLE, Base64_Encode, BUFFER_HANDLE, input);
00041 
00042 /**
00043  * @brief   Base64 encodes the buffer pointed to by @p source and returns the resulting string.
00044  *
00045  * @param   source  The buffer that needs to be base64 encoded.
00046  * @param   size    The size.
00047  *
00048  *          This function produces a @c STRING_HANDLE containing the base64 encoding of the
00049  *          buffer pointed to by @p source, having the size as given by
00050  *          @p size. If @p source is @c NULL then @c Base64_Encode_Bytes returns @c NULL
00051  *          If @p source is not @c NULL and @p size is zero, then @c Base64_Encode_Bytes produces
00052  *          an empty @c STRING_HANDLE. Otherwise, @c Base64_Encode_Bytes produces a
00053  *          @c STRING_HANDLE containing the Base64 representation of the buffer. In case of
00054  *          any errors, @c Base64_Encode_Bytes returns @c NULL.].
00055  *
00056  * @return  @c NULL in case an error occurs or a @c STRING_HANDLE containing the base64 encoding
00057  *          of @p input.
00058  *
00059  */
00060 MOCKABLE_FUNCTION(, STRING_HANDLE, Base64_Encode_Bytes, const unsigned char*, source, size_t, size);
00061 
00062 /**
00063  * @brief   Base64 decodes the buffer pointed to by @p source and returns the resulting buffer.
00064  *
00065  * @param   source  A base64 encoded string buffer.
00066  *
00067  *          This function decodes the string pointed at by @p source using base64 decoding and
00068  *          returns the resulting buffer. If @p source is @c NULL then
00069  *          @c Base64_Decoder returns NULL. If the string pointed to by @p source is zero
00070  *          length then the handle returned refers to a zero length buffer. If there is any
00071  *          memory allocation failure during the decode or if the source string has an invalid
00072  *          length for a base 64 encoded string then @c Base64_Decoder returns @c NULL.
00073  * 
00074  * @return  A @c BUFFER_HANDLE pointing to a buffer containing the result of base64 decoding @p
00075  *          source.
00076  */
00077 MOCKABLE_FUNCTION(, BUFFER_HANDLE, Base64_Decoder, const char*, source);
00078 
00079 #ifdef __cplusplus
00080 }
00081 #endif
00082 
00083 #endif /* BASE64_H */