nsINetUtil.idl (8485B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #include "nsISupports.idl" 7 8 interface nsIURI; 9 interface nsIPrefBranch; 10 11 /** 12 * nsINetUtil provides various network-related utility methods. 13 */ 14 [scriptable, uuid(fe2625ec-b884-4df1-b39c-9e830e47aa94)] 15 interface nsINetUtil : nsISupports 16 { 17 /** 18 * Parse a Content-Type header value in strict mode. This is a more 19 * conservative parser that reject things that violate RFC 7231 section 20 * 3.1.1.1. This is typically useful for parsing Content-Type header values 21 * that are used for HTTP requests, and those that are used to make security 22 * decisions. 23 * 24 * @param aTypeHeader the header string to parse 25 * @param [out] aCharset the charset parameter specified in the 26 * header, if any. 27 * @param [out] aHadCharset whether a charset was explicitly specified. 28 * @return the MIME type specified in the header, in lower-case. 29 */ 30 AUTF8String parseRequestContentType(in AUTF8String aTypeHeader, 31 out AUTF8String aCharset, 32 out boolean aHadCharset); 33 34 /** 35 * Parse a Content-Type header value in relaxed mode. This is a more 36 * permissive parser that ignores things that go against RFC 7231 section 37 * 3.1.1.1. This is typically useful for parsing Content-Type header values 38 * received from web servers where we want to make a best effort attempt 39 * at extracting a useful MIME type and charset. 40 * 41 * NOTE: DO NOT USE THIS if you're going to make security decisions 42 * based on the result. 43 * 44 * @param aTypeHeader the header string to parse 45 * @param [out] aCharset the charset parameter specified in the 46 * header, if any. 47 * @param [out] aHadCharset whether a charset was explicitly specified. 48 * @return the MIME type specified in the header, in lower-case. 49 */ 50 AUTF8String parseResponseContentType(in AUTF8String aTypeHeader, 51 out AUTF8String aCharset, 52 out boolean aHadCharset); 53 54 /** 55 * Test whether the given URI's handler has the given protocol flags. 56 * 57 * @param aURI the URI in question 58 * @param aFlags the flags we're testing for. 59 * 60 * @return whether the protocol handler for aURI has all the flags 61 * in aFlags. 62 */ 63 boolean protocolHasFlags(in nsIURI aURI, in unsigned long aFlag); 64 65 /** 66 * Test whether the protocol handler for this URI or that for any of 67 * its inner URIs has the given protocol flags. This will QI aURI to 68 * nsINestedURI and walk the nested URI chain. 69 * 70 * @param aURI the URI in question 71 * @param aFlags the flags we're testing for. 72 * 73 * @return whether any of the protocol handlers involved have all the flags 74 * in aFlags. 75 */ 76 boolean URIChainHasFlags(in nsIURI aURI, in unsigned long aFlags); 77 78 /** Escape every character with its %XX-escaped equivalent */ 79 const unsigned long ESCAPE_ALL = 0; 80 81 /** Leave alphanumeric characters intact and %XX-escape all others */ 82 const unsigned long ESCAPE_XALPHAS = 1; 83 84 /** Leave alphanumeric characters intact, convert spaces to '+', 85 %XX-escape all others */ 86 const unsigned long ESCAPE_XPALPHAS = 2; 87 88 /** Leave alphanumeric characters and forward slashes intact, 89 %XX-escape all others */ 90 const unsigned long ESCAPE_URL_PATH = 4; 91 92 /** Additional encoding for Apple's NSURL compatibility. 93 Like XALPHAS, but leave '%' to avoid double encoding, '+', and '/'. 94 %XX-escape all others */ 95 const unsigned long ESCAPE_URL_APPLE_EXTRA = 8; 96 97 /** 98 * escape a string with %00-style escaping 99 */ 100 ACString escapeString(in ACString aString, in unsigned long aEscapeType); 101 102 /** %XX-escape URL scheme */ 103 const unsigned long ESCAPE_URL_SCHEME = 1; 104 105 /** %XX-escape username in the URL */ 106 const unsigned long ESCAPE_URL_USERNAME = 1 << 1; 107 108 /** %XX-escape password in the URL */ 109 const unsigned long ESCAPE_URL_PASSWORD = 1 << 2; 110 111 /** %XX-escape URL host */ 112 const unsigned long ESCAPE_URL_HOST = 1 << 3; 113 114 /** %XX-escape URL directory */ 115 const unsigned long ESCAPE_URL_DIRECTORY = 1 << 4; 116 117 /** %XX-escape file basename in the URL */ 118 const unsigned long ESCAPE_URL_FILE_BASENAME = 1 << 5; 119 120 /** %XX-escape file extension in the URL */ 121 const unsigned long ESCAPE_URL_FILE_EXTENSION = 1 << 6; 122 123 /** %XX-escape URL parameters */ 124 const unsigned long ESCAPE_URL_PARAM = 1 << 7; 125 126 /** %XX-escape URL query */ 127 const unsigned long ESCAPE_URL_QUERY = 1 << 8; 128 129 /** %XX-escape URL ref */ 130 const unsigned long ESCAPE_URL_REF = 1 << 9; 131 132 /** %XX-escape URL path - same as escaping directory, basename and extension */ 133 const unsigned long ESCAPE_URL_FILEPATH = 134 ESCAPE_URL_DIRECTORY | ESCAPE_URL_FILE_BASENAME | ESCAPE_URL_FILE_EXTENSION; 135 136 /** %XX-escape scheme, username, password, host, path, params, query and ref */ 137 const unsigned long ESCAPE_URL_MINIMAL = 138 ESCAPE_URL_SCHEME | ESCAPE_URL_USERNAME | ESCAPE_URL_PASSWORD | 139 ESCAPE_URL_HOST | ESCAPE_URL_FILEPATH | ESCAPE_URL_PARAM | 140 ESCAPE_URL_QUERY | ESCAPE_URL_REF; 141 142 /** Force %XX-escaping of already escaped sequences */ 143 const unsigned long ESCAPE_URL_FORCED = 1 << 10; 144 145 /** Skip non-ascii octets, %XX-escape all others */ 146 const unsigned long ESCAPE_URL_ONLY_ASCII = 1 << 11; 147 148 /** 149 * Skip graphic octets (0x20-0x7E) when escaping 150 * Skips all ASCII octets (0x00-0x7F) when unescaping 151 */ 152 const unsigned long ESCAPE_URL_ONLY_NONASCII = 1 << 12; 153 154 /** Force %XX-escape of colon */ 155 const unsigned long ESCAPE_URL_COLON = 1 << 14; 156 157 /** Skip C0 and DEL from unescaping */ 158 const unsigned long ESCAPE_URL_SKIP_CONTROL = 1 << 15; 159 160 /** %XX-escape external protocol handler URL */ 161 const unsigned long ESCAPE_URL_EXT_HANDLER = 1 << 17; 162 163 /** 164 * %XX-Escape invalid chars in a URL segment. 165 * 166 * @param aStr the URL to be escaped 167 * @param aFlags the URL segment type flags 168 * 169 * @return the escaped string (the string itself if escaping did not happen) 170 * 171 */ 172 ACString escapeURL(in ACString aStr, in unsigned long aFlags); 173 174 /** 175 * Expands URL escape sequences 176 * 177 * @param aStr the URL to be unescaped 178 * @param aFlags only ESCAPE_URL_ONLY_NONASCII and ESCAPE_URL_SKIP_CONTROL 179 * are recognized. If |aFlags| is 0 all escape sequences are 180 * unescaped 181 * @return unescaped string 182 */ 183 ACString unescapeString(in AUTF8String aStr, in unsigned long aFlags); 184 185 /** 186 * Extract the charset parameter location and value from a content-type 187 * header. 188 * 189 * @param aTypeHeader the header string to parse 190 * @param [out] aCharset the charset parameter specified in the 191 * header, if any. 192 * @param [out] aCharsetStart index of the start of the charset parameter 193 * (the ';' separating it from what came before) in aTypeHeader. 194 * If this function returns false, this argument will still be 195 * set, to the index of the location where a new charset should 196 * be inserted. 197 * @param [out] aCharsetEnd index of the end of the charset parameter (the 198 * ';' separating it from what comes after, or the end 199 * of the string) in aTypeHeader. If this function returns 200 * false, this argument will still be set, to the index of the 201 * location where a new charset should be inserted. 202 * 203 * @return whether a charset parameter was found. This can be false even in 204 * cases when parseContentType would claim to have a charset, if the type 205 * that won out does not have a charset parameter specified. 206 */ 207 boolean extractCharsetFromContentType(in AUTF8String aTypeHeader, 208 out AUTF8String aCharset, 209 out long aCharsetStart, 210 out long aCharsetEnd); 211 212 /** 213 * This is test-only. Send an IPC message to let socket process send a 214 * telemetry. 215 */ 216 void socketProcessTelemetryPing(); 217 218 /** 219 * This is a void method that is C++ implemented and always 220 * returns NS_ERROR_NOT_IMPLEMENTED. To be used for testing. 221 */ 222 void notImplemented(); 223 };