ucw docs: base64 & base224

Documentation of base64 and base224 encoding. Describes the basecode
utility as well.

diff --git a/ucw/base224.h b/ucw/base224.h
index 7e815d8c3b864f16795ce1d535e6b716ea2bb271..f1941919e6091be9c1fdcfce797b8ad30d43c17a 100644 (file)
--- a/ucw/base224.h
+++ b/ucw/base224.h
@@ -7,12 +7,23 @@
  *     of the GNU Lesser General Public License.
  */
 
+/**
+ * Encodes @len bytes of data pointed to by @src by base224 encoding.
+ * Stores them in @dest and returns the number of bytes the output
+ * takes.
+ */
 uns base224_encode(byte *dest, const byte *src, uns len);
+/**
+ * Decodes @len bytes of data pointed to by @src from base224 encoding.
+ * All invalid characters are ignored. The result is stored into @dest
+ * and length of the result is returned.
+ */
 uns base224_decode(byte *dest, const byte *src, uns len);
 
-/*
- * Warning: when encoding, at least 4 bytes of extra space are needed.
- * Better use this macro to calculate buffer size.
+/**
+ * Use this macro to calculate base224_encode() output buffer size.
+ * It can happen 4 more bytes would be needed, this macro takes care
+ * of that.
  */
 #define BASE224_ENC_LENGTH(x) (((x)*8+38)/39*5)
 
@@ -21,5 +32,5 @@ uns base224_decode(byte *dest, const byte *src, uns len);
  * always BASE224_OUT_CHUNK bytes long. If a longer block is split
  * to such chunks, the result will be identical.
  */
-#define BASE224_IN_CHUNK 39
-#define BASE224_OUT_CHUNK 40
+#define BASE224_IN_CHUNK 39 /** Chunk size on the un-encoded side. **/
+#define BASE224_OUT_CHUNK 40 /** Chunk size on the encoded side. **/

diff --git a/ucw/base64.h b/ucw/base64.h
index 78909664286f7e33c58039784024c5ad81ae43a9..3f30b69acf112757c76afbce83caaa8ea5a8c8a5 100644 (file)
--- a/ucw/base64.h
+++ b/ucw/base64.h
@@ -7,11 +7,21 @@
  *     of the GNU Lesser General Public License.
  */
 
+/**
+ * Encodes @len bytes of data pointed to by @src by base64 encoding.
+ * Stores them in @dest and returns the number of bytes the output
+ * takes.
+ */
 uns base64_encode(byte *dest, const byte *src, uns len);
+/**
+ * Decodes @len bytes of data pointed to by @src from base64 encoding.
+ * All invalid characters are ignored. The result is stored into @dest
+ * and length of the result is returned.
+ */
 uns base64_decode(byte *dest, const byte *src, uns len);
 
-/*
- * Use this macro to calculate buffer size.
+/**
+ * Use this macro to calculate base64_encode() output buffer size.
  */
 #define BASE64_ENC_LENGTH(x) (((x)+2)/3 *4)
 
@@ -20,6 +30,6 @@ uns base64_decode(byte *dest, const byte *src, uns len);
  * always BASE64_OUT_CHUNK bytes long. If a longer block is split
  * to such chunks, the result will be identical.
  */
-#define BASE64_IN_CHUNK 3
-#define BASE64_OUT_CHUNK 4
+#define BASE64_IN_CHUNK 3 /** Size of chunk on the un-encoded side. **/
+#define BASE64_OUT_CHUNK 4 /** Size of chunk on the encoded side. **/
 

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
index b25d4beb60db43098efb52a7081e0440679ecfb5..3b9216acdf436a2b92f6ce2adea01de2abe2eae5 100644 (file)
--- a/ucw/doc/Makefile
+++ b/ucw/doc/Makefile
@@ -2,7 +2,7 @@
 
 DIRS+=ucw/doc
 
-UCW_DOCS=fastbuf index
+UCW_DOCS=fastbuf index basecode
 UCW_INDEX=$(o)/ucw/doc/def_index.html
 
 $(UCW_INDEX): DOC_HEAD=$(s)/ucw/doc/def_index.txt

diff --git a/ucw/doc/basecode.txt b/ucw/doc/basecode.txt
new file mode 100644 (file)
index 0000000..94b4102
--- /dev/null
+++ b/ucw/doc/basecode.txt
@@ -0,0 +1,75 @@
+Base64 and Base224 encodings
+============================
+
+These modules can be used to encode and decode data to and from
+base64 (described in RFC 3548) and base224 (not described in any
+standard, uses all non-control characters of ASCII).
+
+- <<base64,Base64>>
+- <<base224,Base224>>
+- <<usage,Usage>>
+- <<basecode,The basecode utility>>
+
+[[base64]]
+ucw/base64.h
+------------
+!!ucw/base64.h
+
+[[base224]]
+ucw/base224.h
+-------------
+!!ucw/base224.h
+
+[[usage]]
+Usage
+-----
+
+- You may want to encode small block of known size. Just allocate the
+  output buffer and feed the data to the function.
+
+  byte output[BASE64_ENC_LENGTH(input_size)];
+  uns output_size = base64_encode(output, input, input_size);
+
+- Decoding can be done in similar way. It is enough to have output
+  buffer of the same size as the input one.
+
+- Encoding of a stream of unknown or large size can be split into
+  chunks. The input chunk size must be multiple of `BASE64_IN_CHUNK`.
+  The output will be corresponding multiple of `BASE64_OUT_CHUNK`.
+
+  uns input_size;
+  byte input[BASE64_IN_CHUNK * 10];
+  while(input_size = read_chunk(input, BASE64_IN_CHUNK * 10)) {
+    byte output[BASE64_OUT_CHUNK * 10];
+    uns output_size = base64_encode(output, input, input_size);
+    use_chunk(output, output_size);
+  }
+
+- Decoding of a stream is done in the same way, just swap
+  `BASE64_IN_CHUNK` and `BASE64_OUT_CHUNK` (you feed the decode
+  function with `BASE64_OUT_CHUNK` multiple and get `BASE64_IN_CHUNK`
+  multiple).
+
+The base224 has similar interface, therefore you can use it the same
+way as base64.
+
+[[basecode]]
+The basecode utility
+--------------------
+You can use the encoding/decoding routines from command line, trough
+`basecode` command. You have to specify the operation by a command
+line argument and give it the data on standard input. The arguments
+are:
+
+- `-e`: Encode to base64.
+- `-d`: Decode from base64.
+- `-E`: Encode to base224.
+- `-D`: Decode from base224.
+
+Furthermore, you can provide `--prefix` argument. If you do, the
+output (when encoding) will be split to lines by default number of
+chunks and the value of prefix will be prepended to each of them.
+When decoding, it removes the prefix from the beginning of line.
+
+You can override the default number of blocks for line-splitting by
+`--blocks` argument.

diff --git a/ucw/doc/index.txt b/ucw/doc/index.txt
index 122a2e8aa73cfe1b6671d607072cc3453d7d70fc..aeccb034c21b8843fdd61f73ae01e177189e6296 100644 (file)
--- a/ucw/doc/index.txt
+++ b/ucw/doc/index.txt
@@ -10,3 +10,4 @@ You can see list of <<def_index:,definitions>>.
 Modules
 -------
 - <<fastbuf:,Fastbufs>>
+- <<basecode:,Base64 and Base224 encoding>>