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