path: root/netwerk/base/http-sfv/nsIStructuredFieldValues.idl

/* 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();
};