interface/wx/base64.h

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