1 // Copyright (C) 2006  Davis E. King (davis@dlib.net)
2 // License: Boost Software License   See LICENSE.txt for the full license.
3 #undef DLIB_BASE64_KERNEl_ABSTRACT_
4 #ifdef DLIB_BASE64_KERNEl_ABSTRACT_
5 
6 #include "../algs.h"
7 #include <iosfwd>
8 
9 namespace dlib
10 {
11 
12     class base64
13     {
14         /*!
15             INITIAL VALUE
16                 - line_ending() == LF
17 
18             WHAT THIS OBJECT REPRESENTS
19                 This object consists of the two functions encode and decode.
20                 These functions allow you to encode and decode data to and from
21                 the Base64 Content-Transfer-Encoding defined in section 6.8 of
22                 rfc2045.
23         !*/
24 
25     public:
26 
27         class decode_error : public dlib::error {};
28 
29         base64 (
30         );
31         /*!
32             ensures
33                 - #*this is properly initialized
34             throws
35                 - std::bad_alloc
36         !*/
37 
38         virtual ~base64 (
39         );
40         /*!
41             ensures
42                 - all memory associated with *this has been released
43         !*/
44 
45         enum line_ending_type
46         {
47             CR,  // i.e. "\r"
48             LF,  // i.e. "\n"
49             CRLF // i.e. "\r\n"
50         };
51 
52         line_ending_type line_ending (
53         ) const;
54         /*!
55             ensures
56                 - returns the type of end of line bytes the encoder
57                   will use when encoding data to base64 blocks.  Note that
58                   the ostream object you use might apply some sort of transform
59                   to line endings as well.  For example, C++ ofstream objects
60                   usually convert '\n' into whatever a normal newline is for
61                   your platform unless you open a file in binary mode.  But
62                   aside from file streams the ostream objects usually don't
63                   modify the data you pass to them.
64         !*/
65 
66         void set_line_ending (
67             line_ending_type eol_style
68         );
69         /*!
70             ensures
71                 - #line_ending() == eol_style
72         !*/
73 
74         void encode (
75             std::istream& in,
76             std::ostream& out
77         ) const;
78         /*!
79             ensures
80                 - reads all data from in (until EOF is reached) and encodes it
81                   and writes it to out
82             throws
83                 - std::ios_base::failure
84                     if there was a problem writing to out then this exception will
85                     be thrown.
86                 - any other exception
87                     this exception may be thrown if there is any other problem
88         !*/
89 
90         void decode (
91             std::istream& in,
92             std::ostream& out
93         ) const;
94         /*!
95             ensures
96                 - reads data from in (until EOF is reached), decodes it,
97                   and writes it to out.
98             throws
99                 - std::ios_base::failure
100                     if there was a problem writing to out then this exception will
101                     be thrown.
102                 - decode_error
103                     if an error was detected in the encoded data that prevented
104                     it from being correctly decoded then this exception is
105                     thrown.
106                 - any other exception
107                     this exception may be thrown if there is any other problem
108         !*/
109 
110     private:
111 
112         // restricted functions
113         base64(base64&);        // copy constructor
114         base64& operator=(base64&);    // assignment operator
115 
116     };
117 
118 }
119 
120 #endif // DLIB_BASE64_KERNEl_ABSTRACT_
121 
122