interface/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 /** @ingroup group_funcmacro_misc */
  15 //@{
  16
  17 /**
  18     This function encodes the given data using base64.
  19
  20     To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
  21     this function with @a dst set to @NULL -- it will then return the necessary
  22     buffer size.
  23
  24     This raw encoding function overload writes the output string into the
  25     provided buffer; the other overloads return it as a wxString.
  26
  27     @param dst
  28         The output buffer, may be @NULL to retrieve the needed buffer size.
  29     @param dstLen
  30         The output buffer size, ignored if dst is @NULL.
  31     @param src
  32         The input buffer, must not be @NULL.
  33     @param srcLen
  34         The length of the input data.
  35
  36     @returns @c wxCONV_FAILED if the output buffer is too small.
  37 */
  38 size_t wxBase64Encode(char* dst, size_t dstLen,
  39                       const void* src,
  40                       size_t srcLen);
  41
  42 /**
  43     This function encodes the given data using base64 and returns the output
  44     as a wxString.
  45
  46     There is no error return.
  47
  48     To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
  49     this function with @a dst set to @NULL -- it will then return the necessary
  50     buffer size.
  51
  52     @param src
  53         The input buffer, must not be @NULL.
  54     @param srcLen
  55         The length of the input data.
  56 */
  57 wxString wxBase64Encode(const void* src, size_t srcLen);
  58
  59 /**
  60     This function encodes the given data using base64 and returns the output
  61     as a wxString.
  62
  63     There is no error return.
  64 */
  65 wxString wxBase64Encode(const wxMemoryBuffer& buf);
  66
  67
  68 /**
  69     Returns the size of the buffer necessary to contain the data encoded in a
  70     base64 string of length @e srcLen. This can be useful for allocating a
  71     buffer to be passed to wxBase64Decode().
  72 */
  73 size_t wxBase64DecodedSize(size_t srcLen);
  74
  75 /**
  76     Returns the length of the string with base64 representation of a buffer of
  77     specified size @e len. This can be useful for allocating the buffer passed
  78     to wxBase64Encode().
  79 */
  80 size_t wxBase64EncodedSize(size_t len);
  81
  82 /**
  83     This function decodes a Base64-encoded string.
  84
  85     This overload is a raw decoding function and decodes the data into the provided
  86     buffer @a dst of the given size @e dstLen. An error is returned if the buffer
  87     is not large enough -- that is not at least wxBase64DecodedSize(srcLen)() bytes.
  88
  89     This overload returns the number of bytes written to the buffer or the
  90     necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on
  91     error, e.g. if the output buffer is too small or invalid characters were
  92     encountered in the input string.
  93
  94     @param dst
  95         Pointer to output buffer, may be @NULL to just compute the
  96         necessary buffer size.
  97     @param dstLen
  98         The size of the output buffer, ignored if dst is @NULL.
  99     @param src
 100         The input string, must not be @NULL. For the version using
 101         wxString, the input string should contain only ASCII characters.
 102     @param srcLen
 103         The length of the input string or special value wxNO_LEN if the string is
 104         NUL-terminated and the length should be computed by this function itself.
 105     @param mode
 106         This parameter specifies the function behaviour when invalid characters
 107         are encountered in input. By default, any such character stops the
 108         decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the
 109         white space characters are silently skipped instead. And if it is
 110         wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
 111     @param posErr
 112         If this pointer is non-@NULL and an error occurs during
 113         decoding, it is filled with the index of the invalid character.
 114 */
 115 size_t wxBase64Decode(void* dst, size_t dstLen,
 116                       const char* src,
 117                       size_t srcLen = wxNO_LEN,
 118                       wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 119                       size_t posErr = NULL);
 120
 121 /**
 122     See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t)
 123     overload for more info about the parameters of this function.
 124
 125     This overload allocates memory internally and returns it as wxMemoryBuffer
 126     and is recommended for normal use.
 127
 128     This overload returns a buffer with the base64 decoded binary equivalent
 129     of the input string. In neither case is the buffer @NULL-terminated.
 130 */
 131 wxMemoryBuffer wxBase64Decode(const char* src,
 132                               size_t srcLen = wxNO_LEN,
 133                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 134                               size_t posErr = NULL);
 135
 136 /**
 137     See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t)
 138     overload for more info about the parameters of this function.
 139
 140     This overload takes as input a wxString and returns the internally-allocated
 141     memory as a wxMemoryBuffer, containing the base64 decoded data.
 142 */
 143 wxMemoryBuffer wxBase64Decode(const wxString& src,
 144                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 145                               size_t posErr = NULL);
 146
 147 //@}
 148