base64.h revision df5f1b4303be82a000284349e9392beb9f1b6f11
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * IPRT - Base64, MIME content transfer encoding.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * Copyright (C) 2009 Sun Microsystems, Inc.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * available from http://www.virtualbox.org. This file is free software;
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * you can redistribute it and/or modify it under the terms of the GNU
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * General Public License (GPL) as published by the Free Software
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * The contents of this file may alternatively be used under the terms
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * of the Common Development and Distribution License Version 1.0
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * VirtualBox OSE distribution, in which case the provisions of the
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * CDDL are applicable instead of those of the GPL.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * You may elect to license modified versions of this file under the
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * terms and conditions of either the GPL or the CDDL or both.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
df3d4c8e9c81584c535676a3d40c57d868ac61bbvboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * additional information or have any questions.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync/** @defgroup grp_rt_base64 RTBase64 - Base64, MIME content transfer encoding.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @ingroup grp_rt
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync/** @def RTBASE64_EOL_SIZE
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * The size of the end-of-line marker. */
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * Calculates the decoded data size for a Base64 encoded string.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @returns The length in bytes. -1 if the encoding is bad.
f902ede7eb073d09a81c1d470c089c7b14921714vboxsync * @param pszString The Base64 encoded string.
97674677e4f2aeae576c39f966568dd664ba7979vboxsync * @param ppszEnd If not NULL, this will point to the first char
18673eee0624b4581d3d56ab9ad9d10ebc7f5bddvboxsync * following the Base64 encoded text block. If
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * NULL the entire string is assumed to be Base64.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsyncRTDECL(ssize_t) RTBase64DecodedSize(const char *pszString, char **ppszEnd);
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * Decodes a Base64 encoded string into the buffer supplied by the caller.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @returns IPRT status code.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * be set, nor will ppszEnd.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @param pszString The Base64 string. Whether the entire string or
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * just the start of the string is in Base64 depends
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * on wther ppszEnd is specified or not.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @param pvData Where to store the decoded data.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @param cbData The size of the output buffer that pvData points to.
f6cc81e94c29cc9b39b896cf32ecfe0501b4a1e5vboxsync * @param pcbActual Where to store the actual number of bytes returned.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * Optional.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @param ppszEnd Indicats that the string may contain other stuff
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * after the Base64 encoded data when not NULL. Will
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * be set to point to the first char that's not part of
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * the encoding. If NULL the entire string must be part
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * of the Base64 encoded data.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsyncRTDECL(int) RTBase64Decode(const char *pszString, void *pvData, size_t cbData, size_t *pcbActual, char **ppszEnd);
9ced981a0263f6280ccbf5dc64c0e81fbe4a2fdavboxsync * Calculates the length of the Base64 encoding of a given number of bytes of
f902ede7eb073d09a81c1d470c089c7b14921714vboxsync * This will assume line breaks every 64 chars. A RTBase64EncodedLengthEx
97674677e4f2aeae576c39f966568dd664ba7979vboxsync * function can be added if closer control over the output is found to be
18673eee0624b4581d3d56ab9ad9d10ebc7f5bddvboxsync * required.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @returns The Base64 string length.
f902ede7eb073d09a81c1d470c089c7b14921714vboxsync * @param cbData The number of bytes to encode.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsyncRTDECL(size_t) RTBase64EncodedLength(size_t cbData);
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * Encodes the specifed data into a Base64 string, the caller supplies the
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * output buffer.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * This will make the same assumptions about line breaks and EOL size as
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * RTBase64EncodedLength() does. A RTBase64EncodeEx function can be added if
f6cc81e94c29cc9b39b896cf32ecfe0501b4a1e5vboxsync * more strict control over the output formatting is found necessary.
84bebd094718692856715fb7ed9e592c9421e039vboxsync * @returns IRPT status code.
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
7bff28e0cedd8656acd24b420759649184d8cf00vboxsync * may contain an invalid Base64 string.
RTDECL(int) RTBase64Encode(const void *pvData, size_t cbData, char *pszBuf, size_t cbBuf, size_t *pcchActual);