X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e54c96f187f46c06bd36be8cd52b35c19884aa2b..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/base64.h diff --git a/interface/base64.h b/interface/base64.h index 1aae84304c..3967d697b9 100644 --- a/interface/base64.h +++ b/interface/base64.h @@ -6,38 +6,77 @@ // 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. + + @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 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. + + @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(). + 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(). + + @header{wx/base64.h} */ size_t wxBase64DecodedSize(size_t srcLen); @@ -45,60 +84,83 @@ 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(). + + @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 @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 - 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. + 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. + 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. + 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 @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 + 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 - decoding, it is filled with the index of the invalid character. + 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 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. + + @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); + //@}