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/. */
7 #ifndef mozilla_dom_FileSystemTaskBase_h
8 #define mozilla_dom_FileSystemTaskBase_h
10 #include "mozilla/dom/FileSystemRequestParent.h"
11 #include "mozilla/dom/PFileSystemRequestChild.h"
12 #include "nsIGlobalObject.h"
13 #include "nsThreadUtils.h"
22 class FileSystemParams
;
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.
30 * The following diagram illustrates the how a API call from the content page
31 * starts a task and gets call back results.
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.
39 * ______|_________________________ | _________________________________
42 * | V | IPC | PBackground thread on |
43 * | [new FileSystemTaskChildBase()] | | | the parent process |
47 * | [GetRequestParams]------------------->[new FileSystemTaskParentBase()] |
49 * | | | | | (4) _____________ |
51 * | | | | | | I/O Thread | |
53 * | | | | ---------> [IOWork] | |
56 * | | | | -------------- | |
57 * | | | | | |_____________| |
60 * | | | | [HandleResult] |
64 * | [SetRequestResult]<---------------------[GetRequestResult] |
68 * |[HandlerCallback] | IPC | |
69 * |_______|_________________________| | |_________________________________|
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
79 * (2) Forward the task to the parent process through the IPC and call
80 * [GetRequestParams] to prepare the parameters of the IPC.
82 * (3) The parent process receives IPC and handle it in
83 * FileystemRequestParent. Get the IPC parameters and create a task to run the
85 * (4) The task operation will be performed in the member function of
86 * [IOWork]. 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
94 * Each task only needs to implement its specific success result preparation
95 * function -[GetSuccessRequestResult].
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.
102 class FileSystemTaskChildBase
: public PFileSystemRequestChild
{
103 friend class PFileSystemRequestChild
;
106 NS_INLINE_DECL_REFCOUNTING(FileSystemTaskChildBase
, final
)
109 * Start the task. It will dispatch all the information to the parent process,
110 * PBackground thread. This method must be called from the owning thread.
115 * The error codes are defined in xpcom/base/ErrorList.h and their
116 * corresponding error name and message are defined in dom/base/domerr.msg.
118 void SetError(const nsresult
& aErrorCode
);
120 FileSystemBase
* GetFileSystem() const;
123 * After the task is completed, this function will be called to pass the task
124 * result to the content page. This method is called in the owning thread.
125 * Override this function to handle the call back to the content page.
127 virtual void HandlerCallback() = 0;
129 bool HasError() const { return NS_FAILED(mErrorValue
); }
133 * To create a task to handle the page content request.
135 FileSystemTaskChildBase(nsIGlobalObject
* aGlobalObject
,
136 FileSystemBase
* aFileSystem
);
138 virtual ~FileSystemTaskChildBase();
141 * Wrap the task parameter to FileSystemParams for sending it through IPC.
142 * It will be called when we need to forward a task from the child process to
143 * the parent process. This method runs in the owning thread.
144 * @param filesystem The string representation of the file system.
146 virtual FileSystemParams
GetRequestParams(const nsString
& aSerializedDOMPath
,
147 ErrorResult
& aRv
) const = 0;
150 * Unwrap the IPC message to get the task success result.
151 * It will be called when the task is completed successfully and an IPC
152 * message is received in the child process and we want to get the task
153 * success result. This method runs in the owning thread.
155 virtual void SetSuccessRequestResult(const FileSystemResponseValue
& aValue
,
156 ErrorResult
& aRv
) = 0;
158 // Overrides PFileSystemRequestChild
159 virtual mozilla::ipc::IPCResult
Recv__delete__(
160 const FileSystemResponseValue
& value
) final
;
162 nsresult mErrorValue
;
163 RefPtr
<FileSystemBase
> mFileSystem
;
164 nsCOMPtr
<nsIGlobalObject
> mGlobalObject
;
168 * Unwrap the IPC message to get the task result.
169 * It will be called when the task is completed and an IPC message is received
170 * in the content process and we want to get the task result. This runs on the
173 void SetRequestResult(const FileSystemResponseValue
& aValue
);
176 // This class is the 'alter ego' of FileSystemTaskChildBase in the PBackground
178 class FileSystemTaskParentBase
: public Runnable
{
180 FileSystemTaskParentBase()
181 : Runnable("FileSystemTaskParentBase"),
182 mErrorValue(NS_ERROR_NOT_INITIALIZED
) {}
185 * Start the task. This must be called from the PBackground thread only.
190 * The error codes are defined in xpcom/base/ErrorList.h and their
191 * corresponding error name and message are defined in dom/base/domerr.msg.
193 void SetError(const nsresult
& aErrorCode
);
196 * The function to perform task operation. It will be run on the I/O
197 * thread of the parent process.
198 * Overrides this function to define the task operation for individual task.
200 virtual nsresult
IOWork() = 0;
203 * Wrap the task success result to FileSystemResponseValue for sending it
204 * through IPC. This method runs in the PBackground thread.
205 * It will be called when the task is completed successfully and we need to
206 * send the task success result back to the child process.
208 virtual FileSystemResponseValue
GetSuccessRequestResult(
209 ErrorResult
& aRv
) const = 0;
212 * After finishing the task operation, handle the task result.
213 * If it is an IPC task, send back the IPC result. It runs on the PBackground
218 bool HasError() const { return NS_FAILED(mErrorValue
); }
223 virtual nsresult
GetTargetPath(nsAString
& aPath
) const = 0;
227 * Wrap the task result to FileSystemResponseValue for sending it through IPC.
228 * It will be called when the task is completed and we need to
229 * send the task result back to the content. This runs on the PBackground
232 FileSystemResponseValue
GetRequestResult() const;
236 * To create a parent process task delivered from the child process through
239 FileSystemTaskParentBase(FileSystemBase
* aFileSystem
,
240 const FileSystemParams
& aParam
,
241 FileSystemRequestParent
* aParent
);
243 virtual ~FileSystemTaskParentBase();
245 nsresult mErrorValue
;
246 RefPtr
<FileSystemBase
> mFileSystem
;
247 RefPtr
<FileSystemRequestParent
> mRequestParent
;
248 nsCOMPtr
<nsIEventTarget
> mBackgroundEventTarget
;
252 } // namespace mozilla
254 #endif // mozilla_dom_FileSystemTaskBase_h