Issue #1258 - Part 1: Import mailnews, ldap, and mork from comm-esr52.9.1

1 files changed, 209 insertions, 0 deletions

diff --git a/mailnews/mime/public/msgIStructuredHeaders.idl b/mailnews/mime/public/msgIStructuredHeaders.idl
new file mode 100644
index 000000000..9d3b3aa9a
--- /dev/null
+++ b/mailnews/mime/public/msgIStructuredHeaders.idl
@@ -0,0 +1,209 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsISupports.idl"
+
+%{C++
+#include "nsCOMArray.h"
+
+#define NS_ISTRUCTUREDHEADERS_CONTRACTID \
+  "@mozilla.org/messenger/structuredheaders;1"
+%}
+
+interface msgIAddressObject;
+interface nsIUTF8StringEnumerator;
+
+/**
+ * A collection of MIME headers that are stored in a rich, structured format.
+ *
+ * The structured forms defined in this method use the structured decoder and
+ * encoder functionality found in jsmime to interconvert between the raw string
+ * forms found in the actual message text and the structured forms supported by
+ * this interface. Extensions can register their own custom structured headers
+ * by listing the source URL of their code under the category
+ * "custom-mime-encoder".
+ *
+ * The alternative modes of access for specific headers are expected to only
+ * work for the headers for which that mode of access is the correct one. For
+ * example, retrieving the "To" header from getUnstructuredHeader would fail,
+ * since the To header is not an unstructured header but an addressing header.
+ * They are provided mostly as a convenience to C++ which is much less able to
+ * utilize a fully generic format.
+ *
+ * With the exception of mismatched headers, the methods do not throw an
+ * exception if the header is missing but rather return an appropriate default
+ * value as indicated in their documentation.
+ */
+[scriptable, uuid(e109bf4f-788f-47ba-bfa8-1236ede05597)]
+interface msgIStructuredHeaders : nsISupports {
+  /**
+   * Retrieve the value of the header stored in this set of headers. If the
+   * header is not present, then undefined is returned.
+   *
+   * @param aHeaderName     The name of the header to retrieve.
+   */
+  jsval getHeader(in string aHeaderName);
+
+  /**
+   * Return true if and only if the given header is already set.
+   *
+   * @param aHeaderName     The name of the header to retrieve.
+   */
+  bool hasHeader(in string aHeaderName);
+
+  /**
+   * Retrieve the value of the header as if it is an unstructured header. Such
+   * headers include most notably the Subject header. If the header is not
+   * present, then null is returned. This is reflected in C++ as an empty string
+   * with IsVoid() set to true (distinguishing it from a header that is present
+   * but contains an empty string).
+   *
+   * @param aHeaderName     The name of the header to retrieve.
+   */
+  AString getUnstructuredHeader(in string aHeaderName);
+
+  /**
+   * Retrieve the value of the header if it is an addressing header, such as the
+   * From or To headers. If the header is not present, then an empty array is
+   * returned.
+   *
+   * @param aHeaderName     The name of the header to retrieve.
+   * @param aPreserveGroups If false (the default), then the result is a flat
+   *                        list of addresses, with all group annotations
+   *                        removed.
+   *                        If true, then some address objects may represent
+   *                        groups in the header, preserving the original header
+   *                        structure.
+   */
+  void getAddressingHeader(in string aHeaderName,
+    [optional] in boolean aPreserveGroups, [optional] out unsigned long count,
+    [array, size_is(count), retval] out msgIAddressObject addresses);
+
+  /**
+   * Retrieve a raw version of the header value as would be represented in MIME.
+   * This form does not include the header name and colon, trailing whitespace,
+   * nor embedded CRLF pairs in the case of very long header names.
+   *
+   * @param aHeaderName     The name of the header to retrieve.
+   */
+  AUTF8String getRawHeader(in string aHeaderName);
+
+  /**
+   * Retrieve an enumerator of the names of all headers in this set of headers.
+   * The header names returned may be in different cases depending on the
+   * precise implementation of this interface, so implementations should not
+   * rely on an exact kind of case being returned.
+   */
+  readonly attribute nsIUTF8StringEnumerator headerNames;
+
+  /**
+   * Retrieve the MIME representation of all of the headers.
+   *
+   * The header values are emitted in an ASCII form, unless internationalized
+   * email addresses are involved. The extra CRLF indicating the end of headers
+   * is not included in this representation.
+   *
+   * This accessor is provided mainly for the benefit of C++ consumers of this
+   * interface, since the JSMime headeremitter functionality allows more
+   * fine-grained customization of the results.
+   */
+   AUTF8String buildMimeText();
+
+%{C++
+  /**
+   * A special variant of getAddressingHeader that is specialized better for C++
+   * users of this API.
+   */
+  nsresult GetAddressingHeader(const char *aPropertyName,
+                               nsCOMArray<msgIAddressObject> &addrs,
+                               bool aPreserveGroups = false)
+  {
+    msgIAddressObject **addrPtr;
+    uint32_t length;
+    nsresult rv = GetAddressingHeader(aPropertyName, aPreserveGroups, &length,
+      &addrPtr);
+    NS_ENSURE_SUCCESS(rv, rv);
+    addrs.Adopt(addrPtr, length);
+    return NS_OK;
+  }
+%}
+
+};
+
+/**
+ * An interface that enhances msgIStructuredHeaders by allowing the values of
+ * headers to be modified.
+ */
+[scriptable, uuid(5dcbbef6-2356-45d8-86d7-b3e73f9c9a0c)]
+interface msgIWritableStructuredHeaders : msgIStructuredHeaders {
+  /**
+   * Store the given value for the given header, overwriting any previous value
+   * that was stored for said header.
+   *
+   * @param aHeaderName     The name of the header to store.
+   * @param aValue          The rich, structured value of the header to store.
+   */
+  void setHeader(in string aHeaderName, in jsval aValue);
+
+  /**
+   * Forget any previous value that was stored for the given header.
+   *
+   * @param aHeaderName     The name of the header to delete.
+   */
+  void deleteHeader(in string aHeaderName);
+
+  /**
+   * Copy all of the structured values from another set of structured headers to
+   * the current one, overwriting any values that may have been specified
+   * locally. Note that the copy is a shallow copy of the value.
+   *
+   * @param aOtherHeaders   A set of header values to be copied.
+   */
+  void addAllHeaders(in msgIStructuredHeaders aOtherHeaders);
+
+  /**
+   * Set the value of the header as if it were an unstructured header. Such
+   * headers include most notably the Subject header.
+   *
+   * @param aHeaderName     The name of the header to store.
+   * @param aValue          The value to store.
+   */
+  void setUnstructuredHeader(in string aHeaderName, in AString aValue);
+
+  /**
+   * Set the value of the header as if it were an addressing header, such as the
+   * From or To headers.
+   *
+   * @param aHeaderName     The name of the header to store.
+   */
+  void setAddressingHeader(in string aHeaderName,
+    [array, size_is(aCount)] in msgIAddressObject aAddresses,
+    in unsigned long aCount);
+
+  /**
+   * Store the value of the header using a raw version as would be represented
+   * in MIME. So as to handle 8-bit headers properly, the charset needs to be
+   * specified, although it may be null.
+   *
+   * @param aHeaderName     The name of the header to store.
+   * @param aValue          The raw MIME header value to store.
+   * @param aCharset        The expected charset of aValue.
+   */
+  void setRawHeader(in string aHeaderName, in ACString aValue,
+                    in string aCharset);
+
+%{C++
+  /**
+   * A special variant of setAddressingHeader that is specialized better for C++
+   * users of this API.
+   */
+  nsresult SetAddressingHeader(const char *aPropertyName,
+                               const nsCOMArray<msgIAddressObject> &addrs)
+  {
+    return SetAddressingHeader(aPropertyName,
+      const_cast<nsCOMArray<msgIAddressObject>&>(addrs).Elements(),
+      addrs.Length());
+  }
+%}
+};