Add COM, .NET/WinRT API definition

Author: lflores-ms

specs/ExtendedProcessFailed.md

@@ -368,8 +368,320 @@ See [API Details](#api-details) section below for API reference.
 # API Details
 ## COM
 ```cpp
+library WebView2
+{
+// ...
+
+/// Specifies the process failure type used in the
+/// `ICoreWebView2ProcessFailedEventHandler` interface. The values in this enum
+/// make reference to the process kinds in the Chromium architecture. For more
+/// information about what these processes are and what they do, see
+/// [Browser Architecture - Inside look at modern web browser](https://developers.google.com/web/updates/2018/09/inside-browser-part1)
+[v1_enum]
+typedef enum COREWEBVIEW2_PROCESS_FAILED_KIND {
+  // Existing stable values.
+  COREWEBVIEW2_PROCESS_FAILED_KIND_BROWSER_PROCESS_EXITED,
+
+  /// Indicates that the main frame's render process ended unexpectedly.  A new
+  /// render process is created automatically and navigated to an error page.
+  /// The app runs `Reload()` to try to recover from the failure.
+  COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_EXITED,
+  COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_UNRESPONSIVE,
+
+  // New values.
+  
+  /// Indicates that a frame-only render process ended unexpectedly. The process
+  /// exit does not impact the top-level document, only a subset of the
+  /// subframes within it. The content in these frames is replaced with a "sad
+  /// face" layer.
+  COREWEBVIEW2_PROCESS_FAILED_KIND_FRAME_RENDER_PROCESS_EXITED,
+
+  /// Indicates that a utility process ended unexpectedly.
+  COREWEBVIEW2_PROCESS_FAILED_KIND_UTILITY_PROCESS_EXITED,
+
+  /// Indicates that a sandbox helper process ended unexpectedly.
+  COREWEBVIEW2_PROCESS_FAILED_KIND_SANDBOX_HELPER_PROCESS_EXITED,
+
+  /// Indicates that the GPU process ended unexpectedly.
+  COREWEBVIEW2_PROCESS_FAILED_KIND_GPU_PROCESS_EXITED,
+
+  /// Indicates that a PPAPI plugin process ended unexpectedly.
+  COREWEBVIEW2_PROCESS_FAILED_KIND_PPAPI_PLUGIN_PROCESS_EXITED,
+
+  /// Indicates that a PPAPI plugin broker process ended unexpectedly.
+  COREWEBVIEW2_PROCESS_FAILED_KIND_PPAPI_BROKER_PROCESS_EXITED,
+
+  /// Indicates that a process of unspecified kind ended unexpectedly.
+  COREWEBVIEW2_PROCESS_FAILED_KIND_UNKNOWN_PROCESS_EXITED,
+} COREWEBVIEW2_PROCESS_FAILED_KIND;
+
+
+/// Specifies the process failure reason used in the
+/// `ICoreWebView2ProcessFailedEventHandler` interface.
+[v1_enum]
+typedef enum COREWEBVIEW2_PROCESS_FAILED_REASON {
+  /// An unexpected process failure occurred.
+  COREWEBVIEW2_PROCESS_FAILED_REASON_UNEXPECTED,
+
+  /// The process became unresponsive.
+  /// This only applies to the main frame's render process.
+  COREWEBVIEW2_PROCESS_FAILED_REASON_UNRESPONSIVE,
+
+  /// The process was killed. E.g., from Task Manager.
+  COREWEBVIEW2_PROCESS_FAILED_REASON_KILLED,
+
+  /// The process crashed.
+  COREWEBVIEW2_PROCESS_FAILED_REASON_CRASHED,
+
+  /// The process failed to launch.
+  COREWEBVIEW2_PROCESS_FAILED_REASON_LAUNCH_FAILED,
+
+  /// The process died due to running out of memory.
+  COREWEBVIEW2_PROCESS_FAILED_REASON_OUT_OF_MEMORY,
+} COREWEBVIEW2_PROCESS_FAILED_REASON;
+
+/// A continuation of `ICoreWebView2ProcessFailedEventArgs` interface.
+[uuid(c62f5687-2f09-481b-b6e4-2c0620bc95a2), object, pointer_default(unique)]
+interface ICoreWebView2ProcessFailedEventArgs2 : IUnknown {
+  // The ProcessFailedKind property below is already in
+  // ICoreWebView2ProcessFailedEventArgs. The changes to this interface extend
+  // its return enum so it can now specify additional process kinds: gpu process
+  // exited, utility process exited, etc. The property is included here to show
+  // the updated docs.
+
+  /// The kind of process failure that has occurred. `processFailedKind` is
+  /// `COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_EXITED` if the
+  /// failed process is the main frame's renderer, even if there were subframes
+  /// rendered by such process; all frames are gone when this happens.
+  // [propget] HRESULT ProcessFailedKind(
+  //     [out, retval] COREWEBVIEW2_PROCESS_FAILED_KIND* processFailedKind);
+
+  /// The reason for the process failure. The reason is always
+  /// `COREWEBVIEW2_PROCESS_FAILED_REASON_UNEXPECTED` when `ProcessFailedKind`
+  /// is `COREWEBVIEW2_PROCESS_FAILED_KIND_BROWSER_PROCESS_EXITED`, and
+  /// `COREWEBVIEW2_PROCESS_FAILED_REASON_UNRESPONSIVE` when `ProcessFailedKind`
+  /// is `COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_UNRESPONSIVE`.
+  /// For other process failure kinds, the reason may be any of the reason
+  /// values.
+  [propget] HRESULT Reason(
+      [out, retval] COREWEBVIEW2_PROCESS_FAILED_REASON* reason);
+
+  /// The exit code of the failing process. The exit code is always `1` when
+  /// `ProcessFailedKind` is
+  /// `COREWEBVIEW2_PROCESS_FAILED_KIND_BROWSER_PROCESS_EXITED`, and
+  /// `STILL_ACTIVE` (`259`) when `ProcessFailedKind` is
+  /// `COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_UNRESPONSIVE`.
+  [propget] HRESULT ExitCode(
+      [out, retval] int* exitCode);
+
+  /// Description of the process assigned by the WebView2 Runtime. This is a
+  /// technical English term appropriate for logging or development purposes,
+  /// and not localized for the end user. It applies to utility processes (e.g.,
+  /// "Audio Service", "Video Capture") and plugin processes (e.g., "Flash").
+  /// The returned `processDescription` is `null` if the WebView2 Runtime did
+  /// not assign a description to the process.
+  [propget] HRESULT ProcessDescription(
+      [out, retval] LPWSTR* processDescription);
+
+  /// The list of frames in the `CoreWebView2` that were being rendered by the
+  /// failed process. The content in these frames is replaced with a "sad face"
+  /// layer.
+  /// This is only available when `ProcessFailedKind` is
+  /// `COREWEBVIEW2_PROCESS_FAILED_KIND_FRAME_RENDER_PROCESS_EXITED`;
+  /// `frames` is `null` for all other process failure kinds, including the case
+  /// in which the failed process was the renderer for the main frame and
+  /// subframes within it, for which the failure kind is
+  /// `COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_EXITED`.
+  [propget] HRESULT ImpactedFramesInfo(
+      [out, retval] ICoreWebView2FrameInfoCollection** frames);
+}
+
+/// Collection of frame details (name and source). Used to list the impacted
+/// frames' info when a frame-only render process failure occurs in the
+/// `ICoreWebView2`.
+[uuid(4bedeef8-3de7-4a3a-aadc-e9437bfb3e92), object, pointer_default(unique)]
+interface ICoreWebView2FrameInfoCollection : IUnknown {
+  /// Gets an iterator over the collection of frames' info.
+  HRESULT GetIterator(
+      [out, retval] ICoreWebView2FrameInfoCollection** iterator);
+}
+
+/// Iterator for a collection of frames' info. For more info, see
+/// `ICoreWebView2ProcessFailedEventArgs2` and
+/// `ICoreWebView2FrameInfoCollection`.
+[uuid(0e2367b9-c725-4696-bb8a-75b97af32330), object, pointer_default(unique)]
+interface ICoreWebView2FrameInfoCollectionIterator : IUnknown {
+  /// Get the current `ICoreWebView2FrameInfo` of the iterator.
+  HRESULT GetCurrentFrameInfo([out, retval] ICoreWebView2FrameInfo** frameInfo);
+
+  /// `TRUE` when the iterator has not run out of frames' info.  If the
+  /// collection over which the iterator is iterating is empty or if the
+  /// iterator has gone past the end of the collection, then this is `FALSE`.
+  HRESULT HasCurrentFrameInfo([out, retval] BOOL* hasCurrent);
+
+  /// Move the iterator to the next frame's info in the collection.
+  HRESULT MoveNext([out, retval] BOOL* hasNext);
+}
+
+/// Provides a set of properties for a frame in the `ICoreWebView2`.
+[uuid(b41e743b-ab1a-4054-bafa-d3347ddc4ddc), object, pointer_default(unique)]
+interface ICoreWebView2FrameInfo : IUnknown {
+  /// The name attribute of the frame, as in `<iframe name="frame-name" ...>`.
+  /// This is `null` when the frame has no name attribute.
+  [propget] HRESULT Name([out, retval] LPWSTR* name);
+  /// The URI of the document in the frame.
+  [propget] HRESULT Source([out, retval] LPWSTR* source);
+}
+
+}
+
 ```
 
 ## .NET and WinRT
 ```c#
+namespace Microsoft.Web.WebView2.Core
+{
+    // ...
+
+    /// Specifies the process failure type used in the
+    /// `CoreWebView2ProcessFailedEventArgs`.
+    /// The values in this enum make reference to the process kinds in the
+    /// Chromium architecture. For more information about what these processes
+    /// are and what they do, see [Browser Architecture - Inside look at modern web browser](https://developers.google.com/web/updates/2018/09/inside-browser-part1)
+    enum CoreWebView2ProcessFailedKind
+    {
+        // Existing stable values
+        BrowserProcessExited,
+        /// Indicates that the main frame's render process ended unexpectedly.  A new
+        /// render process is created automatically and navigated to an error page.
+        /// The app runs `Reload()` to try to recover from the failure.
+        RenderProcessExited,
+        RenderProcessUnresponsive,
+
+        // New values.
+
+        /// Indicates that a frame-only render process ended unexpectedly. The process
+        /// exit does not impact the top-level document, only a subset of the
+        /// subframes within it. The content in these frames is replaced with a "sad
+        /// face" layer.
+        FrameRenderProcessExited,
+        /// Indicates that a utility process ended unexpectedly.
+        UtilityProcessExited,
+        /// Indicates that a sandbox helper process ended unexpectedly.
+        SandboxHelperProcessExited,
+        /// Indicates that the GPU process ended unexpectedly.
+        GpuProcessExited,
+        /// Indicates that a PPAPI plugin process ended unexpectedly.
+        PpapiPluginProcessExited,
+        /// Indicates that a PPAPI plugin broker process ended unexpectedly.
+        PpapiBrokerProcessExited,
+        /// Indicates that a process of unspecified kind ended unexpectedly.
+        UnknownProcessExited,
+    };
+
+    /// Specifies the process failure reason used in the
+    /// `CoreWebView2ProcessFailedEventArgs`.
+    enum CoreWebView2ProcessFailedReason
+    {
+        /// An unexpected process failure occurred.
+        Unexpected,
+        /// The process became unresponsive.
+        /// This only applies to the main frame's render process.
+        Unresponsive,
+        /// The process was killed. E.g., from Task Manager.
+        Killed,
+        /// The process crashed.
+        Crashed,
+        /// The process failed to launch.
+        LaunchFailed,
+        /// The process died due to running out of memory.
+        OutOfMemory,
+    };
+
+    runtimeclass CoreWebView2ProcessFailedEventArgs
+    {
+        // The property below is already in the event args and included here
+        // just to show the updated docs.
+
+        /// The kind of process failure that has occurred. Returns
+        /// `CoreWebView2ProcessFailedKind.RenderProcessExited` if the
+        /// failed process is the main frame's renderer, even if there were subframes
+        /// rendered by such process; all frames are gone when this happens.
+        // CoreWebView2ProcessFailedKind ProcessFailedKind { get; };
+
+
+        /// The reason for the process failure. The reason is always
+        /// `CoreWebView2ProcessFailedReason..Unexpected` when `ProcessFailedKind`
+        /// is `CoreWebView2ProcessFailedKind.BrowserProcessExited`, and
+        /// `CoreWebView2ProcessFailedReason..Unresponsive` when `ProcessFailedKind`
+        /// is `CoreWebView2ProcessFailedKind.RenderProcessUnresponsive`.
+        /// For other process failure kinds, the reason may be any of the reason
+        /// values.
+        CoreWebView2ProcessFailedReason Reason { get; };
+
+        /// The exit code of the failing process. The exit code is always `1` when
+        /// `ProcessFailedKind` is
+        /// `CoreWebView2ProcessFailedKind.BrowserProcessExited`, and
+        /// `STILL_ACTIVE` (`259`) when `ProcessFailedKind` is
+        /// `CoreWebView2ProcessFailedKind.RenderProcessUnresponsive`.
+        Int32 ExitCode { get; };
+
+        /// Description of the process assigned by the WebView2 Runtime. This is a
+        /// technical English term appropriate for logging or development purposes,
+        /// and not localized for the end user. It applies to utility processes (e.g.,
+        /// "Audio Service", "Video Capture") and plugin processes (e.g., "Flash").
+        /// The returned string is `null` if the WebView2 Runtime did
+        /// not assign a description to the process.
+        String ProcessDescription { get; };
+
+        /// The list of frames in the `CoreWebView2` that were being rendered by the
+        /// failed process. The content in these frames is replaced with a "sad face"
+        /// layer.
+        /// This is only available when `ProcessFailedKind` is
+        /// `CoreWebView2ProcessFailedKind.FrameRenderProcessExited`;
+        /// it is `null` for all other process failure kinds, including the case
+        /// in which the failed process was the renderer for the main frame and
+        /// subframes within it, for which the failure kind is
+        /// `CoreWebView2ProcessFailedKind.RenderProcessExited`.
+        CoreWebView2FrameInfoCollection ImpactedFramesInfo { get; };
+    }
+
+    /// Collection of frame details (name and source). Used to list the impacted
+    /// frames' info when a frame-only render process failure occurs in the
+    /// `CoreWebView2`.
+    runtimeclass CoreWebView2FrameInfoCollection
+    {
+        /// Gets an iterator over the collection of frames' info.
+        CoreWebView2FrameInfoCollection GetIterator();
+    }
+
+    /// Iterator for a collection of frames' info. For more info, see
+    /// `CoreWebView2ProcessFailedEventArgs` and
+    /// ICoreWebView2FrameInfoCollection`.
+    runtimeclass CoreWebView2FrameInfoCollectionIterator
+    {
+        /// Get the current `CoreWebView2FrameInfo` of the iterator.
+        CoreWebView2FrameInfo GetCurrentFrameInfo();
+
+        /// `true` when the iterator has not run out of frames' info.  If the
+        /// collection over which the iterator is iterating is empty or if the
+        /// iterator has gone past the end of the collection, then this is `false`.
+        Int32 HasCurrentFrameInfo();
+
+        /// Move the iterator to the next frame's info in the collection.
+        Boolean MoveNext();
+    }
+
+    /// Provides a set of properties for a frame in the `CoreWebView2`.
+    runtimeclass CoreWebView2FrameInfo
+    {
+        /// The name attribute of the frame, as in `<iframe name="frame-name" ...>`.
+        /// This is `null` when the frame has no name attribute.
+        String Name { get; };
+
+        /// The URI of the document in the frame.
+        String Source { get; };
+    }
+}
+
 ```