intl/uconv/idl/nsIUTF8ConverterService.idl@b8a032363ba2 (annotated)
intl/uconv/idl/nsIUTF8ConverterService.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| michael@0 | 2 | /* vim:expandtab:shiftwidth=4:tabstop=4: |
| michael@0 | 3 | */ |
| michael@0 | 4 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 5 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 6 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 7 | |
| michael@0 | 8 | #include "nsISupports.idl" |
| michael@0 | 9 | |
| michael@0 | 10 | [scriptable, uuid(249f52a3-2599-4b00-ba40-0481364831a2)] |
| michael@0 | 11 | interface nsIUTF8ConverterService : nsISupports |
| michael@0 | 12 | { |
| michael@0 | 13 | /** |
| michael@0 | 14 | * Ensure that |aString| is encoded in UTF-8. If not, |
| michael@0 | 15 | * convert to UTF-8 assuming it's encoded in |aCharset| |
| michael@0 | 16 | * and return the converted string in UTF-8. |
| michael@0 | 17 | * |
| michael@0 | 18 | * @param aString a string to ensure its UTF8ness |
| michael@0 | 19 | * @param aCharset the charset to convert from if |aString| is not in UTF-8 |
| michael@0 | 20 | * @param aSkipCheck determines whether or not to skip 'ASCIIness' and |
| michael@0 | 21 | * 'UTF8ness' check. Set this to PR_TRUE only if you suspect that |
| michael@0 | 22 | * aString can be mistaken for ASCII / UTF-8 but is actually NOT |
| michael@0 | 23 | * in ASCII / UTF-8 so that aString has to go through the conversion. |
| michael@0 | 24 | * skipping ASCIIness/UTF8ness check. |
| michael@0 | 25 | * The most common case is the input is in 7bit non-ASCII charsets |
| michael@0 | 26 | * like ISO-2022-JP, HZ or UTF-7 (in its original form or |
| michael@0 | 27 | * a modified form used in IMAP folder names). |
| michael@0 | 28 | * @param aAllowSubstitution when true, allow the decoder to substitute |
| michael@0 | 29 | * invalid input sequences by replacement characters (defaults to |
| michael@0 | 30 | * true) |
| michael@0 | 31 | * @return the converted string in UTF-8. |
| michael@0 | 32 | * @throws NS_ERROR_UCONV_NOCONV when there is no decoder for aCharset |
| michael@0 | 33 | * or error code of nsIUnicodeDecoder in case of conversion failure |
| michael@0 | 34 | */ |
| michael@0 | 35 | |
| michael@0 | 36 | [optional_argc] |
| michael@0 | 37 | AUTF8String convertStringToUTF8(in ACString aString, |
| michael@0 | 38 | in string aCharset, |
| michael@0 | 39 | in boolean aSkipCheck, |
| michael@0 | 40 | [optional] in boolean aAllowSubstitution); |
| michael@0 | 41 | |
| michael@0 | 42 | /* XXX : To-be-added. convertStringFromUTF8 */ |
| michael@0 | 43 | |
| michael@0 | 44 | /** |
| michael@0 | 45 | * Ensure that |aSpec| (after URL-unescaping it) is encoded in UTF-8. |
| michael@0 | 46 | * If not, convert it to UTF-8, assuming it's encoded in |aCharset|, |
| michael@0 | 47 | * and return the result. |
| michael@0 | 48 | * |
| michael@0 | 49 | * <p>Make sure that all characters outside US-ASCII in your input spec |
| michael@0 | 50 | * are url-escaped if your spec is not in UTF-8 (before url-escaping) |
| michael@0 | 51 | * because the presence of non-ASCII characters is <strong>blindly</strong> |
| michael@0 | 52 | * regarded as an indication that your input spec is in unescaped UTF-8 |
| michael@0 | 53 | * and it will be returned without further processing. No valid spec |
| michael@0 | 54 | * going around in Mozilla code would break this assumption. |
| michael@0 | 55 | * |
| michael@0 | 56 | * <p>XXX The above may change in the future depending on the usage pattern. |
| michael@0 | 57 | * |
| michael@0 | 58 | * @param aSpec an url-escaped URI spec to ensure its UTF8ness |
| michael@0 | 59 | * @param aCharset the charset to convert from if |aSpec| is not in UTF-8 |
| michael@0 | 60 | * @return the converted spec in UTF-8. |
| michael@0 | 61 | * @throws NS_ERROR_UCONV_NOCONV when there is no decoder for aCharset |
| michael@0 | 62 | * or error code of nsIUnicodeDecoder in case of conversion failure |
| michael@0 | 63 | */ |
| michael@0 | 64 | |
| michael@0 | 65 | AUTF8String convertURISpecToUTF8(in ACString aSpec, |
| michael@0 | 66 | in string aCharset); |
| michael@0 | 67 | }; |
| michael@0 | 68 |
