1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */ 3 /* This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this file, 5 * You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 #ifndef mozilla_dom_FileSystemTaskBase_h 8 #define mozilla_dom_FileSystemTaskBase_h 9 10 #include "mozilla/ErrorResult.h" 11 #include "mozilla/dom/FileSystemRequestParent.h" 12 #include "mozilla/dom/PFileSystemRequestChild.h" 13 #include "nsIIPCBackgroundChildCreateCallback.h" 14 #include "nsThreadUtils.h" 15 16 namespace mozilla { 17 namespace dom { 18 19 class BlobImpl; 20 class FileSystemBase; 21 class FileSystemParams; 22 class PBlobParent; 23 24 /* 25 * The base class to implement a Task class. 26 * The file system operations can only be performed in the parent process. In 27 * order to avoid duplicated code, we used PBackground for child-parent and 28 * parent-parent communications. 29 * 30 * The following diagram illustrates the how a API call from the content page 31 * starts a task and gets call back results. 32 * 33 * The left block is the call sequence inside any process loading content, while 34 * the right block is the call sequence only inside the parent process. 35 * 36 * Page 37 * | 38 * | (1) 39 * ______|_________________________ | _________________________________ 40 * | | | | | | 41 * | | | | | | 42 * | V | IPC | PBackground thread on | 43 * | [new FileSystemTaskChildBase()] | | | the parent process | 44 * | | | | | | 45 * | | (2) | | | 46 * | V | (3) | | 47 * | [GetRequestParams]------------------->[new FileSystemTaskParentBase()] | 48 * | | | | | 49 * | | | | | (4) _____________ | 50 * | | | | | | | | 51 * | | | | | | I/O Thread | | 52 * | | | | | | | | 53 * | | | | ---------> [IOWork] | | 54 * | | IPC | | | | | 55 * | | | | | | (5) | | 56 * | | | | -------------- | | 57 * | | | | | |_____________| | 58 * | | | | | | 59 * | | | | V | 60 * | | | | [HandleResult] | 61 * | | | | | | 62 * | | | | (6) | 63 * | | (7) | V | 64 * | [SetRequestResult]<---------------------[GetRequestResult] | 65 * | | | | | 66 * | | (8) | | | | 67 * | V | | | | 68 * |[HandlerCallback] | IPC | | 69 * |_______|_________________________| | |_________________________________| 70 * | | 71 * V 72 * Page 73 * 74 * 1. From the process that is handling the request 75 * Child/Parent (it can be in any process): 76 * (1) Call FileSystem API from content page with JS. Create a task and run. 77 * The base constructor [FileSystemTaskChildBase()] of the task should be 78 * called. 79 * (2) Forward the task to the parent process through the IPC and call 80 * [GetRequestParams] to prepare the parameters of the IPC. 81 * Parent: 82 * (3) The parent process receives IPC and handle it in 83 * FileystemRequestParent. Get the IPC parameters and create a task to run the 84 * IPC task. 85 * (4) The task operation will be performed in the member function of [IOWork]. 86 * A I/O thread will be created to run that function. If error occurs 87 * during the operation, call [SetError] to record the error and then abort. 88 * (5) After finishing the task operation, call [HandleResult] to send the 89 * result back to the child process though the IPC. 90 * (6) Call [GetRequestResult] request result to prepare the parameters of the 91 * IPC. Because the formats of the error result for different task are the 92 * same, FileSystemTaskChildBase can handle the error message without 93 * interfering. 94 * Each task only needs to implement its specific success result preparation 95 * function -[GetSuccessRequestResult]. 96 * Child/Parent: 97 * (7) The process receives IPC and calls [SetRequestResult] to get the 98 * task result. Each task needs to implement its specific success result 99 * parsing function [SetSuccessRequestResult] to get the success result. 100 * (8) Call [HandlerCallback] to send the task result to the content page. 101 */ 102 class FileSystemTaskChildBase : public PFileSystemRequestChild 103 , public nsIIPCBackgroundChildCreateCallback 104 { 105 public: 106 NS_DECL_ISUPPORTS 107 NS_DECL_NSIIPCBACKGROUNDCHILDCREATECALLBACK 108 109 /* 110 * Start the task. It will dispatch all the information to the parent process, 111 * PBackground thread. This method must be called from the owning thread. 112 */ 113 void 114 Start(); 115 116 /* 117 * The error codes are defined in xpcom/base/ErrorList.h and their 118 * corresponding error name and message are defined in dom/base/domerr.msg. 119 */ 120 void 121 SetError(const nsresult& aErrorCode); 122 123 FileSystemBase* 124 GetFileSystem() const; 125 126 /* 127 * After the task is completed, this function will be called to pass the task 128 * result to the content page. This method is called in the owning thread. 129 * Override this function to handle the call back to the content page. 130 */ 131 virtual void 132 HandlerCallback() = 0; 133 134 bool HasError()135 HasError() const { return NS_FAILED(mErrorValue); } 136 137 protected: 138 /* 139 * To create a task to handle the page content request. 140 */ 141 explicit FileSystemTaskChildBase(FileSystemBase* aFileSystem); 142 143 virtual 144 ~FileSystemTaskChildBase(); 145 146 /* 147 * Wrap the task parameter to FileSystemParams for sending it through IPC. 148 * It will be called when we need to forward a task from the child process to 149 * the parent process. This method runs in the owning thread. 150 * @param filesystem The string representation of the file system. 151 */ 152 virtual FileSystemParams 153 GetRequestParams(const nsString& aSerializedDOMPath, 154 ErrorResult& aRv) const = 0; 155 156 /* 157 * Unwrap the IPC message to get the task success result. 158 * It will be called when the task is completed successfully and an IPC 159 * message is received in the child process and we want to get the task 160 * success result. This method runs in the owning thread. 161 */ 162 virtual void 163 SetSuccessRequestResult(const FileSystemResponseValue& aValue, 164 ErrorResult& aRv) = 0; 165 166 // Overrides PFileSystemRequestChild 167 virtual bool 168 Recv__delete__(const FileSystemResponseValue& value) override; 169 170 nsresult mErrorValue; 171 RefPtr<FileSystemBase> mFileSystem; 172 173 private: 174 175 /* 176 * Unwrap the IPC message to get the task result. 177 * It will be called when the task is completed and an IPC message is received 178 * in the content process and we want to get the task result. This runs on the 179 * owning thread. 180 */ 181 void 182 SetRequestResult(const FileSystemResponseValue& aValue); 183 }; 184 185 // This class is the 'alter ego' of FileSystemTaskChildBase in the PBackground 186 // world. 187 class FileSystemTaskParentBase : public Runnable 188 { 189 public: 190 /* 191 * Start the task. This must be called from the PBackground thread only. 192 */ 193 void 194 Start(); 195 196 /* 197 * The error codes are defined in xpcom/base/ErrorList.h and their 198 * corresponding error name and message are defined in dom/base/domerr.msg. 199 */ 200 void 201 SetError(const nsresult& aErrorCode); 202 203 /* 204 * The function to perform task operation. It will be run on the I/O 205 * thread of the parent process. 206 * Overrides this function to define the task operation for individual task. 207 */ 208 virtual nsresult 209 IOWork() = 0; 210 211 /* 212 * Wrap the task success result to FileSystemResponseValue for sending it 213 * through IPC. This method runs in the PBackground thread. 214 * It will be called when the task is completed successfully and we need to 215 * send the task success result back to the child process. 216 */ 217 virtual FileSystemResponseValue 218 GetSuccessRequestResult(ErrorResult& aRv) const = 0; 219 220 /* 221 * After finishing the task operation, handle the task result. 222 * If it is an IPC task, send back the IPC result. It runs on the PBackground 223 * thread. 224 */ 225 void 226 HandleResult(); 227 228 // If this task must do something on the main-thread before IOWork(), it must 229 // overwrite this method. Otherwise it returns true if the FileSystem must be 230 // initialized on the main-thread. It's called from the Background thread. 231 virtual bool 232 NeedToGoToMainThread() const; 233 234 // This method is called only if NeedToGoToMainThread() returns true. 235 // Of course, it runs on the main-thread. 236 virtual nsresult 237 MainThreadWork(); 238 239 bool HasError()240 HasError() const { return NS_FAILED(mErrorValue); } 241 242 NS_IMETHOD 243 Run() override; 244 245 virtual nsresult 246 GetTargetPath(nsAString& aPath) const = 0; 247 248 private: 249 /* 250 * Wrap the task result to FileSystemResponseValue for sending it through IPC. 251 * It will be called when the task is completed and we need to 252 * send the task result back to the content. This runs on the PBackground 253 * thread. 254 */ 255 FileSystemResponseValue 256 GetRequestResult() const; 257 258 protected: 259 /* 260 * To create a parent process task delivered from the child process through 261 * IPC. 262 */ 263 FileSystemTaskParentBase(FileSystemBase* aFileSystem, 264 const FileSystemParams& aParam, 265 FileSystemRequestParent* aParent); 266 267 virtual 268 ~FileSystemTaskParentBase(); 269 270 nsresult mErrorValue; 271 RefPtr<FileSystemBase> mFileSystem; 272 RefPtr<FileSystemRequestParent> mRequestParent; 273 nsCOMPtr<nsIEventTarget> mBackgroundEventTarget; 274 }; 275 276 } // namespace dom 277 } // namespace mozilla 278 279 #endif // mozilla_dom_FileSystemTaskBase_h 280