Point Cloud Library (PCL) 1.12.1
opennurbs_base64.h
1/* $NoKeywords: $ */
2/*
3//
4// Copyright (c) 1993-2012 Robert McNeel & Associates. All rights reserved.
5// OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert
6// McNeel & Associates.
7//
8// THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
9// ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF
10// MERCHANTABILITY ARE HEREBY DISCLAIMED.
11//
12// For complete openNURBS copyright information see <http://www.opennurbs.org>.
13//
14////////////////////////////////////////////////////////////////
15*/
16
17#if !defined(OPENNURBS_BASE64_INC_)
18#define OPENNURBS_BASE64_INC_
19
20//////////////////////////////////////////////////////////////////////////////////////////
21
23{
24public:
27
28 /*
29 Description:
30 ON_Base64EncodeStream delivers the base64 encoded stream by
31 calling a base64 encoded stream output handler function.
32 There are two options for specifying the base64 encoded stream
33 output handler function.
34 1. Overriding the virtual Out() function.
35 2. Providing a callback function.
36 SetCallback() is used to specify a callback function to handle
37 the base64 encoded stream and to specify a context pointer to be
38 passed to either option of the handler.
39 Parameters:
40 callback_function - [in]
41 Function to handle sections of the base64 encoded stream.
42 If callback_function is null, then the virtual Out()
43 function will be called. When callback_function
44 is specified, it must return true if the base64 encoding
45 calculation should continue and false to cancel the
46 base64 encoding calculation.
47 callback_context - [in]
48 This value is passed as the first argument when calling
49 callback_function or the virutal Out() function.
50 Returns:
51 True if successful.
52 Remarks:
53 Once base64 encoding has started, it would be unusual to
54 intentionally change the base64 encoded stream output handler,
55 but you can do this if you need to.
56 */
58 ON_StreamCallbackFunction callback_function,
59 void* callback_context
60 );
61
62 /*
63 Returns:
64 Current value of the callback function for handling
65 the base64 encoded stream. If the callback function is
66 null, the the virtual Out() function is used to
67 handle the output stream.
68 */
69 ON_StreamCallbackFunction CallbackFunction() const;
70
71 /*
72 Returns:
73 Current value of the context pointer passed as the first
74 argument to the base64 encoded stream output handler function.
75 */
76 void* CallbackContext() const;
77
78 /*
79 Description:
80 Call Begin() one time to initialize the base64 encoding
81 calculation. Then call In() one or more times
82 to submit the unencoded stream to the base64 encoding
83 calculation. When you reach the end of the unencoded
84 stream, call End().
85 Returns:
86 true if successful, false if an error occured.
87 */
88 bool Begin();
89
90
91 /*
92 Description:
93 Call In() one or more times to base64 encode a stream of bytes.
94 After the last call to In(), call End(). Calling In() will
95 result in at least in_buffer_size/57 and at most
96 (in_buffer_size+56)/57 calls to to the output stream handler.
97 Parameters:
98 in_buffer_size - [in]
99 number of bytes in in_buffer
100 in_buffer - [in]
101 Returns:
102 true if successful, false if an error occured.
103 */
104 bool In(
105 ON__UINT64 in_buffer_size,
106 const void* in_buffer
107 );
108
109 /*
110 Description:
111 If an explicit base 64 encoded stream output handler is not
112 specified ( CallbackFunction() returns null ), then the
113 virtual Out() function is called to handle the base 64 encoded
114 output stream. As the input stream is encoded, one or more
115 calls to Out() will occur.
116
117 With a possible exception of the last call to Out(), when Out()
118 is called, 57 input bytes have been encoded into 76 output
119 characters with ASCII codes A-Z, a-z, 0-9, +, /.
120 Parameters:
121 callback_context - [in]
122 context pointer set by calling SetCallback(). Typically
123 the context pointer is not used by a virtual override
124 because the context can be added as member variables
125 of the derived class, but it is available if needed.
126 out_buffer_size - [in]
127 number of non-null characters in out_buffer.
128 out_buffer - [in]
129 A null terminated ASCII string that is a base 64 encoding.
130 out_buffer[0...(out_buffer_size-1)] are ASCII characters with
131 values characters with ASCII codes A-Z, a-z, 0-9, +, /
132 and out_buffer[out_buffer_size] = 0.
133 Returns:
134 True to continue base 64 encodeing and false to cancel the
135 encoding calculation.
136 */
137 virtual bool Out(
138 void* callback_context,
139 ON__UINT32 out_buffer_size,
140 const char* out_buffer
141 );
142
143 /*
144 Description:
145 After the last call to In(), call End(). Calling End() may
146 generate one call to the output stream handler with the value
147 of out_buffer_size = 4 to 76.
148 Returns:
149 true if successful, false if an error occured.
150 */
151 bool End();
152
153 /*
154 Returns:
155 Then the returned value is the total number bytes in the input
156 stream. The size is updated every time In() is called before
157 any calls are made to the output stream handler. If the
158 calculation is finished ( End() has been called ), then the
159 returned value is the total number of bytes in the entire
160 input stream.
161 */
162 ON__UINT64 InSize() const;
163
164 /*
165 Returns:
166 Then the returned value is the total number characters in the
167 output stream. The size is incremented immediately after each
168 call to the output stream handler. If the base64 encoding
169 calculation is finished ( End() has been called ), then the
170 returned value is the total number of bytes in the entire
171 output stream.
172 */
173 ON__UINT64 OutSize() const;
174
175 /*
176 Returns:
177 Then the returned value is the 32-bit crc of the input stream.
178 The crc is updated every time In() is called before any calls
179 are made to the output stream handler. If the base64 encoding
180 calculation is finished ( End() has been called ), then the
181 returned value is the 32-bit crc of the entire input stream.
182 */
183 ON__UINT32 InCRC() const;
184
185 /*
186 Returns:
187 Then the returned value is the 32bit crc of the output stream.
188 The crc is updated immediately after each call to the output
189 stream handler. If the calculation is finished ( End() has
190 been called ), then the returned value is the 32-bit crc of
191 the entire output stream.
192 */
193 ON__UINT32 OutCRC() const;
194
195private:
196 ON_StreamCallbackFunction m_out_callback_function;
197 void* m_out_callback_context;
198 ON__UINT64 m_in_size;
199 ON__UINT64 m_out_size;
200 ON__UINT32 m_in_crc;
201 ON__UINT32 m_out_crc;
202 void* m_implementation;
203 void* m_reserved;
204
205 void ErrorHandler();
206
207private:
208 // prohibit use - no implementation
211};
212
213//////////////////////////////////////////////////////////////////////////////////////////
214
215class ON_CLASS ON_DecodeBase64
216{
217public:
220
221 void Begin();
222
223 // Decode will generate zero or more callbacks to the
224 // virtual Output() function. If the base 64 encoded information
225 // is in pieces, you can call Decode() for each piece. For example,
226 // if your encoded information is in a text file, you might call
227 // Decode() for every line in the file. Decode() returns 0 if
228 // there is nothing in base64str to decode or if it detects an
229 // error that prevents any further decoding. The function Error()
230 // can be used to determine if an error occured. Otherwise,
231 // Decode() returns a pointer to the location in the string where
232 // it stopped decoding because it detected a character, like a null
233 // terminator, an end of line character, or any other character
234 // that could not be part of the base 64 encoded information.
235 const char* Decode(const char* base64str);
236 const char* Decode(const char* base64str, std::size_t base64str_count);
237 const wchar_t* Decode(const wchar_t* base64str);
238 const wchar_t* Decode(const wchar_t* base64str, std::size_t base64str_count);
239
240 // You must call End() when Decode() returns 0 or when you have
241 // reached the end of your encoded information. End() may
242 // callback to Output() zero or one time. If all the information
243 // passed to Decode() was successfully decoded, then End()
244 // returns true. If something was not decoded, then End()
245 // returns false.
246 bool End();
247
248 // Override the virtual Output() callback function to process the
249 // decoded output. Each time Output() is called there are m_output_count
250 // bytes in the m_output[] array.
251 // Every call to Decode() can result in zero, one, or many callbacks
252 // to Output(). Calling End() may result in zero or one callbacks
253 // to Output().
254 virtual void Output();
255
256 // m_decode_count = total number of input base64 characters
257 // that Decode() has decoded.
258 unsigned int m_decode_count;
259
260 int m_output_count; // 0 to 512
261 unsigned char m_output[512];
262
263 // Call if your Output() function detects an error and
264 // wants to stop further decoding.
265 void SetError();
266
267 // Returns true if an error occured during decoding because
268 // invalid input was passed to Decode().
269 bool Error() const;
270
271private:
272 int m_status; // 1: error - decoding stopped
273 // 2: '=' encountered as 3rd char in Decode()
274 // 3: successfully parsed "**=="
275 // 4: successfully parsed "***="
276 // 5: End() successfully called.
277
278 // cached encoded input from previous call to Decode()
279 int m_cache_count;
280 int m_cache[4];
281
282 void DecodeHelper1(); // decodes "**==" quartet into 1 byte
283 void DecodeHelper2(); // decodes "***=" quartet into 2 bytes
284};
285
286
287/////////////////////////////////////////////////////////////////////
288
289
290/*
291class ON_CLASS ON_EncodeBase64
292{
293public:
294 ON_EncodeBase64();
295 virtual ~ON_EncodeBase64();
296
297 void Begin();
298
299 // Calling Encode will generate at least
300 // sizeof_buffer/57 and at most (sizeof_buffer+56)/57
301 // calls to Output(). Every callback to Output() will
302 // have m_output_count = 76.
303 void Encode(const void* buffer, std::size_t sizeof_buffer);
304
305 // Calling End may generate a single call to Output()
306 // If it does generate a single call to Output(),
307 // then m_output_count will be between 1 and 76.
308 void End(); // may generate a single call to Output().
309
310 // With a single exception, when Output() is called,
311 // 57 input bytes have been encoded into 76 output
312 // characters with ASCII codes A-Z, a-z, 0-9, +, /.
313 // m_output_count will be 76
314 // m_output[0...(m_output_count-1)] will be the base 64
315 // encoding.
316 // m_output[m_output_count] = 0.
317 // The Output() function can modify the values of m_output[]
318 // and m_output_count anyway it wants.
319 virtual void Output();
320
321 // Total number of bytes passed to Encode().
322 int m_encode_count;
323
324 // When the virtual Output() is called, there are m_output_count (1 to 76)
325 // characters of base64 encoded output in m_output[]. The remainder of
326 // the m_output[] array is zero. The Output function may modify the
327 // contents of m_output[] any way it sees fit.
328 int m_output_count;
329 char m_output[80];
330
331private:
332 // input waiting to be encoded
333 // At most 56 bytes can be waiting to be processed in m_input[].
334 unsigned int m_unused2; // Here for alignment purposes. Never used by opennurbs.
335 unsigned int m_input_count;
336 unsigned char m_input[64];
337
338 void EncodeHelper1(const unsigned char*, char*);
339 void EncodeHelper2(const unsigned char*, char*);
340 void EncodeHelper3(const unsigned char*, char*);
341 void EncodeHelper57(const unsigned char*);
342};
343*/
344
345#endif
bool SetCallback(ON_StreamCallbackFunction callback_function, void *callback_context)
ON__UINT32 InCRC() const
void * CallbackContext() const
virtual ~ON_Base64EncodeStream()
ON__UINT64 OutSize() const
ON__UINT32 OutCRC() const
ON__UINT64 InSize() const
bool In(ON__UINT64 in_buffer_size, const void *in_buffer)
virtual bool Out(void *callback_context, ON__UINT32 out_buffer_size, const char *out_buffer)
ON_StreamCallbackFunction CallbackFunction() const
virtual ~ON_DecodeBase64()
const wchar_t * Decode(const wchar_t *base64str, std::size_t base64str_count)
const char * Decode(const char *base64str, std::size_t base64str_count)
bool Error() const
unsigned int m_decode_count
const char * Decode(const char *base64str)
const wchar_t * Decode(const wchar_t *base64str)
virtual void Output()