Improve ResourceRequestInfo::HasUserGesture API docs

content/public/browser/resource_request_info.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef CONTENT_PUBLIC_BROWSER_RESOURCE_REQUEST_INFO_H_
 #define CONTENT_PUBLIC_BROWSER_RESOURCE_REQUEST_INFO_H_
 
 #include "base/basictypes.h"
 #include "content/common/content_export.h"
 #include "content/public/common/resource_type.h"
@@ skipping 80 matching lines @@
 
   // Returns the associated visibility state at the time the request was started
   // in the renderer.
   virtual blink::WebPageVisibilityState GetVisibilityState() const = 0;
 
   // Returns the associated page transition type.
   virtual ui::PageTransition GetPageTransition() const = 0;
 
   // True if the request was initiated by a user action (like a tap to follow
   // a link).
+  //
+  // Note that a false value does not mean the request was not initiated by a
+  // user gesture. Also note that the fact that a user gesture was active
+  // while the request was created does not imply that the user consciously
+  // wanted this request to happen nor is aware of it.
+  //
+  // DO NOT BASE SECURITY DECISIONS ON THIS FLAG!

[mkosiba (inactive), 2014/10/17 08:54:33]

Yes, you should be especially wary of using this to determine what to do with a
download :D

https://code.google.com/p/chromium/codesearch#chromium/src/chrome/browser/saf...

https://code.google.com/p/chromium/codesearch#chromium/src/content/browser/do...

[Randy Smith (Not in Mondays), 2014/10/20 14:20:46]

We'd welcome other other suggestions as to how to make download decisions (but
you'll probably have to mind-meld extensively with the current conditional
cascade and you may feel dirty afterwards :-}).  Whether and how to download
resources has a pretty strong tension between security and convenience, and when
we've moved towards security (e.g. prompting people around downloading PDFs
because they can contain arbitrary executable code) we've gotten howls of
protest.  I don't expect we're going to change our current use of user gesture,
even though we do indeed know it's not reliable :-{.

   virtual bool HasUserGesture() const = 0;
 
   // True if ResourceController::CancelAndIgnore() was called.  For example,
   // the requested URL may be being loaded by an external program.
   virtual bool WasIgnoredByHandler() const = 0;
 
   // Returns false if there is NOT an associated render frame.
   virtual bool GetAssociatedRenderFrame(int* render_process_id,
                                         int* render_frame_id) const = 0;
 
   // Returns true if this is associated with an asynchronous request.
   virtual bool IsAsync() const = 0;
 
   // Whether this is a download.
   virtual bool IsDownload() const = 0;
 
  protected:
   virtual ~ResourceRequestInfo() {}
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_RESOURCE_REQUEST_INFO_H_