interface/base64.h

   1 /////////////////////////////////////////////////////////////////////////////
   2     // Name:        base64.h
   3     // Purpose:     documentation for global functions
   4     // Author:      wxWidgets team
   5     // RCS-ID:      $Id$
   6     // Licence:     wxWindows license
   7     /////////////////////////////////////////////////////////////////////////////
   8
   9     //@{
  10 /**
  11     These functions encode the given data using base64. The first of them is the
  12     raw encoding function writing the output string into provided buffer while the
  13     other ones return the output as wxString. There is no error return for these
  14     functions except for the first one which returns @c wxCONV_FAILED if the
  15     output buffer is too small. To allocate the buffer of the correct size, use
  16     wxBase64EncodedSize or call this function with
  17     @e dst set to @NULL -- it will then return the necessary buffer size.
  18
  19     @param dst
  20     The output buffer, may be @NULL to retrieve the needed buffer
  21     size.
  22
  23     @param dstLen
  24     The output buffer size, ignored if dst is @NULL.
  25
  26     @param src
  27     The input buffer, must not be @NULL.
  28
  29     @param srcLen
  30     The length of the input data.
  31 */
  32 size_t wxBase64Encode(char * dst, size_t dstLen,
  33                       const void * src,
  34                       size_t srcLen);
  35     wxString wxBase64Encode(const void * src, size_t srcLen);
  36     wxString wxBase64Encode(const wxMemoryBuffer& buf);
  37 //@}
  38
  39
  40     /**
  41     Returns the size of the buffer necessary to contain the data encoded in a
  42     base64 string of length @e srcLen. This can be useful for allocating a
  43     buffer to be passed to wxBase64Decode.
  44 */
  45 size_t wxBase64DecodedSize(size_t srcLen);
  46
  47 /**
  48     Returns the length of the string with base64 representation of a buffer of
  49     specified size @e len. This can be useful for allocating the buffer passed
  50     to wxBase64Encode.
  51 */
  52 size_t wxBase64EncodedSize(size_t len);
  53
  54 //@{
  55 /**
  56     These function decode a Base64-encoded string. The first version is a raw
  57     decoding function and decodes the data into the provided buffer @e dst of
  58     the given size @e dstLen. An error is returned if the buffer is not large
  59     enough -- that is not at least wxBase64DecodedSize(srcLen)
  60     bytes. The second version allocates memory internally and returns it as
  61     wxMemoryBuffer and is recommended for normal use.
  62
  63     The first version returns the number of bytes written to the buffer or the
  64     necessary buffer size if @e dst was @NULL or @c wxCONV_FAILED on
  65     error, e.g. if the output buffer is too small or invalid characters were
  66     encountered in the input string. The second version returns a buffer with the
  67     base64 decoded binary equivalent of the input string. In neither case is the
  68     buffer NUL-terminated.
  69
  70     @param dst
  71     Pointer to output buffer, may be @NULL to just compute the
  72     necessary buffer size.
  73
  74     @param dstLen
  75     The size of the output buffer, ignored if dst is
  76     @NULL.
  77
  78     @param src
  79     The input string, must not be @NULL. For the version using
  80     wxString, the input string should contain only ASCII characters.
  81
  82     @param srcLen
  83     The length of the input string or special value
  84     wxNO_LEN if the string is NUL-terminated and the length should be
  85     computed by this function itself.
  86
  87     @param mode
  88     This parameter specifies the function behaviour when invalid
  89     characters are encountered in input. By default, any such character stops the
  90     decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the white
  91     space characters are silently skipped instead. And if it is
  92     wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
  93
  94     @param posErr
  95     If this pointer is non-@NULL and an error occurs during
  96     decoding, it is filled with the index of the invalid character.
  97 */
  98 size_t wxBase64Decode(void * dst, size_t dstLen,
  99                       const char * src,
 100                       size_t srcLen = wxNO_LEN,
 101                       wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 102                       size_t posErr = @NULL);
 103     wxMemoryBuffer wxBase64Decode(const char * src,
 104                                   size_t srcLen = wxNO_LEN,
 105                                   wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 106                                   size_t posErr = @NULL);
 107     wxMemoryBuffer wxBase64Decode(const wxString& src,
 108                                   wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 109                                   size_t posErr = @NULL);
 110 //@}
 111