1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5#include "nsISupports.idl"
6
7/**
8 * Conceptually, there are three types of structured field (header) values:
9 *
10 * Item - can be an Integer, Decimal, String, Token, Byte Sequence, or Boolean.
11 * It can have associated Parameters.
12 * List - array of zero or more members, each of which can be an Item or an InnerList,
13 * both of which can be Parameterized.
14 * Dictionary - ordered map of name-value pairs, where the names are short textual strings
15 * and the values are Items or arrays of Items (represented with InnerList),
16 * both of which can be Parameterized. There can be zero or more members,
17 * and their names are unique in the scope of the Dictionary they occur within.
18 *
19 *
20 * There's also a few primitive types used to construct structured field values:
21 * - BareItem used as Item's value or as a parameter value in Parameters.
22 * - Parameters are an ordered map of key-value pairs that are associated with an Item or InnerList.
23 * The keys are unique within the scope the Parameters they occur within, and the values are BareItem.
24 * - InnerList is an array of zero or more Items. Can have Parameters.
25 * - ListEntry represents either Item or InnerList as a member of List or as member-value in Dictionary.
26 */
27
28
29
30/**
31 * nsISFVBareItem is a building block for Item header value (nsISFVItem) and Parameters (nsISFVParams).
32 * It can be of type BOOL, STRING, DECIMAL, INTEGER, TOKEN, BYTE_SEQUENCE.
33 * Each type is represented by its own interface which is used to create
34 * a bare item of that type.
35 */
36[scriptable, builtinclass, uuid(7072853f-215b-4a8a-92e5-9732bccc377b)]
37interface nsISFVBareItem : nsISupports {
38    const long BOOL = 1;
39    const long STRING = 2;
40    const long DECIMAL = 3;
41    const long INTEGER = 4;
42    const long TOKEN = 5;
43    const long BYTE_SEQUENCE = 6;
44
45    /**
46     * Returns value associated with type of bare item.
47     * Used to identify type of bare item without querying for interface
48     * (like nsISFVString, etc).
49     */
50    readonly attribute long long type;
51};
52
53[scriptable, builtinclass, uuid(843eea44-990a-422c-bbf2-2aa4ba9ee4d2)]
54interface nsISFVInteger : nsISFVBareItem {
55    attribute long long value;
56};
57
58[scriptable, builtinclass, uuid(df6a0787-7caa-4fef-b145-08c1104c2fde)]
59interface nsISFVString : nsISFVBareItem {
60    attribute ACString value;
61};
62
63[scriptable, builtinclass, uuid(d263c6d7-4123-4c39-a121-ccf874a19012)]
64interface nsISFVBool : nsISFVBareItem {
65    attribute boolean value;
66};
67
68[scriptable, builtinclass, uuid(1098da8b-b4df-4526-b985-53dbd4160ad2)]
69interface nsISFVDecimal : nsISFVBareItem {
70    attribute double value;
71};
72
73[scriptable, builtinclass, uuid(8ad33d52-b9b2-4a17-8aa8-991250fc1214)]
74interface nsISFVToken : nsISFVBareItem {
75    attribute ACString value;
76};
77
78[scriptable, builtinclass, uuid(887eaef0-19fe-42bc-9a42-9ff773aa8fea)]
79interface nsISFVByteSeq : nsISFVBareItem {
80    attribute ACString value;
81};
82
83
84/**
85 * nsISFVParams represents parameters, key-value pairs of ACString and nsISFVBareItem,
86 * which parametrize Item type header or InnerList type withing List type header.
87 */
88[scriptable, builtinclass, uuid(b1a397d7-3333-43e7-993a-fbe8ab90ee96)]
89interface nsISFVParams : nsISupports {
90    /**
91     * Return value (nsISFVBareItem) stored for key, if it is present
92     *
93     * @throws NS_ERROR_UNEXPECTED if the key does not exist in parameters.
94     */
95    nsISFVBareItem get(in ACString key);
96
97    /**
98     * Insert a new key-value pair.
99     * If an equivalent key already exists: the key remains and retains in its place in the order,
100     * its corresponding value is updated with the new value.
101     *
102     * @throws NS_ERROR_UNEXPECTED if supplied item does not implement nsISFVBareItem interface.
103     */
104    void set(in ACString key, in nsISFVBareItem item);
105
106    /**
107     * Remove the key-value pair equivalent to key.
108     *
109     * @throws NS_ERROR_UNEXPECTED upon attempt to delete  key that does not exist in parameters.
110     */
111    void delete(in ACString key);
112
113    /**
114     * Returns array of keys.
115     */
116    Array<ACString> keys();
117};
118
119/**
120 * nsISFVParametrizable is implemented for types that
121 * can be parametrized with nsISFVParams
122 */
123[scriptable, builtinclass, uuid(6c0399f8-01de-4b25-b339-68e35e8d2e49)]
124interface nsISFVParametrizable : nsISupports {
125    readonly attribute nsISFVParams params;
126};
127
128/**
129 * nsISFVItemOrInnerList represents member in nsISFVList
130 * or member-value in nsISFVDictionary.
131 * nsISFVItemOrInnerList is implemented for
132 * nsISFVItem or nsISFVInnerList, both of which are used
133 * to create nsISFVList and nsISFVDictionary.
134 */
135[scriptable, builtinclass, uuid(99ac1b56-b5b3-44e7-ad96-db7444aae4b2)]
136interface nsISFVItemOrInnerList : nsISFVParametrizable {
137};
138
139/**
140 * nsISFVSerialize indicates that object can be serialized into ACString.
141 */
142[scriptable, builtinclass, uuid(28b9215d-c131-413c-9482-0004a371a5ec)]
143interface nsISFVSerialize : nsISupports {
144    ACString serialize();
145};
146
147/**
148 * nsISFVItem represents Item structured header value.
149 */
150[scriptable, builtinclass, uuid(abe8826b-6af7-4e54-bd2c-46ab231700ce)]
151interface nsISFVItem : nsISFVItemOrInnerList {
152    readonly attribute nsISFVBareItem value;
153    ACString serialize();
154};
155
156/**
157 * nsISFVInnerList can be used as a member of nsISFVList
158 * or a member-value of nsISFVDictionary.
159 */
160[scriptable, builtinclass, uuid(b2e52be2-8488-41b2-9ee2-3c48d92d095c)]
161interface nsISFVInnerList : nsISFVItemOrInnerList {
162    attribute Array<nsISFVItem> items;
163};
164
165/**
166 * nsISFVList represents List structured header value.
167 */
168[scriptable, builtinclass, uuid(02bb92a6-d1de-449c-b54f-d137f30c613d)]
169interface nsISFVList : nsISFVSerialize {
170    /**
171     * Returns array of members.
172     * QueryInterface can be used on a member to get more specific type.
173     */
174    attribute Array<nsISFVItemOrInnerList> members;
175
176    /**
177     * In case when header value is split across lines, it's possible
178     * this method parses supplied line and merges it with members of existing object.
179     */
180    void parseMore(in ACString header);
181};
182
183/**
184 * nsISFVDictionary represents nsISFVDictionary structured header value.
185 */
186[scriptable, builtinclass, uuid(6642a7fe-7026-4eba-b730-05e230ee3437)]
187interface nsISFVDictionary : nsISFVSerialize {
188
189    /**
190     * Return value (nsISFVItemOrInnerList) stored for key, if it is present.
191     * QueryInterface can be used on a value to get more specific type.
192     *
193     * @throws NS_ERROR_UNEXPECTED if the key does not exist in parameters.
194     */
195    nsISFVItemOrInnerList get(in ACString key);
196
197    /**
198     * Insert a new key-value pair.
199     * If an equivalent key already exists: the key remains and retains in its place in the order,
200     * its corresponding value is updated with the new value.
201     *
202     * @throws NS_ERROR_UNEXPECTED if supplied item does not implement nsISFVItemOrInnerList interface.
203     */
204    void set(in ACString key, in nsISFVItemOrInnerList member_value);
205
206    /**
207     * Remove the key-value pair equivalent to key.
208     *
209     * @throws NS_ERROR_UNEXPECTED upon attempt to delete  key that does not exist in parameters.
210     */
211    void delete(in ACString key);
212
213    /**
214     * Returns array of keys.
215     */
216    Array<ACString> keys();
217
218    /**
219     * In case when header value is split across lines, it's possible
220     * this method parses supplied line and merges it with members of existing object.
221     */
222    void parseMore(in ACString header);
223};
224
225
226/**
227 * nsISFVService provides a set of functions for working with HTTP header value as an object.
228 * It exposes functions for creating object from string containing header value,
229 * as well as individual components for manual structured header object creation.
230 */
231[scriptable, builtinclass, uuid(049f4be1-2f22-4438-a8da-518552ed390c)]
232interface nsISFVService: nsISupports
233{
234    /**
235     * Parses provided string into Dictionary header value (nsISFVDictionary).
236     *
237     * @throws NS_ERROR_FAILURE if parsing fails.
238     */
239    nsISFVDictionary parseDictionary(in ACString header);
240
241    /**
242     * Parses provided string into List header value (nsISFVList).
243     *
244     * @throws NS_ERROR_FAILURE if parsing fails.
245     */
246    nsISFVList parseList(in ACString header);
247
248    /**
249     * Parses provided string into Item header value (nsISFVItem).
250     *
251     * @throws NS_ERROR_FAILURE if parsing fails.
252     */
253    nsISFVItem parseItem(in ACString header);
254
255    /**
256     * The following functions create bare item of specific type.
257     */
258    nsISFVInteger newInteger(in long long value);
259    nsISFVBool newBool(in bool value);
260    nsISFVDecimal newDecimal(in double value);
261    nsISFVString newString(in ACString value);
262    nsISFVByteSeq newByteSequence(in ACString value);
263    nsISFVToken newToken(in ACString value);
264
265    /**
266     * Creates nsISFVParams with no parameters. In other words, it's an empty map byt default.
267     */
268    nsISFVParams newParameters();
269
270    /**
271     * Creates nsISFVInnerList from nsISFVItem array and nsISFVParams.
272     */
273    nsISFVInnerList newInnerList(in Array<nsISFVItem> items, in nsISFVParams params);
274
275    /**
276     * Creates nsISFVItem, which represents Item header value, from nsISFVBareItem and associated nsISFVParams.
277     */
278    nsISFVItem newItem(in nsISFVBareItem value, in nsISFVParams params);
279
280    /**
281     * Creates nsISFVList, which represents List header value, from array of nsISFVItemOrInnerList.
282     * nsISFVItemOrInnerList represens either Item (nsISFVItem) or Inner List (nsISFVInnerList).
283     */
284    nsISFVList newList(in Array<nsISFVItemOrInnerList> members);
285
286    /**
287     * Creates nsISFVDictionary representing Dictionary header value. It is empty by default.
288     */
289    nsISFVDictionary newDictionary();
290};
291