include/wx/base64.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/base64.h
   3 // Purpose:     declaration of BASE64 encoding/decoding functionality
   4 // Author:      Charles Reimers, Vadim Zeitlin
   5 // Created:     2007-06-18
   6 // Licence:     wxWindows licence
   7 ///////////////////////////////////////////////////////////////////////////////
   8
   9 #ifndef _WX_BASE64_H_
  10 #define _WX_BASE64_H_
  11
  12 #if wxUSE_BASE64
  13
  14 #include "wx/string.h"
  15 #include "wx/buffer.h"
  16
  17 // ----------------------------------------------------------------------------
  18 // encoding functions
  19 // ----------------------------------------------------------------------------
  20
  21 // return the size needed for the buffer containing the encoded representation
  22 // of a buffer of given length
  23 inline size_t wxBase64EncodedSize(size_t len) { return 4*((len+2)/3); }
  24
  25 // raw base64 encoding function which encodes the contents of a buffer of the
  26 // specified length into the buffer of the specified size
  27 //
  28 // returns the length of the encoded data or wxCONV_FAILED if the buffer is not
  29 // large enough; to determine the needed size you can either allocate a buffer
  30 // of wxBase64EncodedSize(srcLen) size or call the function with NULL buffer in
  31 // which case the required size will be returned
  32 WXDLLIMPEXP_BASE size_t
  33 wxBase64Encode(char *dst, size_t dstLen, const void *src, size_t srcLen);
  34
  35 // encode the contents of the given buffer using base64 and return as string
  36 // (there is no error return)
  37 inline wxString wxBase64Encode(const void *src, size_t srcLen)
  38 {
  39     const size_t dstLen = wxBase64EncodedSize(srcLen);
  40     wxCharBuffer dst(dstLen);
  41     wxBase64Encode(dst.data(), dstLen, src, srcLen);
  42
  43     return dst;
  44 }
  45
  46 inline wxString wxBase64Encode(const wxMemoryBuffer& buf)
  47 {
  48     return wxBase64Encode(buf.GetData(), buf.GetDataLen());
  49 }
  50
  51 // ----------------------------------------------------------------------------
  52 // decoding functions
  53 // ----------------------------------------------------------------------------
  54
  55 // elements of this enum specify the possible behaviours of wxBase64Decode()
  56 // when an invalid character is encountered
  57 enum wxBase64DecodeMode
  58 {
  59     // normal behaviour: stop at any invalid characters
  60     wxBase64DecodeMode_Strict,
  61
  62     // skip whitespace characters
  63     wxBase64DecodeMode_SkipWS,
  64
  65     // the most lenient behaviour: simply ignore all invalid characters
  66     wxBase64DecodeMode_Relaxed
  67 };
  68
  69 // return the buffer size necessary for decoding a base64 string of the given
  70 // length
  71 inline size_t wxBase64DecodedSize(size_t srcLen) { return 3*srcLen/4; }
  72
  73 // raw decoding function which decodes the contents of the string of specified
  74 // length (or NUL-terminated by default) into the provided buffer of the given
  75 // size
  76 //
  77 // the function normally stops at any character invalid inside a base64-encoded
  78 // string (i.e. not alphanumeric nor '+' nor '/') but can be made to skip the
  79 // whitespace or all invalid characters using its mode argument
  80 //
  81 // returns the length of the decoded data or wxCONV_FAILED if an error occurs
  82 // such as the buffer is too small or the encoded string is invalid; in the
  83 // latter case the posErr is filled with the position where the decoding
  84 // stopped if it is not NULL
  85 WXDLLIMPEXP_BASE size_t
  86 wxBase64Decode(void *dst, size_t dstLen,
  87                const char *src, size_t srcLen = wxNO_LEN,
  88                wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
  89                size_t *posErr = NULL);
  90
  91 inline size_t
  92 wxBase64Decode(void *dst, size_t dstLen,
  93                const wxString& src,
  94                wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
  95                size_t *posErr = NULL)
  96 {
  97     // don't use str.length() here as the ASCII buffer is shorter than it for
  98     // strings with embedded NULs
  99     return wxBase64Decode(dst, dstLen, src.ToAscii(), wxNO_LEN, mode, posErr);
 100 }
 101
 102 // decode the contents of the given string; the returned buffer is empty if an
 103 // error occurs during decoding
 104 WXDLLIMPEXP_BASE wxMemoryBuffer
 105 wxBase64Decode(const char *src, size_t srcLen = wxNO_LEN,
 106                wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 107                size_t *posErr = NULL);
 108
 109 inline wxMemoryBuffer
 110 wxBase64Decode(const wxString& src,
 111                wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 112                size_t *posErr = NULL)
 113 {
 114     // don't use str.length() here as the ASCII buffer is shorter than it for
 115     // strings with embedded NULs
 116     return wxBase64Decode(src.ToAscii(), wxNO_LEN, mode, posErr);
 117 }
 118
 119 #endif // wxUSE_BASE64
 120
 121 #endif // _WX_BASE64_H_