/* 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 &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 &addrs) { return SetAddressingHeader(aPropertyName, const_cast&>(addrs).Elements(), addrs.Length()); } %} };