nsIStructuredFieldValues.idl (9903B)
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)] 37 interface 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 type; 51 }; 52 53 [scriptable, builtinclass, uuid(843eea44-990a-422c-bbf2-2aa4ba9ee4d2)] 54 interface nsISFVInteger : nsISFVBareItem { 55 attribute long long value; 56 }; 57 58 [scriptable, builtinclass, uuid(df6a0787-7caa-4fef-b145-08c1104c2fde)] 59 interface nsISFVString : nsISFVBareItem { 60 attribute ACString value; 61 }; 62 63 [scriptable, builtinclass, uuid(d263c6d7-4123-4c39-a121-ccf874a19012)] 64 interface nsISFVBool : nsISFVBareItem { 65 attribute boolean value; 66 }; 67 68 [scriptable, builtinclass, uuid(1098da8b-b4df-4526-b985-53dbd4160ad2)] 69 interface nsISFVDecimal : nsISFVBareItem { 70 attribute double value; 71 }; 72 73 [scriptable, builtinclass, uuid(8ad33d52-b9b2-4a17-8aa8-991250fc1214)] 74 interface nsISFVToken : nsISFVBareItem { 75 attribute ACString value; 76 }; 77 78 [scriptable, builtinclass, uuid(887eaef0-19fe-42bc-9a42-9ff773aa8fea)] 79 interface 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)] 89 interface 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)] 124 interface 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)] 136 interface 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)] 143 interface 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)] 151 interface 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)] 161 interface 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)] 169 interface 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)] 187 interface 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)] 232 interface 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 boolean 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 };