Add base64 docs

diff --git a/ChangeLog b/ChangeLog
index 03845d01518f19f31c2e8f5cdd43793f7bfa2445..1de75e28d98a794399e07cf3a362b5b85dc19190 100644 (file)
--- 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 03845d01518f19f31c2e8f5cdd43793f7bfa2445..1de75e28d98a794399e07cf3a362b5b85dc19190 100644 (file)
--- 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 92b24a8cc089355110179ae199ab6ddd354bd5ee..90cc0d0e1eac25ebe7e7773f24a4039db3549e25 100644 (file)
--- 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 02801d1fdd83fef099889abb4556c84323c99336..951adacc7f3d108b910226f91963bdff8bbd45ee 100644 (file)
--- 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 15b1e5b57cf035edebddb09882450596fb65b860..786b832aa52d834521089d8e2f0a90c33a1158da 100644 (file)
--- 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 (file)
index 0000000..a935ac6
--- /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 f6e0cd0d9605c7ec442e2845cb2a6179c9d76791..14f20d39208d3202ad9f33ff97d2e38e09604c46 100644 (file)
--- 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 1aa2bff63a29cfe5acb120c4ad77c8233ee8ed3c..6637984ec16b96d8e656c6ed8b9c09ab05e0f485 100644 (file)
--- 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 3a03e077b3854c94efc70a3efe1690e9718b295f..6c98a3b48cc1e2563335019b15fbf0fdbec68641 100644 (file)
--- 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