interface/wx/base64.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        base64.h
   3 // Purpose:     interface of global functions
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 // ============================================================================
  10 // Global functions/macros
  11 // ============================================================================
  12
  13 /** @addtogroup group_funcmacro_misc */
  14 //@{
  15
  16 /**
  17     Elements of this enum specify the possible behaviours of wxBase64Decode
  18     when an invalid character is encountered.
  19 */
  20 enum wxBase64DecodeMode
  21 {
  22     wxBase64DecodeMode_Strict,  ///< Normal behaviour: stop at any invalid characters.
  23     wxBase64DecodeMode_SkipWS,  ///< Skip whitespace characters.
  24     wxBase64DecodeMode_Relaxed  ///< The most lenient behaviour: simply ignore all invalid characters.
  25 };
  26
  27 /**
  28     This function encodes the given data using base64.
  29
  30     To allocate the buffer of the correct size, use wxBase64EncodedSize() or
  31     call this function with @a dst set to @NULL -- it will then return the
  32     necessary buffer size.
  33
  34     This raw encoding function overload writes the output string into the
  35     provided buffer; the other overloads return it as a wxString.
  36
  37     @param dst
  38         The output buffer, may be @NULL to retrieve the needed buffer size.
  39     @param dstLen
  40         The output buffer size, ignored if dst is @NULL.
  41     @param src
  42         The input buffer, must not be @NULL.
  43     @param srcLen
  44         The length of the input data.
  45
  46     @return @c wxCONV_FAILED if the output buffer is too small.
  47
  48     @header{wx/base64.h}
  49 */
  50 size_t wxBase64Encode(char* dst, size_t dstLen,
  51                       const void* src,
  52                       size_t srcLen);
  53
  54 /**
  55     This function encodes the given data using base64 and returns the output as
  56     a wxString.
  57
  58     There is no error return.
  59
  60     To allocate the buffer of the correct size, use wxBase64EncodedSize() or
  61     call this function with @a dst set to @NULL -- it will then return the
  62     necessary buffer size.
  63
  64     @param src
  65         The input buffer, must not be @NULL.
  66     @param srcLen
  67         The length of the input data.
  68
  69     @header{wx/base64.h}
  70 */
  71 wxString wxBase64Encode(const void* src, size_t srcLen);
  72
  73 /**
  74     This function encodes the given data using base64 and returns the output as
  75     a wxString.
  76
  77     There is no error return.
  78
  79     @header{wx/base64.h}
  80 */
  81 wxString wxBase64Encode(const wxMemoryBuffer& buf);
  82
  83
  84 /**
  85     Returns the size of the buffer necessary to contain the data encoded in a
  86     base64 string of length @e srcLen. This can be useful for allocating a
  87     buffer to be passed to wxBase64Decode().
  88
  89     @header{wx/base64.h}
  90 */
  91 size_t wxBase64DecodedSize(size_t srcLen);
  92
  93 /**
  94     Returns the length of the string with base64 representation of a buffer of
  95     specified size @e len. This can be useful for allocating the buffer passed
  96     to wxBase64Encode().
  97
  98     @header{wx/base64.h}
  99 */
 100 size_t wxBase64EncodedSize(size_t len);
 101
 102 /**
 103     This function decodes a Base64-encoded string.
 104
 105     This overload is a raw decoding function and decodes the data into the
 106     provided buffer @a dst of the given size @e dstLen. An error is returned if
 107     the buffer is not large enough -- that is not at least
 108     wxBase64DecodedSize(srcLen) bytes. Notice that the buffer will @e not be
 109     @NULL-terminated.
 110
 111     This overload returns the number of bytes written to the buffer or the
 112     necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on error,
 113     e.g. if the output buffer is too small or invalid characters were
 114     encountered in the input string.
 115
 116     @param dst
 117         Pointer to output buffer, may be @NULL to just compute the necessary
 118         buffer size.
 119     @param dstLen
 120         The size of the output buffer, ignored if dst is @NULL.
 121     @param src
 122         The input string, must not be @NULL. For the version using wxString,
 123         the input string should contain only ASCII characters.
 124     @param srcLen
 125         The length of the input string or special value wxNO_LEN if the string
 126         is @NULL-terminated and the length should be computed by this function
 127         itself.
 128     @param mode
 129         This parameter specifies the function behaviour when invalid characters
 130         are encountered in input. By default, any such character stops the
 131         decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the
 132         white space characters are silently skipped instead. And if it is
 133         wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
 134     @param posErr
 135         If this pointer is non-@NULL and an error occurs during decoding, it is
 136         filled with the index of the invalid character.
 137
 138     @header{wx/base64.h}
 139 */
 140 size_t wxBase64Decode(void* dst, size_t dstLen,
 141                       const char* src,
 142                       size_t srcLen = wxNO_LEN,
 143                       wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 144                       size_t *posErr = NULL);
 145
 146 /**
 147     Decode a Base64-encoded wxString.
 148
 149     See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*)
 150     overload for more information about the parameters of this function, the
 151     only difference between it and this one is that a wxString is used instead
 152     of a @c char* pointer and its length.
 153
 154     @since 2.9.1
 155
 156     @header{wx/base64.h}
 157  */
 158 size_t wxBase64Decode(void* dst, size_t dstLen,
 159                       const wxString& str,
 160                       wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 161                       size_t *posErr = NULL);
 162
 163 /**
 164     Decode a Base64-encoded string and return decoded contents in a buffer.
 165
 166     See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*)
 167     overload for more information about the parameters of this function. The
 168     difference of this overload is that it allocates a buffer of necessary size
 169     on its own and returns it, freeing you from the need to do it manually.
 170     Because of this, it is simpler to use and is recommended for normal use.
 171
 172     @header{wx/base64.h}
 173 */
 174 wxMemoryBuffer wxBase64Decode(const char* src,
 175                               size_t srcLen = wxNO_LEN,
 176                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 177                               size_t *posErr = NULL);
 178
 179 /**
 180     Decode a Base64-encoded wxString and return decoded contents in a buffer.
 181
 182     See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*)
 183     overload for more information about the parameters of this function.
 184
 185     This overload takes as input a wxString and returns the internally-allocated
 186     memory as a wxMemoryBuffer, containing the Base64-decoded data.
 187
 188     @header{wx/base64.h}
 189 */
 190 wxMemoryBuffer wxBase64Decode(const wxString& src,
 191                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 192                               size_t *posErr = NULL);
 193
 194 //@}
 195