Add spec for ProgrammaticSaveAs.md

specs/ProgrammaticSaveAs.md

@@ -0,0 +1,396 @@
+Programmatic Save As API
+===
+
+# Background
+
+Chromium browser's context menus have a "Save as" menu item to save the document
+(html page, image, pdf, or other content) through a save as dialog. We provide
+more flexible ways to programmatically perform the Save As operation in WebView2.
+
+With the new API you will be able to:
+- Launch the default save as dialog
+- Block the default save as dialog
+- Request save as silently by providing the path and save as kind
+- Build your own save as UI
+
+The chromium browser's Save As operation consists of showing the Save As dialog 
+and then starting a download of the document. The Save As method and event
+described in this document relate to the Save As dialog and not the download,
+which will go through the existing WebView2 download APIs. 
+
+We'd appreciate your feedback.
+
+# Description
+
+We propose the `CoreWebView2.ShowSaveAsUI` method, which allows you to trigger 
+the Save As UX programmatically. By using this method, the system default dialog, 
+or your own UI will show and start the Save As operation.
+
+We also propose the `CoreWebView2.SaveAsUIShowing` event. You can register this event to block 
+the default dialog and instead create your own Save As UI using the `SaveAsUIShowingEventArgs`, 
+to set your preferred save as path, save as kind, and duplicate file replacement rule. 
+In your client app, you can design your own UI to input these parameters. 
+For HTML documents, we support 3 save as kinds: HTML_ONLY, SINGLE_FILE and 
+COMPLETE. Non-HTML documents, you must use DEFAULT, which will save the content as 
+it is. This API has default values for all parameters, to perform the common 
+save as operation.
+
+# Examples
+## Win32 C++ 
+### Programmatic Save As
+This example hides the default save as dialog and shows a customized dialog.
+The sample code will register a handler and trigger programmaic save as once.
+```c++
+bool ScenarioSaveAs::ProgrammaticSaveAs()
+{
+    if (!m_webView2_24)
+        return false;
+
+    // Register a handler for the `SaveAsUIShowing` event.
+    m_webView2_24->add_SaveAsUIShowing(
+        Callback<ICoreWebView2SaveAsUIShowingEventHandler>(
+            [this](
+            ICoreWebView2* sender,
+                ICoreWebView2SaveAsUIShowingEventArgs* args) -> HRESULT
+            {
+                // Hide the system default save as dialog.
+                CHECK_FAILURE(args->put_SuppressDefaultDialog(TRUE));
+
+                auto showCustomizedDialog = [this, args = wil:: make_com_ptr(args)]
+                {
+                    // As an end developer, you can design your own dialog UI, or no UI at all.
+                    // You can ask the user to provide information like file name, file extension, 
+                    // and so on. Finally, and set them on the event args.
+                    //
+                    // This is a customized dialog example, the constructor returns after the 
+                    // dialog interaction is completed by the end user.
+                    SaveAsDialog dialog;
+                    if (dialog.confirmed)
+                    {
+                        // Setting the SaveAsFilePath, Kind, AllowReplace for the event
+                        // args from this customized dialog inputs is optional. The event 
+                        // args has default values based on the document to save.
+                        //
+                        // Additionally, you can use `get_ContentMimeType` to check the mime 
+                        // type of the document that will be saved to help the Kind selection.
+                        CHECK_FAILURE(
+                            args->put_SaveAsFilePath((LPCWSTR)dialog.path.c_str()));
+                        CHECK_FAILURE(args->put_Kind(dialog.selectedKind));
+                        CHECK_FAILURE(args->put_AllowReplace(dialog.allowReplace));
+                    }
+                    else
+                    {
+                        // Save As cancelled from this customized dialog.
+                        CHECK_FAILURE(args->put_Cancel(TRUE));
+                    }
+                };
+
+                wil::com_ptr<ICoreWebView2Deferral> deferral;
+                CHECK_FAILURE(args->GetDeferral(&deferral));
+
+                m_appWindow->RunAsync(
+                    [deferral, showCustomizedDialog]()
+                    {
+                        showCustomizedDialog();
+                        CHECK_FAILURE(deferral->Complete());
+                    });
+                return S_OK;
+            })
+            .Get(),
+        &m_SaveAsUIShowingToken);
+
+    // Call method ShowSaveAsUI to trigger the programmatic save as once.
+    m_webView2_24->ShowSaveAsUI(
+        Callback<ICoreWebView2ShowSaveAsUICompletedHandler>(
+            [this](HRESULT errorCode, COREWEBVIEW2_SAVE_AS_UI_RESULT result) -> HRESULT
+            {
+                // Show ShowSaveAsUI returned result, optional. See
+                // COREWEBVIEW2_SAVE_AS_UI_RESULT for more details.
+                MessageBox(
+                    m_appWindow->GetMainWindow(),
+                    (L"Save As " + saveAsUIString[result]).c_str(), L"Info", MB_OK);
+                return S_OK;
+            })
+            .Get());
+    return true;
+}
+```
+
+## .Net/ WinRT
+### Programmatic Save As
+This example hides the default save as dialog and shows a customized dialog.
+The sample code will register a handler and trigger programmaic save as once.
+```c#
+
+async void ProgrammaticSaveAsExecuted(object target, ExecutedRoutedEventArgs e)
+{
+    // Register a handler for the `SaveAsUIShowing` event.
+    webView.CoreWebView2.SaveAsUIShowing += (sender, args) =>
+    {
+        // Hide the system default save as dialog.
+        args.SuppressDefaultDialog = true;
+
+        // Developer can obtain a deferral for the event so that the CoreWebView2
+        // doesn't examine the properties we set on the event args until
+        // after the deferral completes asynchronously.
+        CoreWebView2Deferral deferral = args.GetDeferral();
+
+        // We avoid potential reentrancy from running a message loop in the event
+        // handler. Show the customized dialog later then complete the deferral
+        // asynchronously.
+        System.Threading.SynchronizationContext.Current.Post((_) =>
+        {
+            using (deferral)
+            {
+                // This is a customized dialog example.
+                var dialog = new SaveAsDialog();
+                if (dialog.ShowDialog() == true)
+                {
+                    // Setting parameters of event args from this dialog is optional.
+                    // The event args has default values.
+                    //
+                    // Additionally, you can use `args.ContentMimeType` to check the mime 
+                    // type of the document that will be saved to help the Kind selection.
+                    args.SaveAsFilePath = System.IO.Path.Combine(
+                        dialog.Directory.Text, dialog.Filename.Text);
+                    args.Kind = (CoreWebView2SaveAsKind)dialog.Kind.SelectedItem;
+                    args.AllowReplace = (bool)dialog.AllowReplaceOldFile.IsChecked;
+                }
+                else
+                {
+                    // Save As cancelled from this customized dialog.
+                    args.Cancel = true;
+                }
+            }
+        }, null);
+    };
+
+    // Call ShowSaveAsUIAsync method to trigger the programmatic save as once.
+    CoreWebView2SaveAsUIResult result = await webView.CoreWebView2.ShowSaveAsUIAsync();
+    // Show ShowSaveAsUIAsync returned result, optional. See
+    // CoreWebView2SaveAsUIResult for more details.
+    MessageBox.Show(result.ToString(), "Info");
+}
+```
+
+# API Details
+## Win32 C++
+```c++
+/// Specifies save as kind selection options for 
+/// `ICoreWebView2SaveAsUIShowingEventArgs`.
+///
+/// For HTML documents, we support 3 save as kinds: HTML_ONLY, SINGLE_FILE and 
+/// COMPLETE. Non-HTML documents, you must use DEFAULT. MIME type of `text/html`,
+/// `application/xhtml+xml` are considered as HTML documents.
+[v1_enum] typedef enum COREWEBVIEW2_SAVE_AS_KIND {
+  /// Default to save for a non-html content. If it is selected for a html
+  /// page, it's same as HTML_ONLY option.
+  COREWEBVIEW2_SAVE_AS_KIND_DEFAULT,
+  /// Save the page as html. It only saves top-level document, excludes
+  /// subresource.
+  COREWEBVIEW2_SAVE_AS_KIND_HTML_ONLY,
+  /// Save the page as mhtml.
+  /// Read more about mhtml at (https://en.wikipedia.org/wiki/MHTML)
+  COREWEBVIEW2_SAVE_AS_KIND_SINGLE_FILE,
+  /// Save the page as html, plus, download the page related source files 
+  /// (for example CSS, JavaScript, images, and so on) in a directory with 
+  /// the same filename prefix.
+  COREWEBVIEW2_SAVE_AS_KIND_COMPLETE,
+} COREWEBVIEW2_SAVE_AS_KIND;
+
+/// Status of a programmatic save as call, indicates the result
+/// for method `ShowSaveAsUI`.
+[v1_enum] typedef enum COREWEBVIEW2_SAVE_AS_UI_RESULT {
+  /// The ShowSaveAsUI method call completed successfully. By defaut the the system 
+  /// save as dialog will open. If `SuppressDefaultDialog` is set to TRUE, will skip
+  /// the system dialog, and start the download.
+  COREWEBVIEW2_SAVE_AS_UI_RESULT_SUCCESS,
+  /// Could not perform Save As because the destination file path is an invalid path.
+  ///
+  /// It is considered as invalid when the path is empty, a relative path, a directory,
+  /// or the parent path doesn't exist.
+  COREWEBVIEW2_SAVE_AS_UI_RESULT_INVALID_PATH,
+  /// Could not perform Save As because the destination file path already exists and 
+  /// replacing files was not allowed by the `AllowReplace` property.
+  COREWEBVIEW2_SAVE_AS_UI_RESULT_FILE_ALREADY_EXISTS,
+  /// Could not perform Save As when the `Kind` property selection not
+  /// supported because of the content MIME type or system limits.
+  ///
+  /// MIME type limits please see the emun `COREWEBVIEW2_SAVE_AS_KIND`.
+  ///
+  /// System limits might happen when select `HTML_ONLY` for an error page at child
+  /// mode, select `COMPLETE` and WebView running in an App Container, etc.
+  COREWEBVIEW2_SAVE_AS_UI_RESULT_KIND_NOT_SUPPORTED,
+  /// Did not perform Save As because the end user cancelled or the 
+  /// CoreWebView2SaveAsUIShowingEventArgs.Cancel property was set to TRUE.
+  COREWEBVIEW2_SAVE_AS_UI_RESULT_CANCELLED,
+} COREWEBVIEW2_SAVE_AS_UI_RESULT;
+
+[uuid(15e1c6a3-c72a-4df3-91d7-d097fbec3bfd), object, pointer_default(unique)]
+interface ICoreWebView2_24 : IUnknown {
+  /// Programmatically trigger a save as action for the currently loaded document.
+  /// The `SaveAsUIShowing` event will be raised.
+  ///
+  /// Opens a system modal dialog by default. If the `SuppressDefaultDialog` is TRUE, 
+  /// won't open the system dialog.
+  ///
+  /// The method can return a detailed info to indicate the call's result. 
+  /// Please see COREWEBVIEW2_SAVE_AS_UI_RESULT.
+  ///
+  /// \snippet ScenarioSaveAs.cpp ProgrammaticSaveAs
+  HRESULT ShowSaveAsUI([in] ICoreWebView2ShowSaveAsUICompletedHandler* handler);
+
+  /// Add an event handler for the `SaveAsUIShowing` event. This event is raised
+  /// when save as is triggered, programmatically or manually.
+  HRESULT add_SaveAsUIShowing(
+   [in] ICoreWebView2SaveAsUIShowingEventHandler* eventHanlder,
+   [out] EventRegistrationToken* token);
+
+  /// Remove an event handler previously added with `add_SaveAsUIShowing`.
+  HRESULT remove_SaveAsUIShowing(
+   [in] EventRegistrationToken token);
+}
+
+/// The event handler for the `SaveAsUIShowing` event.
+[uuid(55b86cd2-adfd-47f1-9cef-cdfb8c414ed3), object, pointer_default(unique)]
+interface ICoreWebView2SaveAsUIShowingEventHandler : IUnknown {
+  HRESULT Invoke(
+   [in] ICoreWebView2* sender,
+   [in] ICoreWebView2SaveAsUIShowingEventArgs* args);
+}
+
+/// The event args for `SaveAsUIShowing` event.
+[uuid(80101027-b8c3-49a1-a052-9ea4bd63ba47), object, pointer_default(unique)]
+interface ICoreWebView2SaveAsUIShowingEventArgs : IUnknown {
+  /// Get the Mime type of content to be saved.
+  [propget] HRESULT ContentMimeType([out, retval] LPWSTR* value);
+
+  /// You can set this to TRUE to cancel the Save As. Then the download won't start. 
+  /// A programmatic call will return COREWEBVIEW2_SAVE_AS_UI_RESULT_CANCELLED as well. 
+  ///
+  /// The default value is FALSE.
+  ///
+  /// Set the `Cancel` for save as.
+  [propput] HRESULT Cancel ([in] BOOL value);
+
+  /// Get the `Cancel` for save as.
+  [propget] HRESULT Cancel ([out, retval] BOOL* value);
+
+  /// Indicates if the system default dialog will be suppressed, FALSE means
+  /// save as default dialog will show; TRUE means a silent save as, will
+  /// skip the system dialog. 
+  ///
+  /// The default value is FALSE.
+  ///
+  /// Set the `SuppressDefaultDialog`.
+  [propput] HRESULT SuppressDefaultDialog([in] BOOL value);
+
+  /// Get the `SuppressDefaultDialog`.
+  [propget] HRESULT SuppressDefaultDialog([out, retval] BOOL* value);
+
+  /// Returns an `ICoreWebView2Deferral` object. This will defer showing the 
+  /// default Save As dialog and performing the Save As operation.
+  HRESULT GetDeferral([out, retval] ICoreWebView2Deferral** deferral);
+
+  /// `SaveAsFilePath` is absolute full path of the location. It includes the file name
+  /// and extension. If `SaveAsFilePath` is not valid, for example the root drive does
+  /// not exist, save as will be denied and return COREWEBVIEW2_SAVE_AS_UI_RESULT_INVALID_PATH.
+  ///
+  /// If the associated download completes successfully, a target file will be saved at 
+  /// this location. If the Kind property is `COREWEBVIEW2_SAVE_AS_KIND_COMPLETE`, 
+  /// there will be an additional directory with resources files.
+  ///
+  /// The default value is a system suggested path, based on users' local environment.
+  /// 
+  /// Set the `SaveAsFilePath` for save as.
+  [propput] HRESULT SaveAsFilePath ([in] LPCWSTR value);
+
+  /// Get the `SaveAsFilePath` for save as.
+  [propget] HRESULT SaveAsFilePath ([out, retval] LPWSTR* value);
+
+  /// `AllowReplace` allows you to control what happens when a file already 
+  /// exists in the file path to which the Save As operation is saving.
+  /// Setting this TRUE allows existing files to be replaced.
+  /// Setting this FALSE will not replace existing files and will return
+  /// COREWEBVIEW2_SAVE_AS_UI_RESULT_FILE_ALREADY_EXISTS.
+  ///
+  /// The default value is FALSE.
+  ///
+  /// Set if allowed to replace the old file if duplicate happens in the save as.
+  [propput] HRESULT AllowReplace ([in] BOOL value);
+
+  /// Get the duplicates replace rule for save as.
+  [propget] HRESULT AllowReplace ([out, retval] BOOL* value);
+
+  /// How to save documents with different kind. See the enum 
+  /// COREWEBVIEW2_SAVE_AS_KIND for a description of the different options.  
+  /// If the kind isn't allowed for the current document, 
+  /// COREWEBVIEW2_SAVE_AS_UI_RESULT_KIND_NOT_SUPPORTED will be returned from
+  /// ShowSaveAsUI.
+  ///
+  /// The default value is COREWEBVIEW2_SAVE_AS_KIND_DEFAULT.
+  ///
+  /// Set the kind for save as.
+  [propput] HRESULT Kind ([in] COREWEBVIEW2_SAVE_AS_KIND value);
+
+  /// Get the kind for save as.
+  [propget] HRESULT Kind ([out, retval] COREWEBVIEW2_SAVE_AS_KIND* value);
+}
+
+/// Receive the result for `ShowSaveAsUI` method.
+[uuid(1a02e9d9-14d3-41c6-9581-8d6e1e6f50fe), object, pointer_default(unique)]
+interface ICoreWebView2ShowSaveAsUICompletedHandler : IUnknown {
+  HRESULT Invoke([in] HRESULT errorCode, [in] COREWEBVIEW2_SAVE_AS_UI_RESULT result);
+}
+```
+
+## .Net/ WinRT
+```c# (but really MIDL3)
+namespace Microsoft.Web.WebView2.Core
+{
+
+    runtimeclass CoreWebView2SaveAsUIShowingEventArgs; 
+    runtimeclass CoreWebView2;
+
+    enum CoreWebView2SaveAsUIResult
+    {   
+        Success = 0,
+        InvalidPath = 1,
+        FileAlreadyExists = 2,
+        KindNotSupported = 3,
+        Cancelled = 4,
+    };
+
+    enum CoreWebView2SaveAsKind
+    {
+        Default = 0,
+        HtmlOnly = 1,
+        SingleFile = 2,
+        Complete = 3,
+    };
+
+    runtimeclass CoreWebView2SaveAsUIShowingEventArgs
+    {
+        String ContentMimeType { get; };
+        Boolean Cancel { get; set; };
+        Boolean SuppressDefaultDialog { get; set; };
+        String SaveAsFilePath { get; set; };
+        Boolean AllowReplace { get; set; };
+        CoreWebView2SaveAsKind Kind { get; set; };
+        Windows.Foundation.Deferral GetDeferral();
+    };
+
+    runtimeclass CoreWebView2
+    {
+        // ...
+
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_24")]
+        {
+            event Windows.Foundation.TypedEventHandler
+                <CoreWebView2, CoreWebView2SaveAsUIShowingEventArgs> SaveAsUIShowing;
+            Windows.Foundation.IAsyncOperation<CoreWebView2SaveAsUIResult > 
+                ShowSaveAsUIAsync();
+        }
+    };
+}
+```