summaryrefslogtreecommitdiffstats
path: root/netwerk/base/http-sfv/nsIStructuredFieldValues.idl
blob: 20b0392ac98ceccac760eb09970b393e343b7ab6 (plain)
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
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
/* 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"

/**
 * Conceptually, there are three types of structured field (header) values:
 *
 * Item - can be an Integer, Decimal, String, Token, Byte Sequence, or Boolean.
 * It can have associated Parameters.
 * List - array of zero or more members, each of which can be an Item or an InnerList,
 * both of which can be Parameterized.
 * Dictionary - ordered map of name-value pairs, where the names are short textual strings
 * and the values are Items or arrays of Items (represented with InnerList),
 * both of which can be Parameterized. There can be zero or more members,
 * and their names are unique in the scope of the Dictionary they occur within.
 *
 *
 * There's also a few primitive types used to construct structured field values:
 * - BareItem used as Item's value or as a parameter value in Parameters.
 * - Parameters are an ordered map of key-value pairs that are associated with an Item or InnerList.
 * The keys are unique within the scope the Parameters they occur within, and the values are BareItem.
 * - InnerList is an array of zero or more Items. Can have Parameters.
 * - ListEntry represents either Item or InnerList as a member of List or as member-value in Dictionary.
 */



/**
 * nsISFVBareItem is a building block for Item header value (nsISFVItem) and Parameters (nsISFVParams).
 * It can be of type BOOL, STRING, DECIMAL, INTEGER, TOKEN, BYTE_SEQUENCE.
 * Each type is represented by its own interface which is used to create
 * a bare item of that type.
 */
[scriptable, builtinclass, uuid(7072853f-215b-4a8a-92e5-9732bccc377b)]
interface nsISFVBareItem : nsISupports {
    const long BOOL = 1;
    const long STRING = 2;
    const long DECIMAL = 3;
    const long INTEGER = 4;
    const long TOKEN = 5;
    const long BYTE_SEQUENCE = 6;

    /**
     * Returns value associated with type of bare item.
     * Used to identify type of bare item without querying for interface
     * (like nsISFVString, etc).
     */
    readonly attribute long type;
};

[scriptable, builtinclass, uuid(843eea44-990a-422c-bbf2-2aa4ba9ee4d2)]
interface nsISFVInteger : nsISFVBareItem {
    attribute long long value;
};

[scriptable, builtinclass, uuid(df6a0787-7caa-4fef-b145-08c1104c2fde)]
interface nsISFVString : nsISFVBareItem {
    attribute ACString value;
};

[scriptable, builtinclass, uuid(d263c6d7-4123-4c39-a121-ccf874a19012)]
interface nsISFVBool : nsISFVBareItem {
    attribute boolean value;
};

[scriptable, builtinclass, uuid(1098da8b-b4df-4526-b985-53dbd4160ad2)]
interface nsISFVDecimal : nsISFVBareItem {
    attribute double value;
};

[scriptable, builtinclass, uuid(8ad33d52-b9b2-4a17-8aa8-991250fc1214)]
interface nsISFVToken : nsISFVBareItem {
    attribute ACString value;
};

[scriptable, builtinclass, uuid(887eaef0-19fe-42bc-9a42-9ff773aa8fea)]
interface nsISFVByteSeq : nsISFVBareItem {
    attribute ACString value;
};


/**
 * nsISFVParams represents parameters, key-value pairs of ACString and nsISFVBareItem,
 * which parametrize Item type header or InnerList type withing List type header.
 */
[scriptable, builtinclass, uuid(b1a397d7-3333-43e7-993a-fbe8ab90ee96)]
interface nsISFVParams : nsISupports {
    /**
     * Return value (nsISFVBareItem) stored for key, if it is present
     *
     * @throws NS_ERROR_UNEXPECTED if the key does not exist in parameters.
     */
    nsISFVBareItem get(in ACString key);

    /**
     * Insert a new key-value pair.
     * If an equivalent key already exists: the key remains and retains in its place in the order,
     * its corresponding value is updated with the new value.
     *
     * @throws NS_ERROR_UNEXPECTED if supplied item does not implement nsISFVBareItem interface.
     */
    void set(in ACString key, in nsISFVBareItem item);

    /**
     * Remove the key-value pair equivalent to key.
     *
     * @throws NS_ERROR_UNEXPECTED upon attempt to delete  key that does not exist in parameters.
     */
    void delete(in ACString key);

    /**
     * Returns array of keys.
     */
    Array<ACString> keys();
};

/**
 * nsISFVParametrizable is implemented for types that
 * can be parametrized with nsISFVParams
 */
[scriptable, builtinclass, uuid(6c0399f8-01de-4b25-b339-68e35e8d2e49)]
interface nsISFVParametrizable : nsISupports {
    readonly attribute nsISFVParams params;
};

/**
 * nsISFVItemOrInnerList represents member in nsISFVList
 * or member-value in nsISFVDictionary.
 * nsISFVItemOrInnerList is implemented for
 * nsISFVItem or nsISFVInnerList, both of which are used
 * to create nsISFVList and nsISFVDictionary.
 */
[scriptable, builtinclass, uuid(99ac1b56-b5b3-44e7-ad96-db7444aae4b2)]
interface nsISFVItemOrInnerList : nsISFVParametrizable {
};

/**
 * nsISFVSerialize indicates that object can be serialized into ACString.
 */
[scriptable, builtinclass, uuid(28b9215d-c131-413c-9482-0004a371a5ec)]
interface nsISFVSerialize : nsISupports {
    ACString serialize();
};

/**
 * nsISFVItem represents Item structured header value.
 */
[scriptable, builtinclass, uuid(abe8826b-6af7-4e54-bd2c-46ab231700ce)]
interface nsISFVItem : nsISFVItemOrInnerList {
    readonly attribute nsISFVBareItem value;
    ACString serialize();
};

/**
 * nsISFVInnerList can be used as a member of nsISFVList
 * or a member-value of nsISFVDictionary.
 */
[scriptable, builtinclass, uuid(b2e52be2-8488-41b2-9ee2-3c48d92d095c)]
interface nsISFVInnerList : nsISFVItemOrInnerList {
    attribute Array<nsISFVItem> items;
};

/**
 * nsISFVList represents List structured header value.
 */
[scriptable, builtinclass, uuid(02bb92a6-d1de-449c-b54f-d137f30c613d)]
interface nsISFVList : nsISFVSerialize {
    /**
     * Returns array of members.
     * QueryInterface can be used on a member to get more specific type.
     */
    attribute Array<nsISFVItemOrInnerList> members;

    /**
     * In case when header value is split across lines, it's possible
     * this method parses supplied line and merges it with members of existing object.
     */
    void parseMore(in ACString header);
};

/**
 * nsISFVDictionary represents nsISFVDictionary structured header value.
 */
[scriptable, builtinclass, uuid(6642a7fe-7026-4eba-b730-05e230ee3437)]
interface nsISFVDictionary : nsISFVSerialize {

    /**
     * Return value (nsISFVItemOrInnerList) stored for key, if it is present.
     * QueryInterface can be used on a value to get more specific type.
     *
     * @throws NS_ERROR_UNEXPECTED if the key does not exist in parameters.
     */
    nsISFVItemOrInnerList get(in ACString key);

    /**
     * Insert a new key-value pair.
     * If an equivalent key already exists: the key remains and retains in its place in the order,
     * its corresponding value is updated with the new value.
     *
     * @throws NS_ERROR_UNEXPECTED if supplied item does not implement nsISFVItemOrInnerList interface.
     */
    void set(in ACString key, in nsISFVItemOrInnerList member_value);

    /**
     * Remove the key-value pair equivalent to key.
     *
     * @throws NS_ERROR_UNEXPECTED upon attempt to delete  key that does not exist in parameters.
     */
    void delete(in ACString key);

    /**
     * Returns array of keys.
     */
    Array<ACString> keys();

    /**
     * In case when header value is split across lines, it's possible
     * this method parses supplied line and merges it with members of existing object.
     */
    void parseMore(in ACString header);
};


/**
 * nsISFVService provides a set of functions for working with HTTP header value as an object.
 * It exposes functions for creating object from string containing header value,
 * as well as individual components for manual structured header object creation.
 */
[scriptable, builtinclass, uuid(049f4be1-2f22-4438-a8da-518552ed390c)]
interface nsISFVService: nsISupports
{
    /**
     * Parses provided string into Dictionary header value (nsISFVDictionary).
     *
     * @throws NS_ERROR_FAILURE if parsing fails.
     */
    nsISFVDictionary parseDictionary(in ACString header);

    /**
     * Parses provided string into List header value (nsISFVList).
     *
     * @throws NS_ERROR_FAILURE if parsing fails.
     */
    nsISFVList parseList(in ACString header);

    /**
     * Parses provided string into Item header value (nsISFVItem).
     *
     * @throws NS_ERROR_FAILURE if parsing fails.
     */
    nsISFVItem parseItem(in ACString header);

    /**
     * The following functions create bare item of specific type.
     */
    nsISFVInteger newInteger(in long long value);
    nsISFVBool newBool(in boolean value);
    nsISFVDecimal newDecimal(in double value);
    nsISFVString newString(in ACString value);
    nsISFVByteSeq newByteSequence(in ACString value);
    nsISFVToken newToken(in ACString value);

    /**
     * Creates nsISFVParams with no parameters. In other words, it's an empty map byt default.
     */
    nsISFVParams newParameters();

    /**
     * Creates nsISFVInnerList from nsISFVItem array and nsISFVParams.
     */
    nsISFVInnerList newInnerList(in Array<nsISFVItem> items, in nsISFVParams params);

    /**
     * Creates nsISFVItem, which represents Item header value, from nsISFVBareItem and associated nsISFVParams.
     */
    nsISFVItem newItem(in nsISFVBareItem value, in nsISFVParams params);

    /**
     * Creates nsISFVList, which represents List header value, from array of nsISFVItemOrInnerList.
     * nsISFVItemOrInnerList represens either Item (nsISFVItem) or Inner List (nsISFVInnerList).
     */
    nsISFVList newList(in Array<nsISFVItemOrInnerList> members);

    /**
     * Creates nsISFVDictionary representing Dictionary header value. It is empty by default.
     */
    nsISFVDictionary newDictionary();
};