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