X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/base64.h diff --git a/interface/base64.h b/interface/base64.h index 311023bf68..3967d697b9 100644 --- a/interface/base64.h +++ b/interface/base64.h @@ -1,111 +1,166 @@ ///////////////////////////////////////////////////////////////////////////// - // Name: base64.h - // Purpose: documentation for global functions - // Author: wxWidgets team - // RCS-ID: $Id$ - // Licence: wxWindows license - ///////////////////////////////////////////////////////////////////////////// - - //@{ +// Name: base64.h +// 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 - @e dst set to @NULL -- it will then return the necessary buffer size. - - @param dst - 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. + 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. + @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. + + @return @c wxCONV_FAILED if the output buffer is too small. + + @header{wx/base64.h} */ -size_t wxBase64Encode(char * dst, size_t dstLen, - const void * src, +size_t wxBase64Encode(char* dst, size_t dstLen, + const void* src, size_t srcLen); - wxString wxBase64Encode(const void * src, size_t srcLen); - wxString wxBase64Encode(const wxMemoryBuffer& buf); -//@} +/** + 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. - /** + @header{wx/base64.h} +*/ +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. + + @header{wx/base64.h} +*/ +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. + buffer to be passed to wxBase64Decode(). + + @header{wx/base64.h} */ 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(). + + @header{wx/base64.h} */ 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 @e 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 - necessary buffer size if @e 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. - - @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. - - @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. - - @param mode - 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 - wxBase64DecodeMode_Relaxed, then all invalid characters are skipped. - - @param posErr - If this pointer is non-@NULL and an error occurs during - decoding, it is filled with the index of the invalid character. + 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. + + @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. + @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 @NULL-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 + decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the + 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 decoding, it is + filled with the index of the invalid character. + + @header{wx/base64.h} */ -size_t wxBase64Decode(void * dst, size_t dstLen, - const char * src, +size_t wxBase64Decode(void* dst, size_t dstLen, + const char* src, size_t srcLen = wxNO_LEN, wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, - size_t posErr = @NULL); - wxMemoryBuffer wxBase64Decode(const char * src, - size_t srcLen = wxNO_LEN, - wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, - size_t posErr = @NULL); - wxMemoryBuffer wxBase64Decode(const wxString& src, - wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, - size_t posErr = @NULL); + 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. + + @header{wx/base64.h} +*/ +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. + + @header{wx/base64.h} +*/ +wxMemoryBuffer wxBase64Decode(const wxString& src, + wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, + size_t posErr = NULL); + //@}