Bug 1723807 - make getURLSpecFromFile [noscript] and clarify its idl comments to discourage use more forcefully, r=valentin,necko-reviewers
authorGijs Kruitbosch <gijskruitbosch@gmail.com>
Thu, 05 Aug 2021 08:52:28 +0000
changeset 587880 c9d056f74217636db2a43f263924cf5389f02754
parent 587879 475db96ce990c3a11411dc2222758f7e90e61ea4
child 587881 ee3a3769b412044574d4705a2483dbddd88fdfd3
push id38676
push userdluca@mozilla.com
push dateThu, 05 Aug 2021 16:34:46 +0000
treeherdermozilla-central@f5921ffeaee4 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersvalentin, necko-reviewers
bugs1723807
milestone92.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1723807 - make getURLSpecFromFile [noscript] and clarify its idl comments to discourage use more forcefully, r=valentin,necko-reviewers Differential Revision: https://phabricator.services.mozilla.com/D121781
netwerk/protocol/file/nsIFileProtocolHandler.idl
--- a/netwerk/protocol/file/nsIFileProtocolHandler.idl
+++ b/netwerk/protocol/file/nsIFileProtocolHandler.idl
@@ -25,40 +25,55 @@ interface nsIFileProtocolHandler : nsIPr
      * being cloned.
      *
      * @param aFile nsIFile
      * @return reference to a new nsIURIMutator object
      */
     nsIURIMutator newFileURIMutator(in nsIFile file);
 
     /**
-     * Converts the nsIFile to the corresponding URL string.  NOTE: under
-     * some platforms this is a lossy conversion (e.g., Mac Carbon build).
-     * If the nsIFile is a local file, then the result will be a file://
-     * URL string.
+     * DEPRECATED, AVOID IF AT ALL POSSIBLE.
+     *
+     * Calling this will cause IO on the calling thread, to determine
+     * if the file is a directory or file, and based on that behaves as
+     * if you called getURLSpecFromDir or getURLSpecFromActualFile,
+     * respectively. This IO may take multiple seconds (e.g. for network
+     * paths, slow external drives that need to be woken up, etc.).
+     *
+     * Usually, the caller should *know* that the `file` argument is
+     * either a directory (in which case it should call getURLSpecFromDir)
+     * or a non-directory file (in which case it should call
+     * getURLSpecFromActualFile), and not need to call this method.
+     */
+    [noscript] AUTF8String getURLSpecFromFile(in nsIFile file);
+
+    /**
+     * Converts a non-directory nsIFile to the corresponding URL string.
+     * NOTE: under some platforms this is a lossy conversion (e.g., Mac
+     * Carbon build). If the nsIFile is a local file, then the result
+     * will be a file:// URL string.
      *
      * The resulting string may contain URL-escaped characters.
-     * NOTE: Callers should use getURLSpecFromActualFile or
-     * getURLSpecFromDirFile if possible, for performance reasons.
-     */
-    AUTF8String getURLSpecFromFile(in nsIFile file);
-
-    /**
-     * Converts the nsIFile to the corresponding URL string. Should
-     * only be called on files which are not directories. Otherwise
-     * identical to getURLSpecFromFile, but is usually more efficient.
-     * WARNING: This restriction may not be enforced at runtime!
+     *
+     * Should only be called on files which are not directories. If
+     * called on directories, the resulting URL may lack a trailing slash
+     * and cause relative URLs in such a document to misbehave.
      */
     AUTF8String getURLSpecFromActualFile(in nsIFile file);
 
     /**
-     * Converts the nsIFile to the corresponding URL string. Should
-     * only be called on files which are directories. Otherwise
-     * identical to getURLSpecFromFile, but is usually more efficient.
-     * WARNING: This restriction may not be enforced at runtime!
+     * Converts a directory nsIFile to the corresponding URL string.
+     * NOTE: under some platforms this is a lossy conversion (e.g., Mac
+     * Carbon build). If the nsIFile is a local file, then the result
+     * will be a file:// URL string.
+     *
+     * The resulting string may contain URL-escaped characters.
+     *
+     * Should only be called on files which are directories (will enforce
+     * the URL ends with a slash).
      */
     AUTF8String getURLSpecFromDir(in nsIFile file);
 
     /**
      * Converts the URL string into the corresponding nsIFile if possible.
      * A local file will be created if the URL string begins with file://.
      */
     nsIFile getFileFromURLSpec(in AUTF8String url);