net/base/filename_util.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef NET_BASE_FILENAME_UTIL_H_
   6 #define NET_BASE_FILENAME_UTIL_H_
   7
   8 #include <string>
   9
  10 #include "base/files/file_path.h"
  11 #include "base/strings/string16.h"
  12 #include "net/base/net_export.h"
  13
  14 class GURL;
  15
  16 namespace base {
  17 class FilePath;
  18 }
  19
  20 namespace  net {
  21
  22 // Given the full path to a file name, creates a file: URL. The returned URL
  23 // may not be valid if the input is malformed.
  24 NET_EXPORT GURL FilePathToFileURL(const base::FilePath& path);
  25
  26 // Converts a file: URL back to a filename that can be passed to the OS. The
  27 // file URL must be well-formed (GURL::is_valid() must return true); we don't
  28 // handle degenerate cases here. Returns true on success, false if it isn't a
  29 // valid file URL. On failure, *file_path will be empty.
  30 NET_EXPORT bool FileURLToFilePath(const GURL& url, base::FilePath* file_path);
  31
  32 // Generates a filename using the first successful method from the following (in
  33 // order):
  34 //
  35 // 1) The raw Content-Disposition header in |content_disposition| as read from
  36 //    the network.  |referrer_charset| is used to decode non-ASCII strings.
  37 // 2) |suggested_name| if specified.  |suggested_name| is assumed to be in
  38 //    UTF-8.
  39 // 3) The filename extracted from the |url|.  |referrer_charset| will be used to
  40 //    interpret the URL if there are non-ascii characters.
  41 // 4) |default_name|.  If non-empty, |default_name| is assumed to be a filename
  42 //    and shouldn't contain a path.  |default_name| is not subject to validation
  43 //    or sanitization, and therefore shouldn't be a user supplied string.
  44 // 5) The hostname portion from the |url|
  45 //
  46 // Then, leading and trailing '.'s will be removed.  On Windows, trailing spaces
  47 // are also removed.  The string "download" is the final fallback if no filename
  48 // is found or the filename is empty.
  49 //
  50 // Any illegal characters in the filename will be replaced by '-'.  If the
  51 // filename doesn't contain an extension, and a |mime_type| is specified, the
  52 // preferred extension for the |mime_type| will be appended to the filename.
  53 // The resulting filename is then checked against a list of reserved names on
  54 // Windows.  If the name is reserved, an underscore will be prepended to the
  55 // filename.
  56 //
  57 // Note: |mime_type| should only be specified if this function is called from a
  58 // thread that allows IO.
  59 NET_EXPORT base::string16 GetSuggestedFilename(
  60     const GURL& url,
  61     const std::string& content_disposition,
  62     const std::string& referrer_charset,
  63     const std::string& suggested_name,
  64     const std::string& mime_type,
  65     const std::string& default_name);
  66
  67 // Similar to GetSuggestedFilename(), but returns a FilePath.
  68 NET_EXPORT base::FilePath GenerateFileName(
  69     const GURL& url,
  70     const std::string& content_disposition,
  71     const std::string& referrer_charset,
  72     const std::string& suggested_name,
  73     const std::string& mime_type,
  74     const std::string& default_name);
  75
  76 // Valid components:
  77 // * are not empty
  78 // * are not Windows reserved names (CON, NUL.zip, etc.)
  79 // * do not have trailing separators
  80 // * do not equal kCurrentDirectory
  81 // * do not reference the parent directory
  82 // * do not contain illegal characters
  83 // * do not end with Windows shell-integrated extensions (even on posix)
  84 // * do not begin with '.' (which would hide them in most file managers)
  85 // * do not end with ' ' or '.'
  86 NET_EXPORT bool IsSafePortablePathComponent(const base::FilePath& component);
  87
  88 // Basenames of valid relative paths are IsSafePortableBasename(), and internal
  89 // path components of valid relative paths are valid path components as
  90 // described above IsSafePortableBasename(). Valid relative paths are not
  91 // absolute paths.
  92 NET_EXPORT bool IsSafePortableRelativePath(const base::FilePath& path);
  93
  94 // Ensures that the filename and extension is safe to use in the filesystem.
  95 //
  96 // Assumes that |file_path| already contains a valid path or file name.  On
  97 // Windows if the extension causes the file to have an unsafe interaction with
  98 // the shell (see net_util::IsShellIntegratedExtension()), then it will be
  99 // replaced by the string 'download'.  If |file_path| doesn't contain an
 100 // extension or |ignore_extension| is true then the preferred extension, if one
 101 // exists, for |mime_type| will be used as the extension.
 102 //
 103 // On Windows, the filename will be checked against a set of reserved names, and
 104 // if so, an underscore will be prepended to the name.
 105 //
 106 // |file_name| can either be just the file name or it can be a full path to a
 107 // file.
 108 //
 109 // Note: |mime_type| should only be non-empty if this function is called from a
 110 // thread that allows IO.
 111 NET_EXPORT void GenerateSafeFileName(const std::string& mime_type,
 112                                      bool ignore_extension,
 113                                      base::FilePath* file_path);
 114
 115 // Returns whether the specified file name is a reserved name on Windows.
 116 // This includes names like "com2.zip" (which correspond to devices) and
 117 // desktop.ini and thumbs.db which have special meaning to the Windows shell.
 118 // Even on other platforms, this will return whether or not a file name is
 119 // reserved on Windows.
 120 NET_EXPORT bool IsReservedNameOnWindows(
 121     const base::FilePath::StringType& filename);
 122
 123 }  // namespace net
 124
 125 #endif  // NET_BASE_FILENAME_UTIL_H_