build: enhance mutt_to_base64() (and callers)

- take chars and cast to unsigned chars inside, remove casts from callers
- return the number of characters written to the output buffers
- Doxygenize and verboize the documentation

Closes: #250

diff --git a/base64.c b/base64.c
index fd3ffb88aae31f41b8033435967d7ac7b4ad58f6..0245a7a6a785af3f3836b53769e2b0104c107fff 100644 (file)
--- a/base64.c
+++ b/base64.c
@@ -48,10 +48,24 @@
 
 #define BAD     -1
 
-/* raw bytes to null-terminated base 64 string */
-void mutt_to_base64 (unsigned char *out, const unsigned char *in, size_t len,
-                    size_t olen)
+/**
+ * mutt_to_base64 - convert raw bytes to null-terminated base64 string.
+ *
+ * @param out Output buffer for the base64 encoded string.
+ * @param cin Input buffer for the raw bytes.
+ * @param len Length of the input buffer.
+ * @param olen Length of the output buffer.
+ * @return The length of the string written to the output buffer.
+ *
+ * This function performs base64 encoding. The resulting string is guaranteed
+ * to be null-terminated. The number of characters up to the terminating
+ * null-byte is returned (equivalent to calling strlen() on the output buffer
+ * after this function returns).
+ */
+size_t mutt_to_base64 (char *out, const char *cin, size_t len, size_t olen)
 {
+  unsigned char *begin = (unsigned char *)out;
+  const unsigned char *in = (const unsigned char *)cin;
   while (len >= 3 && olen > 10)
   {
     *out++ = B64Chars[in[0] >> 2];
@@ -77,10 +91,20 @@ void mutt_to_base64 (unsigned char *out, const unsigned char *in, size_t len,
     *out++ = '=';
   }
   *out = '\0';
+  return out - (char *)begin;
 }
 
-/* Convert '\0'-terminated base 64 string to raw bytes.
- * Returns length of returned buffer, or -1 on error */
+/**
+ * mutt_from_base64 - convert null-terminated base64 string to raw bytes.
+ *
+ * @param out Output buffer for the raw bytes.
+ * @param cin Input buffer for the null-terminated base64-encoded string
+ * @return The number of bytes written on success, -1 on error.
+ *
+ * This function performs base64 decoding. The resulting buffer is NOT
+ * null-terminated. If the input buffer contains invalid base64 characters,
+ * this function returns -1.
+ */
 int mutt_from_base64 (char *out, const char *in)
 {
   int len = 0;

diff --git a/imap/auth_cram.c b/imap/auth_cram.c
index 9b6db9af61e838b7f3ae68c0048334708d58163a..f6c8e4e38b02a0c0888d60c33d4afd4798e57347 100644 (file)
--- a/imap/auth_cram.c
+++ b/imap/auth_cram.c
@@ -106,8 +106,7 @@ imap_auth_res_t imap_auth_cram_md5 (IMAP_DATA* idata, const char* method)
    * plus the additional debris
    */
   
-  mutt_to_base64 ((unsigned char*) ibuf, (unsigned char*) obuf, strlen (obuf),
-                 sizeof (ibuf) - 2);
+  mutt_to_base64 (ibuf, obuf, strlen (obuf), sizeof (ibuf) - 2);
   safe_strcat (ibuf, sizeof (ibuf), "\r\n");
   mutt_socket_write (idata->conn, ibuf);
 

diff --git a/imap/auth_gss.c b/imap/auth_gss.c
index 39786c4f1f43423d7946e9e572f87decae0d8280..c4f3b02261ba3ebc01e6009d4da2ed265b7df352 100644 (file)
--- a/imap/auth_gss.c
+++ b/imap/auth_gss.c
@@ -160,7 +160,7 @@ imap_auth_res_t imap_auth_gss (IMAP_DATA* idata, const char* method)
 
   /* now start the security context initialisation loop... */
   dprint (2, (debugfile, "Sending credentials\n"));
-  mutt_to_base64 ((unsigned char*) buf1, send_token.value, send_token.length,
+  mutt_to_base64 (buf1, send_token.value, send_token.length,
     sizeof (buf1) - 2);
   gss_release_buffer (&min_stat, &send_token);
   safe_strcat (buf1, sizeof (buf1), "\r\n");
@@ -197,8 +197,8 @@ imap_auth_res_t imap_auth_gss (IMAP_DATA* idata, const char* method)
 
       goto err_abort_cmd;
     }
-    mutt_to_base64 ((unsigned char*) buf1, send_token.value,
-      send_token.length, sizeof (buf1) - 2);
+    mutt_to_base64 (buf1, send_token.value, send_token.length,
+      sizeof (buf1) - 2);
     gss_release_buffer (&min_stat, &send_token);
     safe_strcat (buf1, sizeof (buf1), "\r\n");
     mutt_socket_write (idata->conn, buf1);
@@ -267,7 +267,7 @@ imap_auth_res_t imap_auth_gss (IMAP_DATA* idata, const char* method)
     goto err_abort_cmd;
   }
 
-  mutt_to_base64 ((unsigned char*) buf1, send_token.value, send_token.length,
+  mutt_to_base64 (buf1, send_token.value, send_token.length,
                  sizeof (buf1) - 2);
   dprint (2, (debugfile, "Requesting authorisation as %s\n",
     idata->conn->account.user));

diff --git a/protos.h b/protos.h
index a0aaf6f64a59a5aaf61e27df565d60f44fe79741..f9cd30976d5e14a95f6e8f2c2b06a88cd5713d3d 100644 (file)
--- a/protos.h
+++ b/protos.h
@@ -423,7 +423,7 @@ pid_t mutt_create_filter_fd (const char *, FILE **, FILE **, FILE **, int, int,
 ADDRESS *alias_reverse_lookup (ADDRESS *);
 
 /* base64.c */
-void mutt_to_base64 (unsigned char*, const unsigned char*, size_t, size_t);
+size_t mutt_to_base64 (char*, const char*, size_t, size_t);
 int mutt_from_base64 (char*, const char*);
 
 /* utf8.c */