[gmime] Added GMimeFormatOptions

[Jeffrey Stedfast <fejj src gnome org>]

commit dfc8b968db3c65388fa4f60c4e535b06d60fea7a
Author: Jeffrey Stedfast <jestedfa microsoft com>
Date:   Fri Mar 17 17:25:47 2017 -0400

    Added GMimeFormatOptions

 docs/reference/gmime-docs.sgml    |    4 +
 docs/reference/gmime-sections.txt |   19 ++
 gmime/Makefile.am                 |    2 +
 gmime/gmime-format-options.c      |  453 +++++++++++++++++++++++++++++++++++++
 gmime/gmime-format-options.h      |   97 ++++++++
 gmime/gmime.h                     |    1 +
 6 files changed, 576 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gmime-docs.sgml b/docs/reference/gmime-docs.sgml
index b7976c7..08482bc 100644
--- a/docs/reference/gmime-docs.sgml
+++ b/docs/reference/gmime-docs.sgml
@@ -24,6 +24,8 @@
 <!ENTITY InternetAddressGroup SYSTEM "xml/internet-address-group.xml">
 <!ENTITY InternetAddressMailbox SYSTEM "xml/internet-address-mailbox.xml">
 <!ENTITY InternetAddressList SYSTEM "xml/internet-address-list.xml">
+<!ENTITY GMimeFormatOptions SYSTEM "xml/gmime-format-options.xml">
+<!ENTITY GMimeParserOptions SYSTEM "xml/gmime-parser-options.xml">
 <!ENTITY GMimeParser SYSTEM "xml/gmime-parser.xml">
 <!ENTITY gmime-charset SYSTEM "xml/gmime-charset.xml">
 <!ENTITY gmime-iconv SYSTEM "xml/gmime-iconv.xml">
@@ -174,6 +176,7 @@ string utilities, file utilities, a main loop abstraction, and so on.
     &gmime-iconv-utils;
     &gmime-encodings;
     &gmime-utils;
+    &GMimeFormatOptions;
   </part>
 
   <part id="classes">
@@ -253,6 +256,7 @@ string utilities, file utilities, a main loop abstraction, and so on.
 
     <chapter id="Parsers">
       <title>Parsing Messages and MIME Parts</title>
+      &GMimeParserOptions;
       &GMimeParser;
     </chapter>
 
diff --git a/docs/reference/gmime-sections.txt b/docs/reference/gmime-sections.txt
index 73dfe95..93f91ef 100644
--- a/docs/reference/gmime-sections.txt
+++ b/docs/reference/gmime-sections.txt
@@ -1188,6 +1188,25 @@ InternetAddressListClass
 </SECTION>
 
 <SECTION>
+<FILE>gmime-format-options</FILE>
+GMimeNewLineFormat
+GMimeFormatOptions
+g_mime_format_options_new
+g_mime_format_options_free
+g_mime_format_options_get_default
+g_mime_format_options_get_param_encoding_method
+g_mime_format_options_set_param_encoding_method
+g_mime_format_options_get_newline_format
+g_mime_format_options_set_newline_format
+g_mime_format_options_get_newline
+g_mime_format_options_create_newline_filter
+g_mime_format_options_is_hidden_header
+g_mime_format_options_add_hidden_header
+g_mime_format_options_remove_hidden_header
+g_mime_format_options_clear_hidden_headers
+</SECTION>
+
+<SECTION>
 <FILE>gmime-parser-options</FILE>
 GMimeParserOptions
 GMimeRfcComplianceMode
diff --git a/gmime/Makefile.am b/gmime/Makefile.am
index bfdf9f3..59f781e 100644
--- a/gmime/Makefile.am
+++ b/gmime/Makefile.am
@@ -44,6 +44,7 @@ libgmime_3_0_la_SOURCES =             \
        gmime-filter-strip.c            \
        gmime-filter-windows.c          \
        gmime-filter-yenc.c             \
+       gmime-format-options.c          \
        gmime-gpg-context.c             \
        gmime-gpgme-utils.c             \
        gmime-header.c                  \
@@ -103,6 +104,7 @@ gmimeinclude_HEADERS =                      \
        gmime-filter-strip.h            \
        gmime-filter-windows.h          \
        gmime-filter-yenc.h             \
+       gmime-format-options.h          \
        gmime-gpg-context.h             \
        gmime-header.h                  \
        gmime-iconv.h                   \
diff --git a/gmime/gmime-format-options.c b/gmime/gmime-format-options.c
new file mode 100644
index 0000000..39bd8fd
--- /dev/null
+++ b/gmime/gmime-format-options.c
@@ -0,0 +1,453 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
+/*  GMime
+ *  Copyright (C) 2000-2017 Jeffrey Stedfast
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public License
+ *  as published by the Free Software Foundation; either version 2.1
+ *  of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free
+ *  Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA
+ *  02110-1301, USA.
+ */
+
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <string.h>
+
+#include "gmime-format-options.h"
+#include "gmime-filter-crlf.h"
+
+
+static GMimeFormatOptions *default_options = NULL;
+
+
+/**
+ * SECTION: gmime-format-options
+ * @title: GMimeFormatOptions
+ * @short_description: Format options
+ * @see_also:
+ *
+ * A #GMimeFormatOptions is used by GMime to determine how to serialize various objects and headers.
+ **/
+
+
+void
+g_mime_format_options_init (void)
+{
+       if (default_options == NULL)
+               default_options = g_mime_format_options_new ();
+}
+
+void
+g_mime_format_options_shutdown (void)
+{
+       guint i;
+       
+       if (default_options == NULL)
+               return;
+       
+       for (i = 0; i < default_options->hidden->len; i++)
+               g_free (default_options->hidden->pdata[i]);
+       
+       g_ptr_array_free (default_options->hidden, TRUE);
+       g_slice_free (GMimeFormatOptions, default_options);
+       default_options = NULL;
+}
+
+
+/**
+ * g_mime_format_options_get_default:
+ *
+ * Gets the default format options.
+ *
+ * Returns: the default format options.
+ **/
+GMimeFormatOptions *
+g_mime_format_options_get_default (void)
+{
+       return default_options;
+}
+
+
+/**
+ * g_mime_format_options_new:
+ *
+ * Creates a new set of #GMimeFormatOptions.
+ *
+ * Returns: a newly allocated set of #GMimeFormatOptions with the default values.
+ **/
+GMimeFormatOptions *
+g_mime_format_options_new (void)
+{
+       GMimeFormatOptions *options;
+       
+       options = g_slice_new (GMimeFormatOptions);
+       options->method = GMIME_PARAM_ENCODING_METHOD_RFC2231;
+       options->newline = GMIME_NEWLINE_FORMAT_UNIX;
+       options->hidden = g_ptr_array_new ();
+       options->mixed_charsets = TRUE;
+       options->international = FALSE;
+       options->maxline = 78;
+       
+       return options;
+}
+
+
+/**
+ * _g_mime_format_options_clone:
+ * @options: a #GMimeFormatOptions
+ *
+ * Clones a #GMimeFormatOptions.
+ *
+ * Returns: a newly allocated #GMimeFormatOptions.
+ **/
+GMimeFormatOptions *
+_g_mime_format_options_clone (GMimeFormatOptions *options)
+{
+       GMimeFormatOptions *clone;
+       guint i;
+       
+       clone = g_slice_new (GMimeFormatOptions);
+       clone->method = options->method;
+       clone->newline = options->newline;
+       clone->mixed_charsets = options->mixed_charsets;
+       clone->international = options->international;
+       clone->maxline = options->newline;
+       
+       clone->hidden = g_ptr_array_new ();
+       for (i = 0; i < options->hidden->len; i++)
+               g_ptr_array_add (clone->hidden, g_strdup (options->hidden->pdata[i]));
+       
+       return clone;
+}
+
+
+/**
+ * g_mime_format_options_free:
+ * @options: a #GMimeFormatOptions
+ *
+ * Frees a set of #GMimeFormatOptions.
+ **/
+void
+g_mime_format_options_free (GMimeFormatOptions *options)
+{
+       guint i;
+       
+       g_return_if_fail (options != NULL);
+       
+       if (options != default_options) {
+               for (i = 0; i < options->hidden->len; i++)
+                       g_free (options->hidden->pdata[i]);
+               g_ptr_array_free (options->hidden, TRUE);
+               
+               g_slice_free (GMimeFormatOptions, options);
+       }
+}
+
+
+/**
+ * g_mime_format_options_get_param_encoding_method:
+ * @options: a #GMimeFormatOptions
+ *
+ * Gets the parameter encoding method to use for #GMimeParam parameters that do not
+ * already have an encoding method specified.
+ *
+ * Returns: the encoding method that is currently set.
+ **/
+GMimeParamEncodingMethod
+g_mime_format_options_get_param_encoding_method (GMimeFormatOptions *options)
+{
+       g_return_val_if_fail (options != NULL, GMIME_PARAM_ENCODING_METHOD_RFC2231);
+       
+       return options->method;
+}
+
+
+/**
+ * g_mime_format_options_set_param_encoding_method:
+ * @options: a #GMimeFormatOptions
+ * @method: a #GMimeParamEncodingMethod
+ *
+ * Sets the parameter encoding method to use when encoding parameters which
+ * do not have an encoding method specified.
+ *
+ * Note: #GMIME_PARAM_ENCODING_METHOD_DEFAULT is not allowed.
+ **/
+void
+g_mime_format_options_set_param_encoding_method (GMimeFormatOptions *options, GMimeParamEncodingMethod 
method)
+{
+       g_return_if_fail (options != NULL);
+       g_return_if_fail (method == GMIME_PARAM_ENCODING_METHOD_RFC2231 || method == 
GMIME_PARAM_ENCODING_METHOD_RFC2047);
+       
+       options->method = method;
+}
+
+
+/**
+ * g_mime_format_options_get_newline_format:
+ * @options: a #GMimeFormatOptions
+ *
+ * Gets the new-line format to use when writing out messages and headers.
+ *
+ * Returns: the new-line format that is currently set.
+ **/
+GMimeNewLineFormat
+g_mime_format_options_get_newline_format (GMimeFormatOptions *options)
+{
+       g_return_val_if_fail (options != NULL, GMIME_NEWLINE_FORMAT_UNIX);
+       
+       return options->newline;
+}
+
+
+/**
+ * g_mime_format_options_set_newline_format:
+ * @options: a #GMimeFormatOptions
+ * @newline: a #GMimeNewLineFormat
+ *
+ * Sets the new-line format that should be used when writing headers and messages.
+ **/
+void
+g_mime_format_options_set_newline_format (GMimeFormatOptions *options, GMimeNewLineFormat newline)
+{
+       g_return_if_fail (options != NULL);
+       g_return_if_fail (newline == GMIME_NEWLINE_FORMAT_UNIX || newline == GMIME_NEWLINE_FORMAT_DOS);
+       
+       options->newline = newline;
+}
+
+
+/**
+ * g_mime_format_options_get_newline:
+ * @options: a #GMimeFormatOptions
+ *
+ * Gets a string representing the currently set new-line format.
+ *
+ * Returns: a new-line character sequence.
+ **/
+const char *
+g_mime_format_options_get_newline (GMimeFormatOptions *options)
+{
+       if (options != NULL && options->newline == GMIME_NEWLINE_FORMAT_DOS)
+               return "\r\n";
+       
+       return "\n";
+}
+
+
+/**
+ * g_mime_format_options_create_newline_filter:
+ * @options: a #GMimeFormatOptions
+ * @ensure_newline: %TRUE if the output must *always* end with a new line
+ *
+ * Creates a #GMimeFilter suitable for converting line-endings to the
+ * currently set new-line format.
+ *
+ * Returns: (transfer full): a #GMimeFilter to convert to the specified new-line format.
+ **/
+GMimeFilter *
+g_mime_format_options_create_newline_filter (GMimeFormatOptions *options, gboolean ensure_newline)
+{
+       if (options != NULL && options->newline == GMIME_NEWLINE_FORMAT_DOS)
+               return g_mime_filter_crlf_new (TRUE, FALSE);
+       
+       return g_mime_filter_crlf_new (FALSE, FALSE);
+}
+
+
+#ifdef NOT_YET_IMPLEMENTED
+/**
+ * g_mime_format_options_get_allow_mixed_charsets:
+ * @options: a #GMimeFormatOptions
+ *
+ * Gets whether or not headers are allowed to be encoded using mixed charsets.
+ *
+ * Returns: %TRUE if each header value is allowed to be encoded with mixed charsets or %FALSE otherwise.
+ **/
+gboolean
+g_mime_format_options_get_allow_mixed_charsets (GMimeFormatOptions *options)
+{
+       g_return_val_if_fail (options != NULL, TRUE);
+       
+       return options->mixed_charsets;
+}
+
+
+/**
+ * g_mime_format_options_set_allow_mixed_charsets:
+ * @options: a #GMimeFormatOptions
+ * @allow: %TRUE if each header value should be allowed to be encoded with mixed charsets
+ *
+ * Sets whether or not header values should be allowed to be encoded with mixed charsets.
+ **/
+void
+g_mime_format_options_set_allow_mixed_charsets (GMimeFormatOptions *options, gboolean allow)
+{
+       g_return_if_fail (options != NULL);
+       
+       options->mixed_charsets = allow;
+}
+
+
+/**
+ * g_mime_format_options_get_allow_international:
+ * @options: a #GMimeFormatOptions
+ *
+ * Gets whether or not international encoding is allowed.
+ *
+ * Returns: %TRUE if international encoding is allowed or %FALSE otherwise.
+ **/
+gboolean
+g_mime_format_options_get_allow_international (GMimeFormatOptions *options)
+{
+       g_return_val_if_fail (options != NULL, FALSE);
+       
+       return options->international;
+}
+
+
+/**
+ * g_mime_format_options_set_allow_international:
+ * @options: a #GMimeFormatOptions
+ * @allow: %TRUE if international encoding is allowed
+ *
+ * Sets whether or not international encoding is allowed.
+ **/
+void
+g_mime_format_options_set_allow_international (GMimeFormatOptions *options, gboolean allow)
+{
+       g_return_if_fail (options != NULL);
+       
+       options->international = allow;
+}
+
+
+/**
+ * g_mime_format_options_get_allow_international:
+ * @options: a #GMimeFormatOptions
+ *
+ * Gets the max line length to use with encoders.
+ *
+ * Returns: the max line length to use with encoders.
+ **/
+guint
+g_mime_format_options_get_max_line (GMimeFormatOptions *options)
+{
+       g_return_val_if_fail (options != NULL, 78);
+       
+       return options->maxline;
+}
+
+
+/**
+ * g_mime_format_options_set_max_line:
+ * @options: a #GMimeFormatOptions
+ * @maxline: the max line length
+ *
+ * Sets the max line length to use for encoders.
+ **/
+void
+g_mime_format_options_set_max_line (GMimeFormatOptions *options, guint maxline)
+{
+       g_return_if_fail (options != NULL);
+       
+       options->maxline = maxline;
+}
+#endif
+
+/**
+ * g_mime_format_options_is_hidden_header:
+ * @options: a #GMimeFormatOptions
+ * @header: the name of a header
+ *
+ * Gets whether or not the specified header should be hidden.
+ *
+ * Returns: %TRUE if the header should be hidden or %FALSE otherwise.
+ **/
+gboolean
+g_mime_format_options_is_hidden_header (GMimeFormatOptions *options, const char *header)
+{
+       guint i;
+       
+       g_return_val_if_fail (options != NULL, FALSE);
+       g_return_val_if_fail (header != NULL, FALSE);
+       
+       for (i = 0; i < options->hidden->len; i++) {
+               if (!g_ascii_strcasecmp (options->hidden->pdata[i], header))
+                       return TRUE;
+       }
+       
+       return FALSE;
+}
+
+
+/**
+ * g_mime_format_options_add_hidden_header:
+ * @options: a #GMimeFormatOptions
+ * @header: a header name
+ *
+ * Adds the given header to the list of headers that should be hidden.
+ **/
+void
+g_mime_format_options_add_hidden_header (GMimeFormatOptions *options, const char *header)
+{
+       g_return_if_fail (options != NULL);
+       g_return_if_fail (header != NULL);
+       
+       g_ptr_array_add (options->hidden, g_strdup (header));
+}
+
+
+/**
+ * g_mime_format_options_remove_hidden_header:
+ * @options: a #GMimeFormatOptions
+ * @header: a header name
+ *
+ * Removes the given header from the list of headers that should be hidden.
+ **/
+void
+g_mime_format_options_remove_hidden_header (GMimeFormatOptions *options, const char *header)
+{
+       guint i;
+       
+       g_return_if_fail (options != NULL);
+       g_return_if_fail (header != NULL);
+       
+       for (i = options->hidden->len; i > 0; i--) {
+               if (!g_ascii_strcasecmp (options->hidden->pdata[i - 1], header)) {
+                       g_free (options->hidden->pdata[i - 1]);
+                       g_ptr_array_remove_index (options->hidden, i - 1);
+               }
+       }
+}
+
+
+/**
+ * g_mime_format_options_clear_hidden_headers:
+ * @options: a #GMimeFormatOptions
+ *
+ * Clears the list of headers that should be hidden.
+ **/
+void
+g_mime_format_options_clear_hidden_headers (GMimeFormatOptions *options)
+{
+       guint i;
+       
+       g_return_if_fail (options != NULL);
+       
+       for (i = 0; i < options->hidden->len; i++)
+               g_free (options->hidden->pdata[i]);
+       
+       g_ptr_array_set_size (options->hidden, 0);
+}
diff --git a/gmime/gmime-format-options.h b/gmime/gmime-format-options.h
new file mode 100644
index 0000000..aa450ca
--- /dev/null
+++ b/gmime/gmime-format-options.h
@@ -0,0 +1,97 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
+/*  GMime
+ *  Copyright (C) 2000-2017 Jeffrey Stedfast
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public License
+ *  as published by the Free Software Foundation; either version 2.1
+ *  of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free
+ *  Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA
+ *  02110-1301, USA.
+ */
+
+
+#ifndef __GMIME_FORMAT_OPTIONS_H__
+#define __GMIME_FORMAT_OPTIONS_H__
+
+#include <glib.h>
+#include <gmime/gmime-param.h>
+#include <gmime/gmime-filter.h>
+
+G_BEGIN_DECLS
+
+/**
+ * GMimeNewLineFormat:
+ * @GMIME_NEWLINE_FORMAT_UNIX: The Unix New-Line format ("\n").
+ * @GMIME_NEWLINE_FORMAT_DOS: The DOS New-Line format ("\r\n").
+ *
+ * There are two commonly used line-endings used by modern Operating Systems.
+ * Unix-based systems such as Linux and Mac OS use a single character ('\n' aka LF)
+ * to represent the end of line where-as Windows (or DOS) uses a sequence of two
+ * characters ("\r\n" aka CRLF). Most text-based network protocols such as SMTP,
+ * POP3, and IMAP use the CRLF sequence as well.
+ **/
+typedef enum {
+       GMIME_NEWLINE_FORMAT_UNIX,
+       GMIME_NEWLINE_FORMAT_DOS
+} GMimeNewLineFormat;
+
+/**
+ * GMimeFormatOptions:
+ * @method: The method to use for parameter encoding.
+ * @newline: The new-line format to use.
+ * @mixed_charsets: Whether or not to allow mixed charsets when encoding header values.
+ * @international: Whether or not to allow internationalized header values.
+ * @hidden: A list of hidden headers.
+ * @maxline: The max line length to allow for encoded content.
+ *
+ * Format options for serializing various GMime objects.
+ **/
+typedef struct {
+       GMimeParamEncodingMethod method;
+       GMimeNewLineFormat newline;
+       gboolean mixed_charsets;
+       gboolean international;
+       GPtrArray *hidden;
+       guint maxline;
+} GMimeFormatOptions;
+
+GMimeFormatOptions *g_mime_format_options_get_default (void);
+
+GMimeFormatOptions *g_mime_format_options_new (void);
+void g_mime_format_options_free (GMimeFormatOptions *options);
+
+GMimeParamEncodingMethod g_mime_format_options_get_param_encoding_method (GMimeFormatOptions *options);
+void g_mime_format_options_set_param_encoding_method (GMimeFormatOptions *options, GMimeParamEncodingMethod 
method);
+
+GMimeNewLineFormat g_mime_format_get_newline_format (GMimeFormatOptions *options);
+void g_mime_format_set_newline_format (GMimeFormatOptions *options, GMimeNewLineFormat newline);
+
+const char *g_mime_format_options_get_newline (GMimeFormatOptions *options);
+GMimeFilter *g_mime_format_options_create_newline_filter (GMimeFormatOptions *options, gboolean 
ensure_newline);
+
+/*gboolean g_mime_format_options_get_allow_mixed_charsets (GMimeFormatOptions *options);*/
+/*void g_mime_format_options_set_allow_mixed_charsets (GMimeFormatOptions *options, gboolean allow);*/
+
+/*gboolean g_mime_format_options_get_allow_international (GMimeFormatOptions *options);*/
+/*void g_mime_format_options_set_allow_international (GMimeFormatOptions *options, gboolean allow);*/
+
+/*gboolean g_mime_format_options_get_max_line (GMimeFormatOptions *options);*/
+/*void g_mime_format_options_set_max_line (GMimeFormatOptions *options, gboolean maxline);*/
+
+gboolean g_mime_format_options_is_hidden_header (GMimeFormatOptions *options, const char *header);
+void g_mime_format_options_add_hidden_header (GMimeFormatOptions *options, const char *header);
+void g_mime_format_options_remove_hidden_header (GMimeFormatOptions *options, const char *header);
+void g_mime_format_options_clear_hidden_headers (GMimeFormatOptions *options);
+
+G_END_DECLS
+
+#endif /* __GMIME_FORMAT_OPTIONS_H__ */
diff --git a/gmime/gmime.h b/gmime/gmime.h
index 7a360f7..84717d4 100644
--- a/gmime/gmime.h
+++ b/gmime/gmime.h
@@ -45,6 +45,7 @@
 #include <gmime/gmime-message-partial.h>
 #include <gmime/internet-address.h>
 #include <gmime/gmime-encodings.h>
+#include <gmime/gmime-format-options.h>
 #include <gmime/gmime-parser-options.h>
 #include <gmime/gmime-parser.h>
 #include <gmime/gmime-utils.h>