Correctly document the library the classes belong to.

[wxWidgets.git] / interface / wx / base64.h

diff --git a/interface/wx/base64.h b/interface/wx/base64.h
index f59ea7ce8209de27af84ef30b6ee114766465af6..e590aaf9a0bea324d355c8db31958765944aa26d 100644 (file)
--- a/interface/wx/base64.h
+++ b/interface/wx/base64.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of global functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -14,6 +14,17 @@
 /** @addtogroup group_funcmacro_misc */
 //@{
 
+/** 
+    Elements of this enum specify the possible behaviours of wxBase64Decode
+    when an invalid character is encountered.
+*/
+enum wxBase64DecodeMode
+{
+    wxBase64DecodeMode_Strict,  ///< Normal behaviour: stop at any invalid characters.
+    wxBase64DecodeMode_SkipWS,  ///< Skip whitespace characters.
+    wxBase64DecodeMode_Relaxed  ///< The most lenient behaviour: simply ignore all invalid characters.
+};
+
 /**
     This function encodes the given data using base64.
 
@@ -95,7 +106,8 @@ size_t wxBase64EncodedSize(size_t len);
     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.
+    wxBase64DecodedSize(srcLen) bytes. Notice that the buffer will @e not be
+    @NULL-terminated.
 
     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,
@@ -133,14 +145,30 @@ size_t wxBase64Decode(void* dst, size_t dstLen,
                       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.
+    Decode a Base64-encoded wxString.
 
-    This overload allocates memory internally and returns it as wxMemoryBuffer
-    and is recommended for normal use.
+    See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*)
+    overload for more information about the parameters of this function, the
+    only difference between it and this one is that a wxString is used instead
+    of a @c char* pointer and its length.
 
-    This overload returns a buffer with the base64 decoded binary equivalent
-    of the input string. In neither case is the buffer @NULL-terminated.
+    @since 2.9.1
+
+    @header{wx/base64.h}
+ */
+size_t wxBase64Decode(void* dst, size_t dstLen,
+                      const wxString& str,
+                      wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
+                      size_t *posErr = NULL);
+
+/**
+    Decode a Base64-encoded string and return decoded contents in a buffer.
+
+    See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*)
+    overload for more information about the parameters of this function. The
+    difference of this overload is that it allocates a buffer of necessary size
+    on its own and returns it, freeing you from the need to do it manually.
+    Because of this, it is simpler to use and is recommended for normal use.
 
     @header{wx/base64.h}
 */
@@ -150,11 +178,13 @@ wxMemoryBuffer wxBase64Decode(const char* src,
                               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.
+    Decode a Base64-encoded wxString and return decoded contents in a buffer.
+
+    See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*)
+    overload for more information 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.
+    memory as a wxMemoryBuffer, containing the Base64-decoded data.
 
     @header{wx/base64.h}
 */