Add base64 docs

9 files changed, 178 insertions, 49 deletions

diff --git a/ChangeLog b/ChangeLog
index 03845d015..1de75e28d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2006-04-04  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/glib.symbols:
+	* glib/gbase64.[hc]: Add G_GNUC_MALLOC where
+	appropriate, use glib types.
+
 2006-04-04  Alexander Larsson  <alexl@redhat.com>
 
 	* glib/Makefile.am:
diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12
index 03845d015..1de75e28d 100644
--- a/ChangeLog.pre-2-12
+++ b/ChangeLog.pre-2-12
@@ -1,3 +1,9 @@
+2006-04-04  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/glib.symbols:
+	* glib/gbase64.[hc]: Add G_GNUC_MALLOC where
+	appropriate, use glib types.
+
 2006-04-04  Alexander Larsson  <alexl@redhat.com>
 
 	* glib/Makefile.am:
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 92b24a8cc..90cc0d0e1 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2006-04-04  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/glib-sections.txt:
+	* glib/glib-docs.sgml: Add Base64 section
+
 2006-04-03  Matthias Clasen  <mclasen@redhat.com>
 
 	* gobject/tmpl/objects.sgml: Add some verbiage to 
diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml
index 02801d1fd..951adacc7 100644
--- a/docs/reference/glib/glib-docs.sgml
+++ b/docs/reference/glib/glib-docs.sgml
@@ -58,6 +58,7 @@
 <!ENTITY glib-Markup SYSTEM "xml/markup.xml">
 <!ENTITY glib-Keyfile SYSTEM "xml/keyfile.xml">
 <!ENTITY glib-Bookmarkfile SYSTEM "xml/bookmarkfile.xml">
+<!ENTITY glib-Base64 SYSTEM "xml/base64.xml">
 <!ENTITY glib-i18n SYSTEM "xml/i18n.xml">
 <!ENTITY glib-Version SYSTEM "xml/version.xml">
 
@@ -135,6 +136,7 @@ synchronize their operation.
     &glib-String-Utility-Functions;
     &glib-Character-Set-Conversion;
     &glib-Unicode-Manipulation;
+    &glib-Base64;
     &glib-i18n;
     &glib-Date-and-Time-Functions;
     &glib-Random-Numbers;   
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 15b1e5b57..786b832aa 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -2305,3 +2305,13 @@ g_strip_context
 <SUBSECTION>
 g_get_language_names
 </SECTION>
+
+<SECTION>
+<TITLE>Base64 Encoding</TITLE>
+<FILE>base64</FILE>
+g_base64_encode_step
+g_base64_encode_close
+g_base64_encode
+g_base64_decode_step
+g_base64_decode
+</SECTION>
diff --git a/docs/reference/glib/tmpl/base64.sgml b/docs/reference/glib/tmpl/base64.sgml
new file mode 100644
index 000000000..a935ac6b9
--- /dev/null
+++ b/docs/reference/glib/tmpl/base64.sgml
@@ -0,0 +1,95 @@
+<!-- ##### SECTION Title ##### -->
+Base64 Encoding
+
+<!-- ##### SECTION Short_Description ##### -->
+encodes and decodes data in Base64 format
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+Base64 is an encoding that allows to encode a sequence of arbitrary
+bytes as a sequence of printable ASCII characters. For the definition
+of Base64, see <ulink url="http://www.ietf.org/rfc/rfc1421.txt">RFC 
+1421</ulink> or <ulink url="http://www.ietf.org/rfc/rfc2045.txt">RFC
+2045</ulink>. Base64 is most commonly used as a MIME transfer encoding
+for email.
+</para>
+
+<para>
+GLib supports incremental encoding using g_base64_encode_step() and
+g_base64_encode_close(). Incremental decoding can be done with
+g_base64_decode_step() and g_base64_decode_close(). To encode or
+decode data in one go, use g_base64_encode() of g_base64_decode(). 
+</para>
+
+<para>
+Support for Base64 encoding has been added in GLib 2.12.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### FUNCTION g_base64_encode_step ##### -->
+<para>
+
+</para>
+
+@in: 
+@len: 
+@break_lines: 
+@out: 
+@state: 
+@save: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_base64_encode_close ##### -->
+<para>
+
+</para>
+
+@break_lines: 
+@out: 
+@state: 
+@save: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_base64_encode ##### -->
+<para>
+
+</para>
+
+@data: 
+@len: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_base64_decode_step ##### -->
+<para>
+
+</para>
+
+@in: 
+@len: 
+@out: 
+@state: 
+@save: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_base64_decode ##### -->
+<para>
+
+</para>
+
+@text: 
+@out_len: 
+@Returns: 
+
+
diff --git a/glib/gbase64.c b/glib/gbase64.c
index f6e0cd0d9..14f20d392 100644
--- a/glib/gbase64.c
+++ b/glib/gbase64.c
@@ -66,12 +66,12 @@ static const char base64_alphabet[] =
  * Since: 2.12
  */
 gsize
-g_base64_encode_step (const guchar  *in, 
-		      gsize          len, 
-		      gboolean       break_lines, 
-		      char          *out, 
-		      int           *state, 
-		      int           *save)
+g_base64_encode_step (const guchar *in, 
+		      gsize         len, 
+		      gboolean      break_lines, 
+		      gchar        *out, 
+		      gint         *state, 
+		      gint         *save)
 {
   char *outptr;
   const guchar *inptr;
@@ -91,10 +91,14 @@ g_base64_encode_step (const guchar  *in,
       already = *state;
       
       switch (((char *) save) [0])
-	{
-	case 1:	c1 = ((unsigned char *) save) [1]; goto skip1;
-	case 2:	c1 = ((unsigned char *) save) [1];
-	  c2 = ((unsigned char *) save) [2]; goto skip2;
+	{	
+	case 1:	
+	  c1 = ((unsigned char *) save) [1]; 
+          goto skip1;
+	case 2:	
+          c1 = ((unsigned char *) save) [1];
+	  c2 = ((unsigned char *) save) [2]; 
+          goto skip2;
 	}
       
       /* 
@@ -115,15 +119,15 @@ g_base64_encode_step (const guchar  *in,
 					(c3 >> 6) ];
 	  *outptr++ = base64_alphabet [ c3 & 0x3f ];
 	  /* this is a bit ugly ... */
-	  if (break_lines && (++already)>=19)
+	  if (break_lines && (++already) >= 19)
 	    {
-	      *outptr++='\n';
+	      *outptr++ = '\n';
 	      already = 0;
 	    }
 	}
       
       ((char *)save)[0] = 0;
-      len = 2-(inptr-inend);
+      len = 2 - (inptr - inend);
       *state = already;
     }
   
@@ -140,10 +144,10 @@ g_base64_encode_step (const guchar  *in,
 	case 2:	*saveout++ = *inptr++;
 	case 1:	*saveout++ = *inptr++;
 	}
-      ((char *)save)[0]+=len;
+      ((char *)save)[0] += len;
     }
   
-  return outptr-out;
+  return outptr - out;
 }
 
 /**
@@ -160,10 +164,10 @@ g_base64_encode_step (const guchar  *in,
  * Since: 2.12
  */
 gsize
-g_base64_encode_close (gboolean       break_lines,
-		       char          *out, 
-		       int           *state, 
-		       int           *save)
+g_base64_encode_close (gboolean  break_lines,
+		       gchar    *out, 
+		       gint     *state, 
+		       gint     *save)
 {
   int c1, c2;
   char *outptr = out;
@@ -192,7 +196,7 @@ g_base64_encode_close (gboolean       break_lines,
   *save = 0;
   *state = 0;
   
-  return outptr-out;
+  return outptr - out;
 }
 
 /**
@@ -208,12 +212,13 @@ g_base64_encode_close (gboolean       break_lines,
  *
  * Since: 2.12
  */
-char *
-g_base64_encode (const guchar *data, gsize len)
+gchar *
+g_base64_encode (const guchar *data, 
+                 gsize         len)
 {
-  char *out;
-  int state = 0, outlen;
-  int save = 0;
+  gchar *out;
+  gint state = 0, outlen;
+  gint save = 0;
 
   /* We can use a smaller limit here, since we know the saved state is 0 */
   out = g_malloc (len * 4 / 3 + 4);
@@ -223,7 +228,7 @@ g_base64_encode (const guchar *data, gsize len)
 				   &state, 
 				   &save);
   out[outlen] = '\0';
-  return (char *) out;
+  return (gchar *) out;
 }
 
 static const unsigned char mime_base64_rank[256] = {
@@ -246,7 +251,7 @@ static const unsigned char mime_base64_rank[256] = {
 };
 
 /**
- * g_base64_decode_step: decode a chunk of base64 encoded data
+ * g_base64_decode_step: 
  * @in: binary input data
  * @len: max length of @in data to decode
  * @out: output buffer
@@ -266,11 +271,11 @@ static const unsigned char mime_base64_rank[256] = {
  * Since: 2.12
  **/
 gsize
-g_base64_decode_step (const char  *in, 
-		      gsize        len, 
-		      guchar      *out, 
-		      int         *state, 
-		      guint       *save)
+g_base64_decode_step (const gchar  *in, 
+		      gsize         len, 
+		      guchar       *out, 
+		      gint         *state, 
+		      guint        *save)
 {
   const guchar *inptr;
   guchar *outptr;
@@ -337,11 +342,11 @@ g_base64_decode_step (const char  *in,
  * Since: 2.12
  */
 guchar *
-g_base64_decode (const char   *text,
-		 gsize        *out_len)
+g_base64_decode (const gchar *text,
+		 gsize       *out_len)
 {
   guchar *ret;
-  int inlen, state = 0;
+  gint inlen, state = 0;
   guint save = 0;
   
   inlen = strlen (text);
diff --git a/glib/gbase64.h b/glib/gbase64.h
index 1aa2bff63..6637984ec 100644
--- a/glib/gbase64.h
+++ b/glib/gbase64.h
@@ -28,22 +28,22 @@ G_BEGIN_DECLS
 gsize   g_base64_encode_step  (const guchar *in,
 			       gsize         len,
 			       gboolean      break_lines,
-			       char         *out,
-			       int          *state,
-			       int          *save);
+			       gchar        *out,
+			       gint         *state,
+			       gint         *save);
 gsize   g_base64_encode_close (gboolean      break_lines,
-			       char         *out,
-			       int          *state,
-			       int          *save);
-char *  g_base64_encode       (const guchar *data,
-			       gsize         len);
-gsize   g_base64_decode_step  (const char   *in,
+			       gchar        *out,
+			       gint         *state,
+			       gint         *save);
+gchar*  g_base64_encode       (const guchar *data,
+			       gsize         len) G_GNUC_MALLOC;
+gsize   g_base64_decode_step  (const gchar  *in,
 			       gsize         len,
 			       guchar       *out,
-			       int          *state,
+			       gint         *state,
 			       guint        *save);
-guchar *g_base64_decode       (const char   *text,
-			       gsize        *out_len);
+guchar *g_base64_decode       (const gchar  *text,
+			       gsize        *out_len) G_GNUC_MALLOC;
 
 G_END_DECLS
 
diff --git a/glib/glib.symbols b/glib/glib.symbols
index 3a03e077b..6c98a3b48 100644
--- a/glib/glib.symbols
+++ b/glib/glib.symbols
@@ -107,9 +107,9 @@ g_on_error_stack_trace
 #if IN_FILE(__G_BASE64_C__)
 g_base64_encode_step
 g_base64_encode_close
-g_base64_encode
+g_base64_encode G_GNUC_MALLOC
 g_base64_decode_step
-g_base64_decode
+g_base64_decode G_GNUC_MALLOC
 #endif
 #endif