]>
Commit | Line | Data |
---|---|---|
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 | /** @addtogroup group_funcmacro_misc */ | |
15 | //@{ | |
16 | ||
17 | /** | |
18 | Elements of this enum specify the possible behaviours of wxBase64Decode | |
19 | when an invalid character is encountered. | |
20 | */ | |
21 | enum 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 | ||
28 | /** | |
29 | This function encodes the given data using base64. | |
30 | ||
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. | |
34 | ||
35 | This raw encoding function overload writes the output string into the | |
36 | provided buffer; the other overloads return it as a wxString. | |
37 | ||
38 | @param dst | |
39 | The output buffer, may be @NULL to retrieve the needed buffer size. | |
40 | @param dstLen | |
41 | The output buffer size, ignored if dst is @NULL. | |
42 | @param src | |
43 | The input buffer, must not be @NULL. | |
44 | @param srcLen | |
45 | The length of the input data. | |
46 | ||
47 | @return @c wxCONV_FAILED if the output buffer is too small. | |
48 | ||
49 | @header{wx/base64.h} | |
50 | */ | |
51 | size_t wxBase64Encode(char* dst, size_t dstLen, | |
52 | const void* src, | |
53 | size_t srcLen); | |
54 | ||
55 | /** | |
56 | This function encodes the given data using base64 and returns the output as | |
57 | a wxString. | |
58 | ||
59 | There is no error return. | |
60 | ||
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. | |
64 | ||
65 | @param src | |
66 | The input buffer, must not be @NULL. | |
67 | @param srcLen | |
68 | The length of the input data. | |
69 | ||
70 | @header{wx/base64.h} | |
71 | */ | |
72 | wxString wxBase64Encode(const void* src, size_t srcLen); | |
73 | ||
74 | /** | |
75 | This function encodes the given data using base64 and returns the output as | |
76 | a wxString. | |
77 | ||
78 | There is no error return. | |
79 | ||
80 | @header{wx/base64.h} | |
81 | */ | |
82 | wxString wxBase64Encode(const wxMemoryBuffer& buf); | |
83 | ||
84 | ||
85 | /** | |
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(). | |
89 | ||
90 | @header{wx/base64.h} | |
91 | */ | |
92 | size_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 | |
97 | to wxBase64Encode(). | |
98 | ||
99 | @header{wx/base64.h} | |
100 | */ | |
101 | size_t wxBase64EncodedSize(size_t len); | |
102 | ||
103 | /** | |
104 | This function decodes a Base64-encoded string. | |
105 | ||
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 | |
109 | wxBase64DecodedSize(srcLen) bytes. Notice that the buffer will @e not be | |
110 | @NULL-terminated. | |
111 | ||
112 | This overload returns the number of bytes written to the buffer or the | |
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 | |
115 | encountered in the input string. | |
116 | ||
117 | @param dst | |
118 | Pointer to output buffer, may be @NULL to just compute the necessary | |
119 | buffer size. | |
120 | @param dstLen | |
121 | The size of the output buffer, ignored if dst is @NULL. | |
122 | @param src | |
123 | The input string, must not be @NULL. For the version using wxString, | |
124 | the input string should contain only ASCII characters. | |
125 | @param srcLen | |
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. | |
129 | @param mode | |
130 | This parameter specifies the function behaviour when invalid characters | |
131 | are encountered in input. By default, any such character stops the | |
132 | decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the | |
133 | white space characters are silently skipped instead. And if it is | |
134 | wxBase64DecodeMode_Relaxed, then all invalid characters are skipped. | |
135 | @param posErr | |
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} | |
140 | */ | |
141 | size_t wxBase64Decode(void* dst, size_t dstLen, | |
142 | const char* src, | |
143 | size_t srcLen = wxNO_LEN, | |
144 | wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, | |
145 | size_t *posErr = NULL); | |
146 | ||
147 | /** | |
148 | Decode a Base64-encoded wxString. | |
149 | ||
150 | See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*) | |
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 | */ | |
159 | size_t wxBase64Decode(void* dst, size_t dstLen, | |
160 | const wxString& str, | |
161 | wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, | |
162 | size_t *posErr = NULL); | |
163 | ||
164 | /** | |
165 | Decode a Base64-encoded string and return decoded contents in a buffer. | |
166 | ||
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. | |
172 | ||
173 | @header{wx/base64.h} | |
174 | */ | |
175 | wxMemoryBuffer wxBase64Decode(const char* src, | |
176 | size_t srcLen = wxNO_LEN, | |
177 | wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, | |
178 | size_t *posErr = NULL); | |
179 | ||
180 | /** | |
181 | Decode a Base64-encoded wxString and return decoded contents in a buffer. | |
182 | ||
183 | See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t*) | |
184 | overload for more information about the parameters of this function. | |
185 | ||
186 | This overload takes as input a wxString and returns the internally-allocated | |
187 | memory as a wxMemoryBuffer, containing the Base64-decoded data. | |
188 | ||
189 | @header{wx/base64.h} | |
190 | */ | |
191 | wxMemoryBuffer wxBase64Decode(const wxString& src, | |
192 | wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, | |
193 | size_t *posErr = NULL); | |
194 | ||
195 | //@} | |
196 |