Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 290 insertions, 0 deletions

diff --git a/netwerk/base/http-sfv/nsIStructuredFieldValues.idl b/netwerk/base/http-sfv/nsIStructuredFieldValues.idl
new file mode 100644
index 0000000000..3f02b33953
--- /dev/null
+++ b/netwerk/base/http-sfv/nsIStructuredFieldValues.idl
@@ -0,0 +1,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 bool 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();
+};