1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsINetUtil.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,195 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsIPrefBranch;
1.13 +
1.14 +/**
1.15 + * nsINetUtil provides various network-related utility methods.
1.16 + */
1.17 +[scriptable, uuid(ca68c485-9db3-4c12-82a6-4fab7948e2d5)]
1.18 +interface nsINetUtil : nsISupports
1.19 +{
1.20 + /**
1.21 + * Parse a content-type header and return the content type and
1.22 + * charset (if any).
1.23 + *
1.24 + * @param aTypeHeader the header string to parse
1.25 + * @param [out] aCharset the charset parameter specified in the
1.26 + * header, if any.
1.27 + * @param [out] aHadCharset whether a charset was explicitly specified.
1.28 + * @return the MIME type specified in the header, in lower-case.
1.29 + */
1.30 + AUTF8String parseContentType(in AUTF8String aTypeHeader,
1.31 + out AUTF8String aCharset,
1.32 + out boolean aHadCharset);
1.33 +
1.34 + /**
1.35 + * Test whether the given URI's handler has the given protocol flags.
1.36 + *
1.37 + * @param aURI the URI in question
1.38 + * @param aFlags the flags we're testing for.
1.39 + *
1.40 + * @return whether the protocol handler for aURI has all the flags
1.41 + * in aFlags.
1.42 + */
1.43 + boolean protocolHasFlags(in nsIURI aURI, in unsigned long aFlag);
1.44 +
1.45 + /**
1.46 + * Test whether the protocol handler for this URI or that for any of
1.47 + * its inner URIs has the given protocol flags. This will QI aURI to
1.48 + * nsINestedURI and walk the nested URI chain.
1.49 + *
1.50 + * @param aURI the URI in question
1.51 + * @param aFlags the flags we're testing for.
1.52 + *
1.53 + * @return whether any of the protocol handlers involved have all the flags
1.54 + * in aFlags.
1.55 + */
1.56 + boolean URIChainHasFlags(in nsIURI aURI, in unsigned long aFlags);
1.57 +
1.58 + /**
1.59 + * Take aURI and produce an immutable version of it for the caller. If aURI
1.60 + * is immutable this will be aURI itself; otherwise this will be a clone,
1.61 + * marked immutable if possible. Passing null to this method is allowed; in
1.62 + * that case it will return null.
1.63 + */
1.64 + nsIURI toImmutableURI(in nsIURI aURI);
1.65 +
1.66 + /**
1.67 + * Create a simple nested URI using the result of
1.68 + * toImmutableURI on the passed-in aURI which may not be null.
1.69 + * Note: The return URI will not have had its spec set yet.
1.70 + */
1.71 + nsIURI newSimpleNestedURI(in nsIURI aURI);
1.72 +
1.73 + /** Escape every character with its %XX-escaped equivalent */
1.74 + const unsigned long ESCAPE_ALL = 0;
1.75 +
1.76 + /** Leave alphanumeric characters intact and %XX-escape all others */
1.77 + const unsigned long ESCAPE_XALPHAS = 1;
1.78 +
1.79 + /** Leave alphanumeric characters intact, convert spaces to '+',
1.80 + %XX-escape all others */
1.81 + const unsigned long ESCAPE_XPALPHAS = 2;
1.82 +
1.83 + /** Leave alphanumeric characters and forward slashes intact,
1.84 + %XX-escape all others */
1.85 + const unsigned long ESCAPE_URL_PATH = 4;
1.86 +
1.87 + /**
1.88 + * escape a string with %00-style escaping
1.89 + */
1.90 + ACString escapeString(in ACString aString, in unsigned long aEscapeType);
1.91 +
1.92 + /** %XX-escape URL scheme */
1.93 + const unsigned long ESCAPE_URL_SCHEME = 1;
1.94 +
1.95 + /** %XX-escape username in the URL */
1.96 + const unsigned long ESCAPE_URL_USERNAME = 1 << 1;
1.97 +
1.98 + /** %XX-escape password in the URL */
1.99 + const unsigned long ESCAPE_URL_PASSWORD = 1 << 2;
1.100 +
1.101 + /** %XX-escape URL host */
1.102 + const unsigned long ESCAPE_URL_HOST = 1 << 3;
1.103 +
1.104 + /** %XX-escape URL directory */
1.105 + const unsigned long ESCAPE_URL_DIRECTORY = 1 << 4;
1.106 +
1.107 + /** %XX-escape file basename in the URL */
1.108 + const unsigned long ESCAPE_URL_FILE_BASENAME = 1 << 5;
1.109 +
1.110 + /** %XX-escape file extension in the URL */
1.111 + const unsigned long ESCAPE_URL_FILE_EXTENSION = 1 << 6;
1.112 +
1.113 + /** %XX-escape URL parameters */
1.114 + const unsigned long ESCAPE_URL_PARAM = 1 << 7;
1.115 +
1.116 + /** %XX-escape URL query */
1.117 + const unsigned long ESCAPE_URL_QUERY = 1 << 8;
1.118 +
1.119 + /** %XX-escape URL ref */
1.120 + const unsigned long ESCAPE_URL_REF = 1 << 9;
1.121 +
1.122 + /** %XX-escape URL path - same as escaping directory, basename and extension */
1.123 + const unsigned long ESCAPE_URL_FILEPATH =
1.124 + ESCAPE_URL_DIRECTORY | ESCAPE_URL_FILE_BASENAME | ESCAPE_URL_FILE_EXTENSION;
1.125 +
1.126 + /** %XX-escape scheme, username, password, host, path, params, query and ref */
1.127 + const unsigned long ESCAPE_URL_MINIMAL =
1.128 + ESCAPE_URL_SCHEME | ESCAPE_URL_USERNAME | ESCAPE_URL_PASSWORD |
1.129 + ESCAPE_URL_HOST | ESCAPE_URL_FILEPATH | ESCAPE_URL_PARAM |
1.130 + ESCAPE_URL_QUERY | ESCAPE_URL_REF;
1.131 +
1.132 + /** Force %XX-escaping of already escaped sequences */
1.133 + const unsigned long ESCAPE_URL_FORCED = 1 << 10;
1.134 +
1.135 + /** Skip non-ascii octets, %XX-escape all others */
1.136 + const unsigned long ESCAPE_URL_ONLY_ASCII = 1 << 11;
1.137 +
1.138 + /**
1.139 + * Skip graphic octets (0x20-0x7E) when escaping
1.140 + * Skips all ASCII octets (0x00-0x7F) when unescaping
1.141 + */
1.142 + const unsigned long ESCAPE_URL_ONLY_NONASCII = 1 << 12;
1.143 +
1.144 + /** Force %XX-escape of colon */
1.145 + const unsigned long ESCAPE_URL_COLON = 1 << 14;
1.146 +
1.147 + /** Skip C0 and DEL from unescaping */
1.148 + const unsigned long ESCAPE_URL_SKIP_CONTROL = 1 << 15;
1.149 +
1.150 + /**
1.151 + * %XX-Escape invalid chars in a URL segment.
1.152 + *
1.153 + * @param aStr the URL to be escaped
1.154 + * @param aFlags the URL segment type flags
1.155 + *
1.156 + * @return the escaped string (the string itself if escaping did not happen)
1.157 + *
1.158 + */
1.159 + ACString escapeURL(in ACString aStr, in unsigned long aFlags);
1.160 +
1.161 + /**
1.162 + * Expands URL escape sequences
1.163 + *
1.164 + * @param aStr the URL to be unescaped
1.165 + * @param aFlags only ESCAPE_URL_ONLY_NONASCII and ESCAPE_URL_SKIP_CONTROL
1.166 + * are recognized. If |aFlags| is 0 all escape sequences are
1.167 + * unescaped
1.168 + * @return unescaped string
1.169 + */
1.170 + ACString unescapeString(in AUTF8String aStr, in unsigned long aFlags);
1.171 +
1.172 + /**
1.173 + * Extract the charset parameter location and value from a content-type
1.174 + * header.
1.175 + *
1.176 + * @param aTypeHeader the header string to parse
1.177 + * @param [out] aCharset the charset parameter specified in the
1.178 + * header, if any.
1.179 + * @param [out] aCharsetStart index of the start of the charset parameter
1.180 + * (the ';' separating it from what came before) in aTypeHeader.
1.181 + * If this function returns false, this argument will still be
1.182 + * set, to the index of the location where a new charset should
1.183 + * be inserted.
1.184 + * @param [out] aCharsetEnd index of the end of the charset parameter (the
1.185 + * ';' separating it from what comes after, or the end
1.186 + * of the string) in aTypeHeader. If this function returns
1.187 + * false, this argument will still be set, to the index of the
1.188 + * location where a new charset should be inserted.
1.189 + *
1.190 + * @return whether a charset parameter was found. This can be false even in
1.191 + * cases when parseContentType would claim to have a charset, if the type
1.192 + * that won out does not have a charset parameter specified.
1.193 + */
1.194 + boolean extractCharsetFromContentType(in AUTF8String aTypeHeader,
1.195 + out AUTF8String aCharset,
1.196 + out long aCharsetStart,
1.197 + out long aCharsetEnd);
1.198 +};
