| 1 |
b64: Base64 Encoding/Decoding Routines |
| 2 |
====================================== |
| 3 |
|
| 4 |
Overview: |
| 5 |
-------- |
| 6 |
libb64 is a library of ANSI C routines for fast encoding/decoding data into and |
| 7 |
from a base64-encoded format. C++ wrappers are included, as well as the source |
| 8 |
code for standalone encoding and decoding executables. |
| 9 |
|
| 10 |
base64 consists of ASCII text, and is therefore a useful encoding for storing |
| 11 |
binary data in a text file, such as xml, or sending binary data over text-only |
| 12 |
email. |
| 13 |
|
| 14 |
References: |
| 15 |
---------- |
| 16 |
* Wikipedia article: |
| 17 |
http://en.wikipedia.org/wiki/Base64 |
| 18 |
* base64, another implementation of a commandline en/decoder: |
| 19 |
http://www.fourmilab.ch/webtools/base64/ |
| 20 |
|
| 21 |
Why? |
| 22 |
--- |
| 23 |
I did this because I need an implementation of base64 encoding and decoding, |
| 24 |
without any licensing problems. Most OS implementations are released under |
| 25 |
either the GNU/GPL, or a BSD-variant, which is not what I require. |
| 26 |
|
| 27 |
Also, the chance to actually use the co-routine implementation in code is rare, |
| 28 |
and its use here is fitting. I couldn't pass up the chance. |
| 29 |
For more information on this technique, see "Coroutines in C", by Simon Tatham, |
| 30 |
which can be found online here: |
| 31 |
http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html |
| 32 |
|
| 33 |
So then, under which license do I release this code? On to the next section... |
| 34 |
|
| 35 |
License: |
| 36 |
------- |
| 37 |
This work is released under into the Public Domain. |
| 38 |
It basically boils down to this: I put this work in the public domain, and you |
| 39 |
can take it and do whatever you want with it. |
| 40 |
|
| 41 |
An example of this "license" is the Creative Commons Public Domain License, a |
| 42 |
copy of which can be found in the LICENSE file, and also online at |
| 43 |
http://creativecommons.org/licenses/publicdomain/ |
| 44 |
|
| 45 |
Commandline Use: |
| 46 |
--------------- |
| 47 |
There is a new executable available, it is simply called base64. |
| 48 |
It can encode and decode files, as instructed by the user. |
| 49 |
|
| 50 |
To encode a file: |
| 51 |
$ ./base64 -e filea fileb |
| 52 |
fileb will now be the base64-encoded version of filea. |
| 53 |
|
| 54 |
To decode a file: |
| 55 |
$ ./base64 -d fileb filec |
| 56 |
filec will now be identical to filea. |
| 57 |
|
| 58 |
Programming: |
| 59 |
----------- |
| 60 |
Some C++ wrappers are provided as well, so you don't have to get your hands |
| 61 |
dirty. Encoding from standard input to standard output is as simple as |
| 62 |
|
| 63 |
#include <b64/encode.h> |
| 64 |
#include <iostream> |
| 65 |
int main() |
| 66 |
{ |
| 67 |
base64::encoder E; |
| 68 |
E.encode(std::cin, std::cout); |
| 69 |
return 0; |
| 70 |
} |
| 71 |
|
| 72 |
Both standalone executables and a static library is provided in the package, |
| 73 |
|
| 74 |
Implementation: |
| 75 |
-------------- |
| 76 |
It is DAMN fast, if I may say so myself. The C code uses a little trick which |
| 77 |
has been used to implement coroutines, of which one can say that this |
| 78 |
implementation is an example. |
| 79 |
|
| 80 |
(To see how the libb64 codebase compares with some other BASE64 implementations |
| 81 |
available, see the BENCHMARKS file) |
| 82 |
|
| 83 |
The trick involves the fact that a switch-statement may legally cross into |
| 84 |
sub-blocks. A very thorough and enlightening essay on co-routines in C, using |
| 85 |
this method, can be found in the above mentioned "Coroutines in C", by Simon |
| 86 |
Tatham: http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html |
| 87 |
|
| 88 |
For example, an RLE decompressing routine, adapted from the article: |
| 89 |
1 static int STATE = 0; |
| 90 |
2 static int len, c; |
| 91 |
3 switch (STATE) |
| 92 |
4 { |
| 93 |
5 while (1) |
| 94 |
6 { |
| 95 |
7 c = getchar(); |
| 96 |
8 if (c == EOF) return EOF; |
| 97 |
9 if (c == 0xFF) { |
| 98 |
10 len = getchar(); |
| 99 |
11 c = getchar(); |
| 100 |
12 while (len--) |
| 101 |
13 { |
| 102 |
14 STATE = 0; |
| 103 |
15 return c; |
| 104 |
16 case 0: |
| 105 |
17 } |
| 106 |
18 } else |
| 107 |
19 STATE = 1; |
| 108 |
20 return c; |
| 109 |
21 case 1: |
| 110 |
22 } |
| 111 |
23 } |
| 112 |
24 } |
| 113 |
|
| 114 |
As can be seen from this example, a coroutine depends on a state variable, |
| 115 |
which it sets directly before exiting (lines 14 and 119). The next time the |
| 116 |
routine is entered, the switch moves control to the specific point directly |
| 117 |
after the previous exit (lines 16 and 21).hands |
| 118 |
|
| 119 |
(As an aside, in the mentioned article the combination of the top-level switch, |
| 120 |
the various setting of the state, the return of a value, and the labelling of |
| 121 |
the exit point is wrapped in #define macros, making the structure of the |
| 122 |
routine even clearer.) |
| 123 |
|
| 124 |
The obvious problem with any such routine is the static keyword. |
| 125 |
Any static variables in a function spell doom for multithreaded applications. |
| 126 |
Also, in situations where this coroutine is used by more than one other |
| 127 |
coroutines, the consistency is disturbed. |
| 128 |
|
| 129 |
What is needed is a structure for storing these variabled, which is passed to |
| 130 |
the routine seperately. This obviously breaks the modularity of the function, |
| 131 |
since now the caller has to worry about and care for the internal state of the |
| 132 |
routine (the callee). This allows for a fast, multithreading-enabled |
| 133 |
implementation, which may (obviously) be wrapped in a C++ object for ease of |
| 134 |
use. |
| 135 |
|
| 136 |
The base64 encoding and decoding functionality in this package is implemented |
| 137 |
in exactly this way, providing both a high-speed high-maintanence C interface, |
| 138 |
and a wrapped C++ which is low-maintanence and only slightly less performant. |