Update SetMemoryUsageLevel.md

Author: LiangTheDev

specs/SetMemoryUsageLevel.md

@@ -3,19 +3,28 @@ Some WebView2 apps want to continue to run scripts while inactive and therefore
 We are introducing WebView2 API to reduce memory usage only for this type of inactive WebViews.
 
 # Description
-You may call the `SetMemoryUsageLevel` API to have the WebView2 consume less memory and going back to normal usage. This is useful when your Win32 app becomes invisible, 
+You may set the `MemoryUsageTargetLevel` property to have the WebView2 consume less memory and going back to normal usage. This is useful when your Win32 app becomes invisible, 
 but still wants to have script running or monitoring requests from network.
 
 # Examples
 ## .NET, WinRT
 ```c#
 async protected void OnBecomingInactive()
 {
-    webView.CoreWebView2.SetMemoryUsageLevel(CoreWebView2MemoryUsageLevel.Idle);
+    // CanSuspendWebPage() checks whether the current web contents in WebView can be suspended.
+    if (CanSuspendWebView()) {
+        await webView.CoreWebView2.TrySuspendAsync();
+    } else {
+        webView.CoreWebView2.MemoryUsageTargetLevel = CoreWebView2MemoryUsageTargetLevel.Low;
+    }
 }
 async protected void OnBecomingActive()
 {
-    webView.CoreWebView2.SetMemoryUsageLevel(CoreWebView2MemoryUsageLevel.Normal);
+    if (webView.CoreWebView2.IsSuspended) {
+        webView.CoreWebView2.Resume();
+    } else if (webView.CoreWebView2.MemoryUsageTargetLevel == CoreWebView2MemoryUsageTargetLevel.Low) {
+        webView.CoreWebView2.MemoryUsageTargetLevel = CoreWebView2MemoryUsageTargetLevel.Normal;
+    }
 }
 ```
 ## Win32 C++
@@ -38,18 +47,28 @@ bool ViewComponent::HandleWindowMessage(
 
 void ViewComponent::OnBecomingInactive()
 {
-    HRESULT hr = webView->SetMemoryUsageLevel(COREWEBVIEW2_MEMORY_USAGE_LEVEL_IDLE);
-    if (FAILED(hr))
-        ShowFailure(hr, L"Failed to set SetMemoryUsageLevel to idle");
+    // CanSuspendWebPage() checks whether the current web contents in WebView can be suspended.
+    if (CanSuspendWebView()) {
+        CHECK_FAILURE(m_webView->TrySuspend(nullptr));
+    } else {
+        CHECK_FAILURE(m_webView->put_MemoryUsageTargetLevel(COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_LOW);
+    }
 }
 
 void ViewComponent::OnBecomingActive()
 {
-    HRESULT hr = webView->SetMemoryUsageLevel(COREWEBVIEW2_MEMORY_USAGE_LEVEL_NORMAL);
-    if (FAILED(hr))
-        ShowFailure(hr, L"Failed to set SetMemoryUsageLevel to normal");
+  BOOL isSuspended = FALSE;
+  CHECK_FAILURE(m_webview->get_IsSuspended(&isSuspended));
+  if (isSuspended) {
+     CHECK_FAILURE(m_webView->Resume());
+  } else {
+     COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL memoryUsageTargetLevel = COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_LOW;
+     CHECK_FAILURE(m_webview->get_MemoryUsageTargetLevel(&memoryUsageTargetLevel));
+     if (memoryUsageTargetLevel == COREWEBVIEW2_MEMORY_USAGE_LEVEL_LOW) {
+         CHECK_FAILURE(m_webView->put_MemoryUsageTargetLevel(COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_NORMAL));
+     }
+  }
 }
-
 ```
 
 # Remarks
@@ -62,36 +81,46 @@ See [API Details](#api-details) section below for API reference.
 
 ## Win32 C++
 ```IDL
-/// Specifies memory usage level of WebView.
+/// Specifies memory usage target level of WebView.
 [v1_enum]
-typedef enum COREWEBVIEW2_MEMORY_USAGE_LEVEL {
-    /// Specifies normal memory usage level.
-    COREWEBVIEW2_MEMORY_USAGE_LEVEL_NORMAL,
+typedef enum COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL {
+    /// Specifies normal memory usage target level.
+    COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_NORMAL,
 
-    /// Specifies idle memory usage level.
+    /// Specifies low memory usage target level.
     /// Used for inactivate WebView for reduced memory consumption.
-    COREWEBVIEW2_MEMORY_USAGE_LEVEL_IDLE,
+    COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_LOW,
 
 } COREWEBVIEW2_MEMORY_USAGE_LEVEL;
 
 interface ICoreWebView2_6 : ICoreWebView2 {
 
-  /// An app may call the `SetMemoryUsageLevel` API to indicate desired memory
+  /// `MemoryUsageTargetLevel` indicates desired memory comsumption level of WebView.
+  HRESULT get_MemoryUsageTargetLevel([in] COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL level);
+  
+  /// An app may set `MemoryUsageTargetLevel` to indicate desired memory
   /// comsumption level of WebView. Scripts will not be impacted and continue to run.
   /// This is useful for inactive apps that still want to run scripts and/or keep
   /// network connections alive and therefore could not call `TrySuspend` and `Resume`
   /// to reduce memory consumption.
-  /// These apps can set memory usage level to `COREWEBVIEW2_MEMORY_USAGE_LEVEL_IDLE` when
-  /// the app becomes inactive, and set back to `COREWEBVIEW2_MEMORY_USAGE_LEVEL_NORMAL` when
+  /// These apps can set memory usage target level to `COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_LOW` when
+  /// the app becomes inactive, and set back to `COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_NORMAL` when
   /// the app becomes active.
   /// It is not neccesary to set CoreWebView2Controller's IsVisible property to false when calling the API.
   /// It is a best effort operation to change memory usage level, and the API will return before the operation completes.
-  /// Setting the level to `COREWEBVIEW2_MEMORY_USAGE_LEVEL_IDLE` could potentially cause
+  /// Setting the level to `COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_LOW` could potentially cause
   /// memory for some WebView browser processes to be swapped out to disk when needed. Therefore,
-  /// it is important for the app to set the level back to `COREWEBVIEW2_MEMORY_USAGE_LEVEL_NORMAL`
+  /// it is important for the app to set the level back to `COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_NORMAL`
   /// when the app becomes active again to have smoothy user experience.
   /// Setting memory usage level back to normal will not happen automatically.
-  HRESULT SetMemoryUsageLevel([in] COREWEBVIEW2_MEMORY_USAGE_LEVEL level);
+  /// An app should choose to use either the combination of `TrySuspend` and `Resume` or the combination
+  /// of setting MemoryUsageTargetLevel to low and normal. It is advices to not mix of them.
+  /// Suspend and resume opertaion is a superset of setting MemoryUsageTargetLevel.
+  /// TrySuspend will automatically set MemoryUsageTargetLevel to low while Resume on suspended WebView
+  /// will automatically set MemoryUsageTargetLevel to normal.
+  /// Calling `Resume` when the WebView is not suspended would not change MemoryUsageTargetLevel.
+  /// Setting MemoryUsageTargetLevel to normal on suspended WebView will auto resume WebView.
+  HRESULT put_MemoryUsageTargetLevel([in] COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL level);
 }
 
 ```
@@ -100,10 +129,17 @@ interface ICoreWebView2_6 : ICoreWebView2 {
 ```c#
 namespace Microsoft.Web.WebView2.Core
 {
+    public enum CoreWebView2MemoryUsageTargetLevel
+    {
+        /// 
+        Normal = 0,
+        /// 
+        Low = 1,
+    }
     public partial class CoreWebView2
     {
         // There are other API in this interface that we are not showing 
-        public void SetMemoryUsageLevel(CoreWebView2MemoryUsageLevel level);
+        public CoreWebView2MemoryUsageTargetLevel MemoryUsageTargetLevel { get; set; };
     }
 }
 ```