/////////////////////////////////////////////////////////////////////////////
// Name: base64.h
-// Purpose: documentation for global functions
+// Purpose: interface of global functions
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @ingroup group_funcmacro_misc */
//@{
+
/**
- These functions encode the given data using base64. The first of them is the
- raw encoding function writing the output string into provided buffer while the
- other ones return the output as wxString. There is no error return for these
- functions except for the first one which returns @c wxCONV_FAILED if the
- output buffer is too small. To allocate the buffer of the correct size, use
- wxBase64EncodedSize or call this function with
- @a dst set to @NULL -- it will then return the necessary buffer size.
+ This function encodes the given data using base64.
+
+ To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
+ this function with @a dst set to @NULL -- it will then return the necessary
+ buffer size.
+
+ This raw encoding function overload writes the output string into the
+ provided buffer; the other overloads return it as a wxString.
@param dst
- The output buffer, may be @NULL to retrieve the needed buffer
- size.
+ The output buffer, may be @NULL to retrieve the needed buffer size.
@param dstLen
The output buffer size, ignored if dst is @NULL.
@param src
The input buffer, must not be @NULL.
@param srcLen
The length of the input data.
+
+ @returns @c wxCONV_FAILED if the output buffer is too small.
*/
size_t wxBase64Encode(char* dst, size_t dstLen,
const void* src,
size_t srcLen);
+
+/**
+ This function encodes the given data using base64 and returns the output
+ as a wxString.
+
+ There is no error return.
+
+ To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
+ this function with @a dst set to @NULL -- it will then return the necessary
+ buffer size.
+
+ @param src
+ The input buffer, must not be @NULL.
+ @param srcLen
+ The length of the input data.
+*/
wxString wxBase64Encode(const void* src, size_t srcLen);
+
+/**
+ This function encodes the given data using base64 and returns the output
+ as a wxString.
+
+ There is no error return.
+*/
wxString wxBase64Encode(const wxMemoryBuffer& buf);
-//@}
/**
-Returns the size of the buffer necessary to contain the data encoded in a
-base64 string of length @e srcLen. This can be useful for allocating a
-buffer to be passed to wxBase64Decode.
+ Returns the size of the buffer necessary to contain the data encoded in a
+ base64 string of length @e srcLen. This can be useful for allocating a
+ buffer to be passed to wxBase64Decode().
*/
size_t wxBase64DecodedSize(size_t srcLen);
/**
Returns the length of the string with base64 representation of a buffer of
specified size @e len. This can be useful for allocating the buffer passed
- to wxBase64Encode.
+ to wxBase64Encode().
*/
size_t wxBase64EncodedSize(size_t len);
-//@{
/**
- These function decode a Base64-encoded string. The first version is a raw
- decoding function and decodes the data into the provided buffer @a dst of
- the given size @e dstLen. An error is returned if the buffer is not large
- enough -- that is not at least wxBase64DecodedSize(srcLen)
- bytes. The second version allocates memory internally and returns it as
- wxMemoryBuffer and is recommended for normal use.
- The first version returns the number of bytes written to the buffer or the
+ This function decodes a Base64-encoded string.
+
+ This overload is a raw decoding function and decodes the data into the provided
+ buffer @a dst of the given size @e dstLen. An error is returned if the buffer
+ is not large enough -- that is not at least wxBase64DecodedSize(srcLen)() bytes.
+
+ This overload returns the number of bytes written to the buffer or the
necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on
error, e.g. if the output buffer is too small or invalid characters were
- encountered in the input string. The second version returns a buffer with the
- base64 decoded binary equivalent of the input string. In neither case is the
- buffer NUL-terminated.
+ encountered in the input string.
@param dst
Pointer to output buffer, may be @NULL to just compute the
necessary buffer size.
@param dstLen
- The size of the output buffer, ignored if dst is
- @NULL.
+ The size of the output buffer, ignored if dst is @NULL.
@param src
The input string, must not be @NULL. For the version using
wxString, the input string should contain only ASCII characters.
@param srcLen
- The length of the input string or special value
- wxNO_LEN if the string is NUL-terminated and the length should be
- computed by this function itself.
+ The length of the input string or special value wxNO_LEN if the string is
+ NUL-terminated and the length should be computed by this function itself.
@param mode
- This parameter specifies the function behaviour when invalid
- characters are encountered in input. By default, any such character stops
- the
+ This parameter specifies the function behaviour when invalid characters
+ are encountered in input. By default, any such character stops the
decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the
- white
- space characters are silently skipped instead. And if it is
+ white space characters are silently skipped instead. And if it is
wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
@param posErr
If this pointer is non-@NULL and an error occurs during
size_t srcLen = wxNO_LEN,
wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
size_t posErr = NULL);
+
+/**
+ See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t)
+ overload for more info about the parameters of this function.
+
+ This overload allocates memory internally and returns it as wxMemoryBuffer
+ and is recommended for normal use.
+
+ This overload returns a buffer with the base64 decoded binary equivalent
+ of the input string. In neither case is the buffer @NULL-terminated.
+*/
wxMemoryBuffer wxBase64Decode(const char* src,
size_t srcLen = wxNO_LEN,
wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
size_t posErr = NULL);
+
+/**
+ See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t)
+ overload for more info about the parameters of this function.
+
+ This overload takes as input a wxString and returns the internally-allocated
+ memory as a wxMemoryBuffer, containing the base64 decoded data.
+*/
wxMemoryBuffer wxBase64Decode(const wxString& src,
wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
size_t posErr = NULL);
+
//@}
projects / wxWidgets.git / blobdiff