1// Copyright (c) 2011 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 CHROME_BROWSER_UTILITY_PROCESS_HOST_H_
6#define CHROME_BROWSER_UTILITY_PROCESS_HOST_H_
7#pragma once
8
9#include <string>
10#include <vector>
11
12#include "base/basictypes.h"
13#include "base/memory/ref_counted.h"
14#include "base/task.h"
15#include "chrome/common/extensions/update_manifest.h"
16#include "content/browser/browser_child_process_host.h"
17#include "content/browser/browser_thread.h"
18
19class DictionaryValue;
20class IndexedDBKey;
21class ListValue;
22class SerializedScriptValue;
23class SkBitmap;
24
25// This class acts as the browser-side host to a utility child process.  A
26// utility process is a short-lived sandboxed process that is created to run
27// a specific task.  This class lives solely on the IO thread.
28// If you need a single method call in the sandbox, use StartFooBar(p).
29// If you need multiple batches of work to be done in the sandboxed process,
30// use StartBatchMode(), then multiple calls to StartFooBar(p),
31// then finish with EndBatchMode().
32class UtilityProcessHost : public BrowserChildProcessHost {
33 public:
34  // An interface to be implemented by consumers of the utility process to
35  // get results back.  All functions are called on the thread passed along
36  // to UtilityProcessHost.
37  class Client : public base::RefCountedThreadSafe<Client> {
38   public:
39    Client() {}
40
41    // Called when the process has crashed.
42    virtual void OnProcessCrashed(int exit_code) {}
43
44    // Called when the extension has unpacked successfully.  |manifest| is the
45    // parsed manifest.json file.  |catalogs| contains list of all parsed
46    // message catalogs.  |images| contains a list of decoded images and the
47    // associated paths where those images live on disk.
48    virtual void OnUnpackExtensionSucceeded(const DictionaryValue& manifest) {}
49
50    // Called when an error occurred while unpacking the extension.
51    // |error_message| contains a description of the problem.
52    virtual void OnUnpackExtensionFailed(const std::string& error_message) {}
53
54    // Called when the web resource has been successfully parsed.  |json_data|
55    // contains the parsed list of web resource items downloaded from the
56    // web resource server.
57    virtual void OnUnpackWebResourceSucceeded(
58        const DictionaryValue& json_data) {}
59
60    // Called when an error occurred while parsing the resource data.
61    // |error_message| contains a description of the problem.
62    virtual void OnUnpackWebResourceFailed(const std::string& error_message) {}
63
64    // Called when an update manifest xml file was successfully parsed.
65    virtual void OnParseUpdateManifestSucceeded(
66        const UpdateManifest::Results& results) {}
67
68    // Called when an update manifest xml file failed parsing. |error_message|
69    // contains details suitable for logging.
70    virtual void OnParseUpdateManifestFailed(
71        const std::string& error_message) {}
72
73    // Called when image data was successfully decoded. |decoded_image|
74    // stores the result.
75    virtual void OnDecodeImageSucceeded(
76        const SkBitmap& decoded_image) {}
77
78    // Called when image data decoding failed.
79    virtual void OnDecodeImageFailed() {}
80
81    // Called when we have successfully obtained the IndexedDBKey after
82    // a call to StartIDBKeysFromValuesAndKeyPath.
83    // |id| is the corresponding identifier.
84    // |keys| the corresponding IndexedDBKey.
85    virtual void OnIDBKeysFromValuesAndKeyPathSucceeded(
86        int id, const std::vector<IndexedDBKey>& keys) {}
87
88    // Called when IDBKeyPath has failed.
89    // |id| is the corresponding identifier passed on
90    // StartIDBKeysFromValuesAndKeyPath.
91    virtual void OnIDBKeysFromValuesAndKeyPathFailed(int id) {}
92
93    // Called when an IDBKey was injected into a
94    // SerializedScriptValue. If injection failed, SerializedScriptValue is
95    // empty.
96    virtual void OnInjectIDBKeyFinished(
97        const SerializedScriptValue& new_value) {}
98
99    // Called when we're finished parsing a JSON string. Note that if parsing
100    // was successful, the result Value is contained in the first element of
101    // |wrapper| (we do this to get around a trickiness with passing a Value
102    // by const reference via our IPC system).
103    virtual void OnJSONParseSucceeded(const ListValue& wrapper) {}
104    virtual void OnJSONParseFailed(const std::string& error_message) {}
105
106   protected:
107    friend class base::RefCountedThreadSafe<Client>;
108
109    virtual ~Client() {}
110
111   private:
112    friend class UtilityProcessHost;
113
114    bool OnMessageReceived(const IPC::Message& message);
115
116    DISALLOW_COPY_AND_ASSIGN(Client);
117  };
118
119  UtilityProcessHost(Client* client, BrowserThread::ID client_thread_id);
120  virtual ~UtilityProcessHost();
121
122  // Start a process to unpack the extension at the given path.  The process
123  // will be given access to the directory subtree that the extension file is
124  // in, so the caller is expected to have moved that file into a quarantined
125  // location first.
126  bool StartExtensionUnpacker(const FilePath& extension);
127
128  // Start a process to unpack and parse a web resource from the given JSON
129  // data.  Any links that need to be downloaded from the parsed data
130  // (thumbnails, etc.) will be unpacked in resource_dir.
131  // TODO(mrc): Right now, the unpacker just parses the JSON data, and
132  // doesn't do any unpacking.  This should change once we finalize the
133  // web resource server format(s).
134  bool StartWebResourceUnpacker(const std::string& data);
135
136  // Start parsing an extensions auto-update manifest xml file.
137  bool StartUpdateManifestParse(const std::string& xml);
138
139  // Start image decoding. The image can be any format WebCore understands.
140  // Results are reported to either OnDecodeImageSuceeded() or
141  // OnDecodeImageFailed().
142  bool StartImageDecoding(const std::vector<unsigned char>& encoded_data);
143  bool StartImageDecodingBase64(const std::string& base64_encoded_data);
144
145  // Starts extracting |key_path| from |serialized_values|, and replies with the
146  // corresponding IndexedDBKeys via OnIDBKeysFromValuesAndKeyPathSucceeded.
147  bool StartIDBKeysFromValuesAndKeyPath(
148      int id, const std::vector<SerializedScriptValue>& serialized_values,
149      const string16& key_path);
150
151  // Starts injecting |key| into |value| via |key_path|, and replies with the
152  // updated value via OnInjectIDBKeyFinished.
153  bool StartInjectIDBKey(const IndexedDBKey& key,
154                         const SerializedScriptValue& value,
155                         const string16& key_path);
156
157  // Starts parsing a JSON string into a Value object. The result is reported
158  // to the client via OnJSONParseSucceeded or OnJSONParseFailed.
159  bool StartJSONParsing(const std::string& json);
160
161  // Starts utility process in batch mode. Caller must call EndBatchMode()
162  // to finish the utility process.
163  bool StartBatchMode();
164
165  // Ends the utility process. Must be called after StartBatchMode().
166  void EndBatchMode();
167
168 protected:
169  // Allow these methods to be overridden for tests.
170  virtual FilePath GetUtilityProcessCmd();
171
172 private:
173  // Starts a process if necessary.  Returns true if it succeeded or a process
174  // has already been started via StartBatchMode().
175  bool StartProcess(const FilePath& exposed_dir);
176
177  // IPC messages:
178  virtual bool OnMessageReceived(const IPC::Message& message);
179
180  // BrowserChildProcessHost:
181  virtual void OnProcessCrashed(int exit_code);
182  virtual bool CanShutdown();
183
184  // A pointer to our client interface, who will be informed of progress.
185  scoped_refptr<Client> client_;
186  BrowserThread::ID client_thread_id_;
187  // True when running in batch mode, i.e., StartBatchMode() has been called
188  // and the utility process will run until EndBatchMode().
189  bool is_batch_mode_;
190
191  DISALLOW_COPY_AND_ASSIGN(UtilityProcessHost);
192};
193
194#endif  // CHROME_BROWSER_UTILITY_PROCESS_HOST_H_
195