chrome/browser/external_protocol/external_protocol_handler.h

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