1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
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());
}
%}
};
|
