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_Encoder takes as a parameter a pointer to a BUFFER. If @p input is @c NULL then
00031  *             @c Base64_Encoder 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_Encoder returns @c NULL. Otherwise
00034  *             @c Base64_Encoder 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_Encoder, 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 */