external_protocol_handler.h revision 2a99a7e74a7f215066514fe81d2bfa6639d9eddd 
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_EXTERNAL_PROTOCOL_EXTERNAL_PROTOCOL_HANDLER_H_
6#define CHROME_BROWSER_EXTERNAL_PROTOCOL_EXTERNAL_PROTOCOL_HANDLER_H_
7
8#include <string>
9
10#include "chrome/browser/shell_integration.h"
11
12class GURL;
13class PrefRegistrySimple;
14
15namespace base {
16class DictionaryValue;
17}
18
19class ExternalProtocolHandler {
20 public:
21  enum BlockState {
22    DONT_BLOCK,
23    BLOCK,
24    UNKNOWN,
25  };
26
27  // Delegate to allow unit testing to provide different behavior.
28  class Delegate {
29   public:
30    virtual ShellIntegration::DefaultProtocolClientWorker* CreateShellWorker(
31        ShellIntegration::DefaultWebClientObserver* observer,
32        const std::string& protocol) = 0;
33    virtual BlockState GetBlockState(const std::string& scheme) = 0;
34    virtual void BlockRequest() = 0;
35    virtual void RunExternalProtocolDialog(const GURL& url,
36                                           int render_process_host_id,
37                                           int routing_id) = 0;
38    virtual void LaunchUrlWithoutSecurityCheck(const GURL& url) = 0;
39    virtual void FinishedProcessingCheck() = 0;
40    virtual ~Delegate() {}
41  };
42
43  // Returns whether we should block a given scheme.
44  static BlockState GetBlockState(const std::string& scheme);
45
46  // Sets whether we should block a given scheme.
47  static void SetBlockState(const std::string& scheme, BlockState state);
48
49  // Checks to see if the protocol is allowed, if it is whitelisted,
50  // the application associated with the protocol is launched on the io thread,
51  // if it is blacklisted, returns silently. Otherwise, an
52  // ExternalProtocolDialog is created asking the user. If the user accepts,
53  // LaunchUrlWithoutSecurityCheck is called on the io thread and the
54  // application is launched.
55  // Must run on the UI thread.
56  static void LaunchUrl(const GURL& url, int render_process_host_id,
57                        int tab_contents_id) {
58      LaunchUrlWithDelegate(url, render_process_host_id, tab_contents_id, NULL);
59  }
60
61  // Version of LaunchUrl allowing use of a delegate to facilitate unit
62  // testing.
63  static void LaunchUrlWithDelegate(const GURL& url, int render_process_host_id,
64                                    int tab_contents_id, Delegate* delegate);
65
66  // Creates and runs a External Protocol dialog box.
67  // |url| - The url of the request.
68  // |render_process_host_id| and |routing_id| are used by
69  // tab_util::GetWebContentsByID to aquire the tab contents associated with
70  // this dialog.
71  // NOTE: There is a race between the Time of Check and the Time Of Use for
72  //       the command line. Since the caller (web page) does not have access
73  //       to change the command line by itself, we do not do anything special
74  //       to protect against this scenario.
75  // This is implemented separately on each platform.
76  static void RunExternalProtocolDialog(const GURL& url,
77                                        int render_process_host_id,
78                                        int routing_id);
79
80  // Register the ExcludedSchemes preference.
81  static void RegisterPrefs(PrefRegistrySimple* registry);
82
83  // Starts a url using the external protocol handler with the help
84  // of shellexecute. Should only be called if the protocol is whitelisted
85  // (checked in LaunchUrl) or if the user explicitly allows it. (By selecting
86  // "Launch Application" in an ExternalProtocolDialog.) It is assumed that the
87  // url has already been escaped, which happens in LaunchUrl.
88  // NOTE: You should Not call this function directly unless you are sure the
89  // url you have has been checked against the blacklist, and has been escaped.
90  // All calls to this function should originate in some way from LaunchUrl.
91  // This will execute on the file thread.
92  static void LaunchUrlWithoutSecurityCheck(const GURL& url);
93
94  // Prepopulates the dictionary with known protocols to deny or allow, if
95  // preferences for them do not already exist.
96  static void PrepopulateDictionary(base::DictionaryValue* win_pref);
97
98  // Allows LaunchUrl to proceed with launching an external protocol handler.
99  // This is typically triggered by a user gesture, but is also called for
100  // each extension API function. Note that each call to LaunchUrl resets
101  // the state to false (not allowed).
102  static void PermitLaunchUrl();
103};
104
105#endif  // CHROME_BROWSER_EXTERNAL_PROTOCOL_EXTERNAL_PROTOCOL_HANDLER_H_
106