diff options
Diffstat (limited to 'netwerk/base/http-sfv/nsIStructuredFieldValues.idl')
| -rw-r--r-- | netwerk/base/http-sfv/nsIStructuredFieldValues.idl | 290 |
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(); +}; |