filename_util.h 6.2 KB

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