[net] Cleanup filename_util and make it portable.

net/base/filename_util.h

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef NET_BASE_FILENAME_UTIL_H_
 #define NET_BASE_FILENAME_UTIL_H_
 
 #include <string>
 
 #include "base/strings/string16.h"
@@ skipping 21 matching lines @@
 // order):
 //
 // 1) The raw Content-Disposition header in |content_disposition| as read from
 //    the network.  |referrer_charset| is used to decode non-ASCII strings.
 // 2) |suggested_name| if specified.  |suggested_name| is assumed to be in
 //    UTF-8.
 // 3) The filename extracted from the |url|.  |referrer_charset| will be used to
 //    interpret the URL if there are non-ascii characters.
 // 4) |default_name|.  If non-empty, |default_name| is assumed to be a filename
 //    and shouldn't contain a path.  |default_name| is not subject to validation
-//    or sanitization, and therefore shouldn't be a user supplied string.
-// 5) The hostname portion from the |url|
+//    or sanitization, and therefore shouldn't be a user supplied string. It is
+//    assumed to be in UTF-8.
+// 5) The hostname portion from the |url|.
+// 6) The string "download".
 //
-// Then, leading and trailing '.'s will be removed.  On Windows, trailing spaces
-// are also removed.  The string "download" is the final fallback if no filename
-// is found or the filename is empty.
-//
-// Any illegal characters in the filename will be replaced by '-'.  If the
-// filename doesn't contain an extension, and a |mime_type| is specified, the
-// preferred extension for the |mime_type| will be appended to the filename.
-// The resulting filename is then checked against a list of reserved names on
-// Windows.  If the name is reserved, an underscore will be prepended to the
-// filename.
+// Any illegal characters in the filename will be replaced by '_'. This includes
+// Ileading and trailing whitespace and periods. If the filename doesn't contain
+// an extension, and a |mime_type| is specified, the preferred extension for the
+// |mime_type| will be appended to the filename.  The resulting filename is then
+// checked against a list of reserved names on Windows.  If the name is
+// reserved, an underscore will be prepended to the filename.
 //
 // Note: |mime_type| should only be specified if this function is called from a
 // thread that allows IO.
-NET_EXPORT base::string16 GetSuggestedFilename(
-    const GURL& url,
-    const std::string& content_disposition,
-    const std::string& referrer_charset,
-    const std::string& suggested_name,
-    const std::string& mime_type,
-    const std::string& default_name);
-
-// Similar to GetSuggestedFilename(), but returns a FilePath.
 NET_EXPORT base::FilePath GenerateFileName(
     const GURL& url,
     const std::string& content_disposition,
     const std::string& referrer_charset,
     const std::string& suggested_name,
     const std::string& mime_type,
     const std::string& default_name);
 
 // Valid components:
 // * are not empty
 // * are not Windows reserved names (CON, NUL.zip, etc.)
 // * do not have trailing separators
 // * do not equal kCurrentDirectory
 // * do not reference the parent directory
 // * do not contain illegal characters
 // * do not end with Windows shell-integrated extensions (even on posix)
 // * do not begin with '.' (which would hide them in most file managers)
 // * do not end with ' ' or '.'
 NET_EXPORT bool IsSafePortablePathComponent(const base::FilePath& component);
 
 // Basenames of valid relative paths are IsSafePortableBasename(), and internal
 // path components of valid relative paths are valid path components as
 // described above IsSafePortableBasename(). Valid relative paths are not
 // absolute paths.
 NET_EXPORT bool IsSafePortableRelativePath(const base::FilePath& path);
 
+// Options controlling how filename extensions are handled in
+// EnsureSafePortableFileName().
+enum ExtensionGenerationOption {
+  EXTENSION_OPTION_KEEP_EXISTING,        // Don't generate a new extension.
+  EXTENSION_OPTION_GENERATE_IF_MISSING,  // Generate one if the filename doesn't
+                                         // already have an extension.
+  EXTENSION_OPTION_GENERATE,  // Always generate a new extension and replace the
+                              // existing extension.
+  EXTENSION_OPTION_GENERATE_AND_APPEND  // Generate a new extension and append
+                                        // it to the filename.
+};
+
 // Ensures that the filename and extension is safe to use in the filesystem.
 //
-// Assumes that |file_path| already contains a valid path or file name.  On
-// Windows if the extension causes the file to have an unsafe interaction with
-// the shell (see net_util::IsShellIntegratedExtension()), then it will be
-// replaced by the string 'download'.  If |file_path| doesn't contain an
-// extension or |ignore_extension| is true then the preferred extension, if one
-// exists, for |mime_type| will be used as the extension.
+// Note that this function only sanitizes the basename of |file_path|. I.e. it
+// assumes that the path leading up to the parent directory of |file_path| is
+// valid.
 //
-// On Windows, the filename will be checked against a set of reserved names, and
-// if so, an underscore will be prepended to the name.
+// This function:
 //
-// |file_name| can either be just the file name or it can be a full path to a
-// file.
+// - Updates |file_path| with a valid filename extension if |mime_type| is known
+//   and |extension_option| specifies that an extension should be generated.
+//
+// - Replaces the extension with the string 'download' if the filename extension
+//   is considered to be one which interacts with the Windows shell in an unsafe
+//   manner.
+//
+// - Prepends an underscore to the filename if the filename will be considered a
+//   device name or is otherwise reserved on Windows.
+//
+// - Replaces any illegal characters in the filename with underscores. This
+//   includes leading and trailing whitespace and periods.
 //
 // Note: |mime_type| should only be non-empty if this function is called from a
 // thread that allows IO.
-NET_EXPORT void GenerateSafeFileName(const std::string& mime_type,
-                                     bool ignore_extension,
-                                     base::FilePath* file_path);
+NET_EXPORT void EnsureSafePortableFileName(
+    const std::string& mime_type,
+    ExtensionGenerationOption extension_option,
+    base::FilePath* file_path);
 
 }  // namespace net
 
 #endif  // NET_BASE_FILENAME_UTIL_H_