Make some changes based on review

Author: lamryQAQ-2nd

specs/IsSmartScreenRequired specs/IsSmartScreenRequired.mdspecs/IsSmartScreenRequired renamed to specs/IsSmartScreenRequired.md

@@ -1,16 +1,15 @@
 # Background
 
-[Edge SmartScreen](https://docs.microsoft.com/en-us/deployedge/microsoft-edge-security-smartscreen) helps you identify reported phishing and malware websites, and also helps you make informed decisions about downloads.
+[Edge SmartScreen](https://support.microsoft.com/en-us/microsoft-edge/how-can-smartscreen-help-protect-me-in-microsoft-edge-1c9a874a-6826-be5e-45b1-67fa445a74c8) helps end users identify reported phishing and malware websites, and also helps you make informed decisions about downloads.
 
 Currently, developers can use `options->put_AdditionalBrowserArguments(L"--disable-features=msSmartScreenProtection")` to disable SmartScreen in the WebView2 application. It is essentially a startup parameter of the browser process and applies to all WebView2 instances associated with that WebView2Environment. It must be determined when the WebView2Environment is created, and it cannot be modified at runtime.
 
 To support more flexibility we introduce a new API.
-We initially considered an API like `CoreWebView2Environment.IsSmartScreenEnabled` that would directly change the value for all the processes. The problem is this is not easy to do for apps like Office who have multiple apps connected to the same browser process. In their case each app has IsSmartScreenEnabled and its hard for the browser process to know which change to the property should win. 
 
-Instead we have CoreWebView2Settings.IsSmartScreenRequired. Each WebView2 declares if it requires SmartScreen. Some WebView2s may be used to display app content and don't require SmartScreen and others may be rendering arbitrary web content and do need SmartScreen. Having SmartScreen on unnecessarily for app content is a detriment to performance but otherwise not a problem. Having SmartScreen off for arbitrary web content is an issue. We have to turn SmartScreen on or off for all the WebView2s in an environment so if any WebView2 requires SmartScreen then we turn it on for all of them. If WebView2 settings change or WebView2s are closed and then all the WebView2s in an environment don't require SmartScreen, then we can turn SmartScreen off.
+we have CoreWebView2Settings.IsSmartScreenRequired. Each WebView2 declares if it requires SmartScreen. Some WebView2s may be used to display app content and don't require SmartScreen and others may be rendering arbitrary web content and do need SmartScreen. Having SmartScreen on unnecessarily for app content is a detriment to performance but otherwise not a problem. Having SmartScreen off for arbitrary web content is an issue. We have to turn SmartScreen on or off for all the WebView2s in an environment so if any WebView2 requires SmartScreen then we turn it on for all of them. If WebView2 settings change or WebView2s are closed and then all the WebView2s in an environment don't require SmartScreen, then we can turn SmartScreen off.
 
 It is much easier to indicate if individual WebView2s require SmartScreen than to have an end developer explicitly manage if SmartScreen should be enabled as a whole, especially when its different sets of WebView2s in different processes (like Excel's set of WebView2s and Word's set of WebView2s) all sharing the same user data folder.
-In this document we describe the new setting. We'd appreciate your feedback.
+In this document we describe the new setting.
 
 
 # Description
@@ -23,17 +22,20 @@ Changes to `IsSmartScreenRequired` take effect on the next navigation or downloa
 
 # Examples
 ```cpp
+// member variable
 wil::com_ptr<ICoreWebView2Settings> m_webViewSettings;
-void SettingsComponent::ToggleSmartScreenRequired()
+
+// isLocalContent is TRUE if the page is navigated to content that is completely
+// app-provided, with no user-provided content or web-served content.
+// Note that we must update the property before navigating to the content.
+void SettingsComponent::UpdateSmartScreenRequirementBeforeNavigating(bool isLocalContent)
 {
-    wil::com_ptr<ICoreWebView2Settings11> coreWebView2Settings11;
+   wil::com_ptr<ICoreWebView2Settings11> coreWebView2Settings11;
     coreWebView2Settings11 =
                 m_webViewSettings.try_query<ICoreWebView2Settings11>();
     if(coreWebView2Settings11) 
     {
-        BOOL enabled;
-        CHECK_FAILURE(coreWebView2Settings11->get_IsSmartScreenRequired(&enabled));
-        CHECK_FAILURE(coreWebView2Settings11->put_IsSmartScreenRequired(enabled ? FALSE : TRUE));
+        CHECK_FAILURE(coreWebView2Settings11->put_IsSmartScreenRequired(!isLocalContent));
     }
 }
 ```
@@ -58,28 +60,27 @@ See [API Details](#api-details) section below for API reference.
 ```cpp
 [uuid(d667d3a7-c1b7-479f-8833-db7547df6687), object, pointer_default(unique)]
 interface ICoreWebView2Settings11 : ICoreWebView2Settings10 {
-  /// SmartScreen helps you identify reported phishing and malware websites  
+  /// SmartScreen helps end users identify reported phishing and malware websites  
   /// and also helps you make informed decisions about downloads. 
   /// `IsSmartScreenRequired`  is used to control whether SmartScreen enabled or not. 
   /// SmartScreen is enabled or disabled for all CoreWebView2s in a CoreWebView2Environment. 
   /// If CoreWebView2Setting.IsSmartScreenRequired is true for any CoreWebView2 associated to the same
   /// CoreWebView2Environment, then SmartScreen is enabled. If CoreWebView2Setting.IsSmartScreenRequired 
   /// is false for all CoreWebView2s in the associated CoreWebView2Environment, then SmartScreen is disabled.
   /// When it is changed, the change will be applied to all WebViews using the 
-  /// same user data folder. 
+  /// same CoreWebView2Environment.
   /// The default value for `IsSmartScreenRequired` is true if SmartScreen is enabled when the CoreWebView2 
   /// is created and false if SmartScreen is disabled when the CoreWebView2 is created. The value doesn't change 
   /// if SmartScreen is enabled or disabled later.
-  /// \snippet SettingsComponent.cpp ToggleSmartScreenEnabled.
   [propget] HRESULT IsSmartScreenRequired([out, retval] BOOL* value); 
 
-  /// The setting of SmartScreen does not mean the actual situation, it only represents 
-  /// the intention of each WebView2.
+  /// Sets whether this webview2 instance needs SmartScreen protection for its content.
   /// Set the `IsSmartScreenRequired` property. 
   [propput] HRESULT IsSmartScreenRequired([in] BOOL value); 
 }
 ```
 
+```c# (really MIDL3)
 namespace Microsoft.Web.WebView2.Core
 {
     runtimeclass CoreWebView2Settings
@@ -91,4 +92,8 @@ namespace Microsoft.Web.WebView2.Core
         }
     }
 }
+```
 
+# Appendix
+
+We initially considered an API like `CoreWebView2Environment.IsSmartScreenEnabled` that would directly change the value for all the processes. The problem is this is not easy to do for apps like Office who have multiple apps connected to the same browser process. In their case each app has IsSmartScreenEnabled and its hard for the browser process to know which change to the property should win.