b64/b64.hpp

Go to the documentation of this file.

/* /////////////////////////////////////////////////////////////////////////////
 * File:        b64/b64.hpp
 *
 * Purpose:     Header file for the b64 C++-API.
 *
 * Created:     18th October 2004
 * Updated:     24th August 2008
 *
 * Home:        http://synesis.com.au/software/
 *
 * Copyright 2004-2008, Matthew Wilson and Synesis Software
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer. 
 * - Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
 *   any contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * ////////////////////////////////////////////////////////////////////////// */


#ifndef B64_INCL_B64_HPP_B64
#define B64_INCL_B64_HPP_B64

/* /////////////////////////////////////////////////////////////////////////////
 * Version information
 */

#ifndef B64_DOCUMENTATION_SKIP_SECTION
# define B64_VER_B64_HPP_B64_MAJOR      2
# define B64_VER_B64_HPP_B64_MINOR      1
# define B64_VER_B64_HPP_B64_REVISION   5
# define B64_VER_B64_HPP_B64_EDIT       30
#endif /* !B64_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////////
 * Includes
 */

#ifndef B64_INCL_B64_H_B64
# include <b64/b64.h>
#endif /* !B64_INCL_B64_H_B64 */

/* If the compiler cannot find the following include, you may have not
 * upgraded to the latest version of STLSoft: 1.9.1. Go to
 *  http://stlsoft.org/ and download this version or later.
 */
#ifndef STLSOFT_INCL_STLSOFT_H_STLSOFT
# include <stlsoft/stlsoft.h>
#endif /* !STLSOFT_INCL_STLSOFT_H_STLSOFT */

#if !defined(_STLSOFT_VER) || \
    _STLSOFT_VER < 0x010930ff
# error Requires STLSoft 1.9.48, or later. (www.stlsoft.org/downloads.html)
#endif /* STLSoft version */

#ifdef STLSOFT_CF_std_NAMESPACE

# if defined(B64_USE_CUSTOM_STRING)
#  include B64_CUSTOM_STRING_INCLUDE
# else /* B64_USE_CUSTOM_STRING */
#  include <string>
# endif /* !B64_USE_CUSTOM_STRING */

# if defined(B64_USE_CUSTOM_VECTOR)
#  include B64_CUSTOM_VECTOR_INCLUDE
# else /* B64_USE_CUSTOM_VECTOR */
#  include <vector>
# endif /* !B64_USE_CUSTOM_VECTOR */

 /* We'll now have a go at checking whether the string type is 
  * known to be contiguous
  */
# ifndef STLSOFT_INCL_STLSOFT_UTIL_STD_LIBRARY_DISCRIMINATOR
#  include <stlsoft/util/std/library_discriminator.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_UTIL_STD_LIBRARY_DISCRIMINATOR */
# ifdef STLSOFT_CF_STD_LIBRARY_IS_DINKUMWARE_VC
#  if STLSOFT_CF_STD_LIBRARY_DINKUMWARE_VC_VERSION <= STLSOFT_CF_DINKUMWARE_VC_VERSION_7_1
#   define B64_STRING_TYPE_IS_CONTIGUOUS
#  endif /* STLSOFT_CF_STD_LIBRARY_DINKUMWARE_VC_VERSION */
# endif /* STLSOFT_CF_STD_LIBRARY_IS_DINKUMWARE_VC */

#else /* ? STLSOFT_CF_std_NAMESPACE */

# if defined(STLSOFT_COMPILER_IS_WATCOM)
#  include <string.hpp>
#  include <wcvector.h>
#  define   B64_USE_CUSTOM_STRING
#  define   B64_CUSTOM_STRING_TYPE      watcom_string_for_b64
#  define   B64_USE_CUSTOM_VECTOR
#  define   B64_CUSTOM_BLOB_TYPE        watcom_vector_for_b64
#  define   B64_STRING_TYPE_IS_CONTIGUOUS
# else /* ? compiler */
#  error No other non-std compiler is known
# endif /* ? compiler */

#endif /* STLSOFT_CF_std_NAMESPACE */

#ifdef B64_NO_CONTIGUOUS_STRING_TYPE
# ifdef B64_STRING_TYPE_IS_CONTIGUOUS
#  undef B64_STRING_TYPE_IS_CONTIGUOUS
# endif /* B64_STRING_TYPE_IS_CONTIGUOUS */
#endif /* B64_NO_CONTIGUOUS_STRING_TYPE */

#if !defined(B64_STRING_TYPE_IS_CONTIGUOUS)
# ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER
#  include <stlsoft/memory/auto_buffer.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER */
#endif /* !B64_STRING_TYPE_IS_CONTIGUOUS */

#ifndef STLSOFT_INCL_STLSOFT_SHIMS_ACCESS_HPP_STRING
# include <stlsoft/shims/access/string.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_SHIMS_ACCESS_HPP_STRING */

#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
# if defined(STLSOFT_COMPILER_IS_WATCOM)
#  include <stdexcep.h>
# else /* ? compiler */
#  include <stdexcept>
# endif /* compiler */
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */

/* /////////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#ifndef B64_NO_NAMESPACE
namespace B64_NAMESPACE
{
#endif /* !B64_NO_NAMESPACE */

/* /////////////////////////////////////////////////////////////////////////////
 * Classes
 */

#if defined(STLSOFT_COMPILER_IS_WATCOM)
class watcom_vector_for_b64
    : public WCValVector<unsigned char>
{
private:
    typedef WCValVector<unsigned char>  parent_class_type;
    typedef watcom_vector_for_b64       class_type;
public:
    watcom_vector_for_b64()
    {}
    watcom_vector_for_b64(size_t n)
        : parent_class_type(n)
    {}
    watcom_vector_for_b64(class_type const &rhs)
        : parent_class_type(rhs)
    {}

public:
    size_t size() const
    {
        return parent_class_type::length();
    }
};

class watcom_string_for_b64
    : public String
{
public:
    watcom_string_for_b64(size_t n, char ch)
        : String(ch, n)
    {}

public:
    void resize(size_t n)
    {
        String  &this_  =   *this;

        this_ = String(*this, n);
    }
};
#endif /* STLSOFT_COMPILER_IS_WATCOM */

#ifdef STLSOFT_CF_EXCEPTION_SUPPORT

class coding_exception
    : public stlsoft_ns_qual_std(runtime_error)
{
public:
    typedef stlsoft_ns_qual_std(runtime_error)  parent_class_type;
    typedef coding_exception                    class_type;

public:
    coding_exception(B64_RC rc, char const *badChar)
        : parent_class_type("decoding error")
        , m_rc(rc)
        , m_badChar(badChar)
    {}

public:
    virtual char const *what() const throw()
    {
        return "decoding error";
    }

public:
    B64_RC      get_rc() const
    {
        return m_rc;
    }
    char const  *get_badChar() const
    {
        return m_badChar;
    }

private:
    B64_RC      m_rc;
    char const  *m_badChar;
};
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */

/* /////////////////////////////////////////////////////////////////////////////
 * Typedefs
 */

#if defined(B64_USE_CUSTOM_STRING)
typedef B64_CUSTOM_STRING_TYPE          string_t;
#else /* B64_USE_CUSTOM_STRING */
typedef std::string                     string_t;
#endif /* !B64_USE_CUSTOM_STRING */

#if defined(B64_USE_CUSTOM_VECTOR)
typedef B64_CUSTOM_BLOB_TYPE            blob_t;
#else /* B64_USE_CUSTOM_VECTOR */
# ifndef B64_DOCUMENTATION_SKIP_SECTION
typedef ::stlsoft::byte_t               byte_t_;
typedef std::vector<byte_t_>            blob_t;
# else /* !B64_DOCUMENTATION_SKIP_SECTION */
typedef std::vector< ::stlsoft::byte_t> blob_t;
# endif /* !B64_DOCUMENTATION_SKIP_SECTION */
#endif /* !B64_USE_CUSTOM_VECTOR */

/* /////////////////////////////////////////////////////////////////////////////
 * Functions
 */

inline string_t encode(void const *src, size_t srcSize, unsigned flags, int lineLen = 0, B64_RC *rc = NULL)
{
    B64_RC  rc_;

    // Make sure rc is non-NULL, since we will need to get the RC in order to
    // throw exception later.
    if(NULL == rc)
    {
        rc = &rc_;
    }

    size_t      n   =   B64_NAMESPACE_QUALIFIER::b64_encode2(src, srcSize, NULL, 0, flags, lineLen, rc);

#ifdef B64_STRING_TYPE_IS_CONTIGUOUS

    // If the string type is known to have contiguous storage we can avoid
    // any intermediate memory, and decode directly into its internal
    // buffer.

    string_t    s(n, '~'); // ~ is used for an invalid / eyecatcher

    STLSOFT_MESSAGE_ASSERT("assumed contiguous string type is not so. Please report this error. To effect fix now, #define B64_NO_CONTIGUOUS_STRING_TYPE", 0 == n || &s[n - 1] == &s[0] + (n - 1));

    size_t      n2  =   B64_NAMESPACE_QUALIFIER::b64_encode2(src, srcSize, &s[0], s.length(), flags, lineLen, rc);

    s.resize(n2);

#else /* ? B64_STRING_TYPE_IS_CONTIGUOUS */

    // If the string type is not known to be contiguous, then we must use
    // intermediate storage. Here we use a 1KB auto_buffer, so that only
    // data in excess of that will incur an additional (over the string's)
    // heap allocation.

    typedef stlsoft::auto_buffer<char, 1024>        buffer_t;

    buffer_t    buffer(n);
    size_t      n2  =   B64_NAMESPACE_QUALIFIER::b64_encode2(src, srcSize, &buffer[0], buffer.size(), flags, lineLen, rc);

    string_t    s(&buffer[0], n2);
#endif /* B64_STRING_TYPE_IS_CONTIGUOUS */

#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
    if( 0 != srcSize &&
        0 == n2 &&
        rc == &rc_)
    {
        throw coding_exception(*rc, NULL);
    }
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */

    return s;
}

inline string_t encode(void const *src, size_t srcSize)
{
    return encode(src, srcSize, 0, 0, NULL);
}

#ifdef STLSOFT_CF_STATIC_ARRAY_SIZE_DETERMINATION_SUPPORT

template <typename T, size_t N>
inline string_t encode(T (&ar)[N])
{
    return encode(&ar[0], sizeof(T) * N);
}
#endif /* STLSOFT_CF_STATIC_ARRAY_SIZE_DETERMINATION_SUPPORT */

inline string_t encode(blob_t const &blob)
{
    return encode(&blob[0], blob.size());
}

inline string_t encode(blob_t const &blob, unsigned flags, int lineLen = 0, B64_RC *rc = NULL)
{
    return encode(&blob[0], blob.size(), flags, lineLen, rc);
}

inline blob_t decode(char const *src, size_t srcLen, unsigned flags, char const **badChar = NULL, B64_RC *rc = NULL)
{
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
    B64_RC      rc_;
    char const  *badChar_;

    if(NULL == rc)
    {
        rc = &rc_;
    }
    if(NULL == badChar)
    {
        badChar = &badChar_;
    }
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */

    size_t  n   =   B64_NAMESPACE_QUALIFIER::b64_decode2(src, srcLen, NULL, 0, flags, badChar, rc);
    blob_t  v(n);
    size_t  n2  =   v.empty() ? 0 : B64_NAMESPACE_QUALIFIER::b64_decode2(src, srcLen, &v[0], v.size(), flags, badChar, rc);

    v.resize(n2);

#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
    if( 0 != srcLen &&
        0 == n2 &&
        rc == &rc_)
    {
        throw coding_exception(*rc, *badChar);
    }
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */

    return v;
}

inline blob_t decode(char const *src, size_t srcLen)
{
    return decode(src, srcLen, 0, NULL, NULL);
}

template <class S>
inline blob_t decode(S const &str)
{
    stlsoft_ns_using(c_str_data_a);
    stlsoft_ns_using(c_str_len_a);

    return decode(c_str_data_a(str), c_str_len_a(str));
}

inline blob_t decode(string_t const &str, unsigned flags = 0)
{
    stlsoft_ns_using(c_str_data_a);
    stlsoft_ns_using(c_str_len_a);

    return decode(c_str_data_a(str), c_str_len_a(str), flags, NULL, NULL);
}

inline blob_t decode(string_t const &str, unsigned flags, char const **badChar, B64_RC *rc = NULL)
{
    stlsoft_ns_using(c_str_data_a);
    stlsoft_ns_using(c_str_len_a);

    return decode(c_str_data_a(str), c_str_len_a(str), flags, badChar, rc);
}

/* /////////////////////////////////////////////////////////////////////////////
 * Namespace
 */

namespace cpp
{

    using B64_NAMESPACE::coding_exception;

    using B64_NAMESPACE::blob_t;
    using B64_NAMESPACE::string_t;

    using B64_NAMESPACE::decode;
    using B64_NAMESPACE::encode;

} /* namespace cpp */

#ifndef B64_NO_NAMESPACE
} /* namespace B64_NAMESPACE */
#endif /* !B64_NO_NAMESPACE */

/* ////////////////////////////////////////////////////////////////////////// */

#endif /* B64_INCL_B64_HPP_B64 */

/* ////////////////////////////////////////////////////////////////////////// */

b64 Library documentation © Synesis Software Pty Ltd, 2004-2007