mozilla
/
gecko-dev
зеркало из https://github.com/mozilla/gecko-dev.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность
gecko-dev/dom/system/IOUtils.h

483 строки
17 KiB
C++
Исходник Ответственный История

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#ifndef mozilla_dom_IOUtils__
#define mozilla_dom_IOUtils__
#include "mozilla/AlreadyAddRefed.h"
#include "mozilla/Attributes.h"
#include "mozilla/Buffer.h"
#include "mozilla/DataMutex.h"
#include "mozilla/MozPromise.h"
#include "mozilla/Result.h"
#include "mozilla/dom/BindingDeclarations.h"
#include "mozilla/dom/IOUtilsBinding.h"
#include "mozilla/dom/TypedArray.h"
#include "nsIAsyncShutdown.h"
#include "nsISerialEventTarget.h"
#include "nsPrintfCString.h"
#include "nsString.h"
#include "nsStringFwd.h"
#include "nsTArray.h"
#include "prio.h"
namespace mozilla {
/**
* Utility class to be used with |UniquePtr| to automatically close NSPR file
* descriptors when they go out of scope.
*
* Example:
*
* UniquePtr<PRFileDesc, PR_CloseDelete> fd = PR_Open(path, flags, mode);
*/
class PR_CloseDelete {
public:
constexpr PR_CloseDelete() = default;
PR_CloseDelete(const PR_CloseDelete& aOther) = default;
PR_CloseDelete(PR_CloseDelete&& aOther) = default;
PR_CloseDelete& operator=(const PR_CloseDelete& aOther) = default;
PR_CloseDelete& operator=(PR_CloseDelete&& aOther) = default;
void operator()(PRFileDesc* aPtr) const { PR_Close(aPtr); }
};
namespace dom {
/**
* Implementation for the Web IDL interface at dom/chrome-webidl/IOUtils.webidl.
* Methods of this class must only be called from the parent process.
*/
class IOUtils final {
public:
class IOError;
static already_AddRefed<Promise> Read(GlobalObject& aGlobal,
const nsAString& aPath,
const ReadOptions& aOptions);
static already_AddRefed<Promise> ReadUTF8(GlobalObject& aGlobal,
const nsAString& aPath,
const ReadUTF8Options& aOptions);
static already_AddRefed<Promise> Write(GlobalObject& aGlobal,
const nsAString& aPath,
const Uint8Array& aData,
const WriteOptions& aOptions);
static already_AddRefed<Promise> WriteUTF8(GlobalObject& aGlobal,
const nsAString& aPath,
const nsAString& aString,
const WriteOptions& aOptions);
static already_AddRefed<Promise> Move(GlobalObject& aGlobal,
const nsAString& aSourcePath,
const nsAString& aDestPath,
const MoveOptions& aOptions);
static already_AddRefed<Promise> Remove(GlobalObject& aGlobal,
const nsAString& aPath,
const RemoveOptions& aOptions);
static already_AddRefed<Promise> MakeDirectory(
GlobalObject& aGlobal, const nsAString& aPath,
const MakeDirectoryOptions& aOptions);
static already_AddRefed<Promise> Stat(GlobalObject& aGlobal,
const nsAString& aPath);
static already_AddRefed<Promise> Copy(GlobalObject& aGlobal,
const nsAString& aSourcePath,
const nsAString& aDestPath,
const CopyOptions& aOptions);
static already_AddRefed<Promise> Touch(
GlobalObject& aGlobal, const nsAString& aPath,
const Optional<int64_t>& aModification);
static already_AddRefed<Promise> GetChildren(GlobalObject& aGlobal,
const nsAString& aPath);
static already_AddRefed<Promise> SetPermissions(GlobalObject& aGlobal,
const nsAString& aPath,
const uint32_t aPermissions);
static already_AddRefed<Promise> Exists(GlobalObject& aGlobal,
const nsAString& aPath);
private:
~IOUtils() = default;
template <typename T>
using IOPromise = MozPromise<T, IOError, true>;
friend class IOUtilsShutdownBlocker;
struct InternalFileInfo;
struct InternalWriteOpts;
class MozLZ4;
static StaticDataMutex<StaticRefPtr<nsISerialEventTarget>>
sBackgroundEventTarget;
static StaticRefPtr<nsIAsyncShutdownClient> sBarrier;
static Atomic<bool> sShutdownStarted;
template <typename OkT, typename Fn, typename... Args>
static RefPtr<IOUtils::IOPromise<OkT>> InvokeToIOPromise(Fn aFunc,
Args... aArgs);
static already_AddRefed<nsIAsyncShutdownClient> GetShutdownBarrier();
static already_AddRefed<nsISerialEventTarget> GetBackgroundEventTarget();
static void SetShutdownHooks();
template <typename OkT, typename Fn>
static void RunOnBackgroundThread(Promise* aPromise, Fn aFunc);
/**
* Creates a new JS Promise.
*
* @return The new promise, or |nullptr| on failure.
*/
static already_AddRefed<Promise> CreateJSPromise(GlobalObject& aGlobal);
// Allow conversion of |InternalFileInfo| with |ToJSValue|.
friend MOZ_MUST_USE bool ToJSValue(JSContext* aCx,
const InternalFileInfo& aInternalFileInfo,
JS::MutableHandle<JS::Value> aValue);
/**
* Resolves |aPromise| with an appropriate JS value for |aValue|.
*/
template <typename T>
static void ResolveJSPromise(Promise* aPromise, const T& aValue);
/**
* Rejects |aPromise| with an appropriate |DOMException| describing |aError|.
*/
static void RejectJSPromise(Promise* aPromise, const IOError& aError);
/**
* Attempts to read the entire file at |aPath| into a buffer.
*
* @param aFile The location of the file.
* @param aMaxBytes If |Some|, then only read up this this number of bytes,
* otherwise attempt to read the whole file.
* @param aDecompress If true, decompress the bytes read from disk before
* returning the result to the caller.
*
* @return A byte array of the entire (decompressed) file contents, or an
* error.
*/
static Result<nsTArray<uint8_t>, IOError> ReadSync(
nsIFile* aFile, const Maybe<uint32_t>& aMaxBytes, const bool aDecompress);
/**
* Attempts to read the entire file at |aPath| as a UTF-8 string.
*
* @param aFile The location of the file.
* @param aDecompress If true, decompress the bytes read from disk before
* returning the result to the caller.
*
* @return The (decompressed) contents of the file re-encoded as a UTF-16
* string.
*/
static Result<nsString, IOError> ReadUTF8Sync(nsIFile* aFile,
const bool aDecompress);
/**
* Attempt to write the entirety of |aByteArray| to the file at |aPath|.
* This may occur by writing to an intermediate destination and performing a
* move, depending on |aOptions|.
*
* @param aFile The location of the file.
* @param aByteArray The data to write to the file.
* @param aOptions Options to modify the way the write is completed.
*
* @return The number of bytes written to the file, or an error if the write
* failed or was incomplete.
*/
static Result<uint32_t, IOError> WriteSync(
nsIFile* aFile, const Span<const uint8_t>& aByteArray,
const InternalWriteOpts& aOptions);
/**
* Attempt to write the entirety of |aUTF8String| to the file at |aFile|.
* This may occur by writing to an intermediate destination and performing a
* move, depending on |aOptions|.
*
* @param aFile The location of the file.
* @param aByteArray The data to write to the file.
* @param aOptions Options to modify the way the write is completed.
*
* @return The number of bytes written to the file, or an error if the write
* failed or was incomplete.
*/
static Result<uint32_t, IOError> WriteUTF8Sync(
nsIFile* aFile, const nsCString& aUTF8String,
const InternalWriteOpts& aOptions);
/**
* Attempts to move the file located at |aSourceFile| to |aDestFile|.
*
* @param aSourceFile The location of the file to move.
* @param aDestFile The destination for the file.
* @param noOverWrite If true, abort with an error if a file already exists at
* |aDestFile|. Otherwise, the file will be overwritten by
* the move.
*
* @return Ok if the file was moved successfully, or an error.
*/
static Result<Ok, IOError> MoveSync(nsIFile* aSourceFile, nsIFile* aDestFile,
bool aNoOverwrite);
/**
* Attempts to copy the file at |aSourceFile| to |aDestFile|.
*
* @param aSourceFile The location of the file to copy.
* @param aDestFile The destination that the file will be copied to.
*
* @return Ok if the operation was successful, or an error.
*/
static Result<Ok, IOError> CopySync(nsIFile* aSourceFile, nsIFile* aDestFile,
bool aNoOverWrite, bool aRecursive);
/**
* Provides the implementation for |CopySync| and |MoveSync|.
*
* @param aMethod A pointer to one of |nsIFile::MoveTo| or |CopyTo|
* instance methods.
* @param aMethodName The name of the method to the performed. Either "move"
* or "copy".
* @param aSource The source file to be copied or moved.
* @param aDest The destination file.
* @param aNoOverwrite If true, allow overwriting |aDest| during the copy or
* move. Otherwise, abort with an error if the file would
* be overwritten.
*
* @return Ok if the operation was successful, or an error.
*/
template <typename CopyOrMoveFn>
static Result<Ok, IOError> CopyOrMoveSync(CopyOrMoveFn aMethod,
const char* aMethodName,
nsIFile* aSource, nsIFile* aDest,
bool aNoOverwrite);
/**
* Attempts to remove the file located at |aFile|.
*
* @param aFile The location of the file.
* @param aIgnoreAbsent If true, suppress errors due to an absent target file.
* @param aRecursive If true, attempt to recursively remove descendant
* files. This option is safe to use even if the target
* is not a directory.
*
* @return Ok if the file was removed successfully, or an error.
*/
static Result<Ok, IOError> RemoveSync(nsIFile* aFile, bool aIgnoreAbsent,
bool aRecursive);
/**
* Attempts to create a new directory at |aFile|.
*
* @param aFile The location of the directory to create.
* @param aCreateAncestors If true, create missing ancestor directories as
* needed. Otherwise, report an error if the target
* has non-existing ancestor directories.
* @param aIgnoreExisting If true, suppress errors that occur if the target
* directory already exists. Otherwise, propagate the
* error if it occurs.
* @param aMode Optional file mode. Defaults to 0777 to allow the
* system umask to compute the best mode for the new
* directory.
*
* @return Ok if the directory was created successfully, or an error.
*/
static Result<Ok, IOError> MakeDirectorySync(nsIFile* aFile,
bool aCreateAncestors,
bool aIgnoreExisting,
int32_t aMode = 0777);
/**
* Attempts to stat a file at |aFile|.
*
* @param aFile The location of the file.
*
* @return An |InternalFileInfo| struct if successful, or an error.
*/
static Result<IOUtils::InternalFileInfo, IOError> StatSync(nsIFile* aFile);
/**
* Attempts to update the last modification time of the file at |aFile|.
*
* @param aFile The location of the file.
* @param aNewModTime Some value in milliseconds since Epoch. For the current
* system time, use |Nothing|.
*
* @return Timestamp of the file if the operation was successful, or an error.
*/
static Result<int64_t, IOError> TouchSync(nsIFile* aFile,
const Maybe<int64_t>& aNewModTime);
/**
* Returns the immediate children of the directory at |aFile|, if any.
*
* @param aFile The location of the directory.
*
* @return An array of absolute paths identifying the children of |aFile|.
* If there are no children, an empty array. Otherwise, an error.
*/
static Result<nsTArray<nsString>, IOError> GetChildrenSync(nsIFile* aFile);
/**
* Set the permissions of the given file.
*
* Windows does not make a distinction between user, group, and other
* permissions like UNICES do. If a permission flag is set for any of user,
* group, or other has a permission, then all users will have that
* permission.
*
* @param aFile The location of the file.
* @param aPermissions The permissions to set, as a UNIX file mode.
*
* @return |Ok| if the permissions were successfully set, or an error.
*/
static Result<Ok, IOError> SetPermissionsSync(nsIFile* aFile,
const uint32_t aPermissions);
/**
* Return whether or not the file exists.
*
* @param aFile The location of the file.
*
* @return Whether or not the file exists.
*/
static Result<bool, IOError> ExistsSync(nsIFile* aFile);
};
/**
* An error class used with the |Result| type returned by most private |IOUtils|
* methods.
*/
class IOUtils::IOError {
public:
MOZ_IMPLICIT IOError(nsresult aCode) : mCode(aCode), mMessage(Nothing()) {}
/**
* Replaces the message associated with this error.
*/
template <typename... Args>
IOError WithMessage(const char* const aMessage, Args... aArgs) {
mMessage.emplace(nsPrintfCString(aMessage, aArgs...));
return *this;
}
IOError WithMessage(const char* const aMessage) {
mMessage.emplace(nsCString(aMessage));
return *this;
}
IOError WithMessage(const nsCString& aMessage) {
mMessage.emplace(aMessage);
return *this;
}
/**
* Returns the |nsresult| associated with this error.
*/
nsresult Code() const { return mCode; }
/**
* Maybe returns a message associated with this error.
*/
const Maybe<nsCString>& Message() const { return mMessage; }
private:
nsresult mCode;
Maybe<nsCString> mMessage;
};
/**
* This is an easier to work with representation of a |mozilla::dom::FileInfo|
* for private use in the IOUtils implementation.
*
* Because web IDL dictionaries are not easily copy/moveable, this class is
* used instead, until converted to the proper |mozilla::dom::FileInfo| before
* returning any results to JavaScript.
*/
struct IOUtils::InternalFileInfo {
nsString mPath;
FileType mType = FileType::Other;
uint64_t mSize = 0;
uint64_t mLastModified = 0;
Maybe<uint64_t> mCreationTime;
uint32_t mPermissions = 0;
};
/**
* This is an easier to work with representation of a
* |mozilla::dom::WriteOptions| for private use in the |IOUtils|
* implementation.
*
* Because web IDL dictionaries are not easily copy/moveable, this class is
* used instead.
*/
struct IOUtils::InternalWriteOpts {
RefPtr<nsIFile> mBackupFile;
RefPtr<nsIFile> mTmpFile;
bool mFlush = false;
bool mNoOverwrite = false;
bool mCompress = false;
static Result<InternalWriteOpts, IOUtils::IOError> FromBinding(
const WriteOptions& aOptions);
};
/**
* Re-implements the file compression and decompression utilities found
* in toolkit/components/lz4/lz4.js
*
* This implementation uses the non-standard data layout:
*
* - MAGIC_NUMBER (8 bytes)
* - content size (uint32_t, little endian)
* - content, as obtained from mozilla::Compression::LZ4::compress
*
* See bug 1209390 for more info.
*/
class IOUtils::MozLZ4 {
public:
static constexpr std::array<uint8_t, 8> MAGIC_NUMBER{
{'m', 'o', 'z', 'L', 'z', '4', '0', '\0'}};
static const uint32_t HEADER_SIZE = 8 + sizeof(uint32_t);
/**
* Compresses |aUncompressed| byte array, and returns a byte array with the
* correct format whose contents may be written to disk.
*/
static Result<nsTArray<uint8_t>, IOError> Compress(
Span<const uint8_t> aUncompressed);
/**
* Checks |aFileContents| for the correct file header, and returns the
* decompressed content.
*/
static Result<nsTArray<uint8_t>, IOError> Decompress(
Span<const uint8_t> aFileContents);
};
class IOUtilsShutdownBlocker : public nsIAsyncShutdownBlocker {
public:
NS_DECL_THREADSAFE_ISUPPORTS
NS_DECL_NSIASYNCSHUTDOWNBLOCKER
private:
virtual ~IOUtilsShutdownBlocker() = default;
};
} // namespace dom
} // namespace mozilla
#endif
Ссылка в новой задаче Показать git blame Копировать постоянную ссылку