]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/base64.h
Post size events to the event handler and not window itself.
[wxWidgets.git] / interface / wx / base64.h
CommitLineData
23324ae1 1/////////////////////////////////////////////////////////////////////////////
7c913512 2// Name: base64.h
e54c96f1 3// Purpose: interface of global functions
7c913512
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
7c913512
FM
7/////////////////////////////////////////////////////////////////////////////
8
698d17c3
FM
9
10// ============================================================================
11// Global functions/macros
12// ============================================================================
13
b21126db 14/** @addtogroup group_funcmacro_misc */
7c913512 15//@{
698d17c3 16
7aa3b31d
VZ
17/**
18 Elements of this enum specify the possible behaviours of wxBase64Decode
19 when an invalid character is encountered.
20*/
21enum wxBase64DecodeMode
22{
23 wxBase64DecodeMode_Strict, ///< Normal behaviour: stop at any invalid characters.
24 wxBase64DecodeMode_SkipWS, ///< Skip whitespace characters.
25 wxBase64DecodeMode_Relaxed ///< The most lenient behaviour: simply ignore all invalid characters.
26};
27
23324ae1 28/**
698d17c3
FM
29 This function encodes the given data using base64.
30
7fa7088e
BP
31 To allocate the buffer of the correct size, use wxBase64EncodedSize() or
32 call this function with @a dst set to @NULL -- it will then return the
33 necessary buffer size.
698d17c3
FM
34
35 This raw encoding function overload writes the output string into the
36 provided buffer; the other overloads return it as a wxString.
7c913512
FM
37
38 @param dst
698d17c3 39 The output buffer, may be @NULL to retrieve the needed buffer size.
7c913512 40 @param dstLen
4cc4bfaf 41 The output buffer size, ignored if dst is @NULL.
7c913512 42 @param src
4cc4bfaf 43 The input buffer, must not be @NULL.
7c913512 44 @param srcLen
4cc4bfaf 45 The length of the input data.
698d17c3 46
d29a9a8a 47 @return @c wxCONV_FAILED if the output buffer is too small.
7fa7088e
BP
48
49 @header{wx/base64.h}
23324ae1 50*/
4cc4bfaf
FM
51size_t wxBase64Encode(char* dst, size_t dstLen,
52 const void* src,
23324ae1 53 size_t srcLen);
698d17c3
FM
54
55/**
7fa7088e
BP
56 This function encodes the given data using base64 and returns the output as
57 a wxString.
698d17c3
FM
58
59 There is no error return.
60
7fa7088e
BP
61 To allocate the buffer of the correct size, use wxBase64EncodedSize() or
62 call this function with @a dst set to @NULL -- it will then return the
63 necessary buffer size.
698d17c3
FM
64
65 @param src
66 The input buffer, must not be @NULL.
67 @param srcLen
68 The length of the input data.
7fa7088e
BP
69
70 @header{wx/base64.h}
698d17c3 71*/
4cc4bfaf 72wxString wxBase64Encode(const void* src, size_t srcLen);
698d17c3
FM
73
74/**
7fa7088e
BP
75 This function encodes the given data using base64 and returns the output as
76 a wxString.
698d17c3
FM
77
78 There is no error return.
7fa7088e
BP
79
80 @header{wx/base64.h}
698d17c3 81*/
7c913512 82wxString wxBase64Encode(const wxMemoryBuffer& buf);
23324ae1
FM
83
84
7c913512 85/**
698d17c3
FM
86 Returns the size of the buffer necessary to contain the data encoded in a
87 base64 string of length @e srcLen. This can be useful for allocating a
88 buffer to be passed to wxBase64Decode().
7fa7088e
BP
89
90 @header{wx/base64.h}
23324ae1
FM
91*/
92size_t wxBase64DecodedSize(size_t srcLen);
93
94/**
95 Returns the length of the string with base64 representation of a buffer of
96 specified size @e len. This can be useful for allocating the buffer passed
e54c96f1 97 to wxBase64Encode().
7fa7088e
BP
98
99 @header{wx/base64.h}
23324ae1
FM
100*/
101size_t wxBase64EncodedSize(size_t len);
102
23324ae1 103/**
698d17c3
FM
104 This function decodes a Base64-encoded string.
105
7fa7088e
BP
106 This overload is a raw decoding function and decodes the data into the
107 provided buffer @a dst of the given size @e dstLen. An error is returned if
108 the buffer is not large enough -- that is not at least
07890fbe
VZ
109 wxBase64DecodedSize(srcLen) bytes. Notice that the buffer will @e not be
110 @NULL-terminated.
698d17c3
FM
111
112 This overload returns the number of bytes written to the buffer or the
7fa7088e
BP
113 necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on error,
114 e.g. if the output buffer is too small or invalid characters were
698d17c3 115 encountered in the input string.
7c913512
FM
116
117 @param dst
7fa7088e
BP
118 Pointer to output buffer, may be @NULL to just compute the necessary
119 buffer size.
7c913512 120 @param dstLen
698d17c3 121 The size of the output buffer, ignored if dst is @NULL.
7c913512 122 @param src
7fa7088e
BP
123 The input string, must not be @NULL. For the version using wxString,
124 the input string should contain only ASCII characters.
7c913512 125 @param srcLen
7fa7088e
BP
126 The length of the input string or special value wxNO_LEN if the string
127 is @NULL-terminated and the length should be computed by this function
128 itself.
7c913512 129 @param mode
3c4f71cc 130 This parameter specifies the function behaviour when invalid characters
698d17c3 131 are encountered in input. By default, any such character stops the
4cc4bfaf 132 decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the
698d17c3 133 white space characters are silently skipped instead. And if it is
4cc4bfaf 134 wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
7c913512 135 @param posErr
7fa7088e
BP
136 If this pointer is non-@NULL and an error occurs during decoding, it is
137 filled with the index of the invalid character.
138
139 @header{wx/base64.h}
23324ae1 140*/
4cc4bfaf
FM
141size_t wxBase64Decode(void* dst, size_t dstLen,
142 const char* src,
23324ae1
FM
143 size_t srcLen = wxNO_LEN,
144 wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
77782a5c 145 size_t *posErr = NULL);
698d17c3
FM
146
147/**
869bc90d
VZ
148 Decode a Base64-encoded wxString.
149
7aa3b31d 150 See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*)
869bc90d
VZ
151 overload for more information about the parameters of this function, the
152 only difference between it and this one is that a wxString is used instead
153 of a @c char* pointer and its length.
154
155 @since 2.9.1
156
157 @header{wx/base64.h}
158 */
159size_t wxBase64Decode(void* dst, size_t dstLen,
160 const wxString& str,
161 wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
162 size_t *posErr = NULL);
698d17c3 163
869bc90d
VZ
164/**
165 Decode a Base64-encoded string and return decoded contents in a buffer.
698d17c3 166
869bc90d
VZ
167 See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*)
168 overload for more information about the parameters of this function. The
169 difference of this overload is that it allocates a buffer of necessary size
170 on its own and returns it, freeing you from the need to do it manually.
171 Because of this, it is simpler to use and is recommended for normal use.
7fa7088e
BP
172
173 @header{wx/base64.h}
698d17c3 174*/
4cc4bfaf 175wxMemoryBuffer wxBase64Decode(const char* src,
7c913512
FM
176 size_t srcLen = wxNO_LEN,
177 wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
77782a5c 178 size_t *posErr = NULL);
698d17c3
FM
179
180/**
869bc90d
VZ
181 Decode a Base64-encoded wxString and return decoded contents in a buffer.
182
7aa3b31d 183 See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*)
869bc90d 184 overload for more information about the parameters of this function.
698d17c3
FM
185
186 This overload takes as input a wxString and returns the internally-allocated
869bc90d 187 memory as a wxMemoryBuffer, containing the Base64-decoded data.
7fa7088e
BP
188
189 @header{wx/base64.h}
698d17c3 190*/
7c913512
FM
191wxMemoryBuffer wxBase64Decode(const wxString& src,
192 wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
77782a5c 193 size_t *posErr = NULL);
698d17c3 194
23324ae1
FM
195//@}
196