Skip to content

Commit 3e68a0b

Browse files
Master-UkuleleMaster-Ukulele
authored
Add descriptions and win32 codes
1 parent 2544d98 commit 3e68a0b

2 files changed

Lines changed: 163 additions & 27 deletions

File tree

‎specs/DangerousFileSecurityDialog.md‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎specs/FileTypePolicy.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
File Type Policy API
2+
===
3+
4+
# Background
5+
When saving a file with original SaveFilePicker, a security alert might be
6+
prompted, because the browser applies the [file type policies](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-security-downloads-interruptions#file-types-requiring-a-gesture)
7+
to protect end users. However, in a WebView2 build App, when end users try
8+
to save a file with a certain file extension, they usually can trust the
9+
host App, domain and file extension. So, we provide the App developers the
10+
File Type Policy API to manage the file type policies dynamically.
11+
12+
We'd appreciate your feedback.
13+
14+
# Description
15+
16+
We proposed the `CoreWebView2.FileTypePolicyChecking` event. You can register
17+
this event to get the file path, file extension and domain uri information,
18+
when end users try to save a file from your App. Then you can apply your own
19+
rules to allow save the file with, or without a default warning dialog;
20+
to cancel the saving; and even to create your own UI to manage runtime
21+
file type policies.
22+
23+
# Examples
24+
## Win32 C++
25+
This example shows suppressing file type policy, security dialog, and
26+
allow to save the file directly. It also blocks saving the exe file.
27+
The sample code will register the event with custom rules.
28+
```c++
29+
bool ScenarioFileTypePolicyStaging::AddCustomFileTypePolicies()
30+
{
31+
if (!m_webView2Staging25)
32+
return false;
33+
// Register a handler for the `FileTypePolicyChecking` event.
34+
m_webView2Staging25->add_FileTypePolicyChecking(
35+
Callback<ICoreWebView2StagingFileTypePolicyCheckingEventHandler>(
36+
[this](
37+
ICoreWebView2* sender,
38+
ICoreWebView2StagingFileTypePolicyCheckingEventArgs* args) -> HRESULT
39+
{
40+
LPWSTR extension;
41+
// Get the file extension for file to be saved.
42+
CHECK_FAILURE(args->get_FileExtension(&extension));
43+
// Create your own rules of file type policy.
44+
if (lstrcmpW(extension, L"eml") == 0)
45+
// Set the `SuppressDefaultPolicy` property to skip the default
46+
// file type policy checking and a possible security alert dialog.
47+
//
48+
// This will consent to save the file.
49+
CHECK_FAILURE(args->put_SuppressDefaultPolicy(TRUE));
50+
if (lstrcmpW(extension, L"exe") == 0)
51+
// Set the `Cancel` property to cancel the saving directly.
52+
//
53+
// This will abort to save the file.
54+
CHECK_FAILURE(args->put_Cancel(TRUE));
55+
wil::com_ptr<ICoreWebView2Deferral> deferral;
56+
CHECK_FAILURE(args->GetDeferral(&deferral));
57+
58+
m_appWindow->RunAsync([deferral]() { CHECK_FAILURE(deferral->Complete()); });
59+
60+
return S_OK;
61+
})
62+
.Get(),
63+
&m_fileTypePolicyCheckingToken);
64+
return true;
65+
}
66+
```
67+
68+
## .Net/ WinRT
69+
###
70+
```c#
71+
```
72+
73+
# API Details
74+
## Win32 C++
75+
```c++
76+
interface ICoreWebView2 : IUnknown {
77+
/// Adds an event handler for the `FileTypePolicyChecking` event.
78+
/// This event will be raised during system FileTypePolicy
79+
/// checking the dangerous file extension list.
80+
///
81+
/// Developers can specify their own decision on if allow this file
82+
/// type extension to be saved, or downloaded. Here are two properties
83+
/// in `ICoreWebView2FileTypePolicyCheckingEventArgs` to manage the
84+
/// decision, `Cancel` and `SuppressDefaultPolicy`.
85+
/// Table of Properties' value and result:
86+
///
87+
/// | Cancel | SuppressDefaultPolicy | Result
88+
/// | ------ | ------ | ---------------------
89+
/// | False | False | Process to default policy check. It might show
90+
/// | | | security warning UI if the file extension is
91+
/// | | | dangerous.
92+
/// | ------ | ------ | ---------------------
93+
/// | False | True | Skip the default policy check and the possible
94+
/// | | | security warning. Start saving or downloading.
95+
/// | ------ | ------ | ---------------------
96+
/// | True | T or F | Skip the default policy check and the possible
97+
/// | | | security warning. Abort save or download.
98+
HRESULT add_FileTypePolicyChecking(
99+
[in] ICoreWebView2StagingFileTypePolicyCheckingEventHandler* eventHandler,
100+
[out] EventRegistrationToken* token);
101+
102+
/// Removes an event handler previously added with `add_FileTypePolicyChecking`.
103+
HRESULT remove_FileTypePolicyChecking(
104+
[in] EventRegistrationToken token);
105+
}
106+
107+
108+
/// The event args for `FileTypePolicyChecking` event.
109+
interface ICoreWebView2StagingFileTypePolicyCheckingEventArgs : IUnknown {
110+
/// Gets the `Cancel` property.
111+
[propget] HRESULT Cancel([out, retval] BOOL* value);
112+
113+
/// Set if cancel the upcoming save/download. `TRUE` means the action
114+
/// will be cancelled before validations in default policy.
115+
///
116+
/// The default value is `FALSE`.
117+
[propput] HRESULT Cancel([in] BOOL value);
118+
119+
/// Get the extension of file to be saved.
120+
///
121+
/// File extension can be empty.
122+
///
123+
/// Only final extension will be provided. For example, "*.tar.gz"
124+
/// is a double extension, where the "gz" will be its final extension.
125+
///
126+
/// File extension usage in the API is case sensitive.
127+
[propget] HRESULT FileExtension([out, retval] LPWSTR* value);
128+
129+
/// Get the full path of file to be saved. This includes the
130+
/// file name and extension.
131+
[propget] HRESULT FilePath([out, retval] LPWSTR* value);
132+
133+
/// Gets the `SuppressDefaultPolicy` property.
134+
[propget] HRESULT SuppressDefaultPolicy([out, retval] BOOL* value);
135+
136+
/// Set if the default policy checking and security warning will be
137+
/// suppressed. `TRUE` means it will be suppressed.
138+
///
139+
/// The default value is `FALSE`.
140+
[propput] HRESULT SuppressDefaultPolicy([in] BOOL value);
141+
142+
/// Get the uri of file source.
143+
[propget] HRESULT Uri([out, retval] LPWSTR* value);
144+
145+
/// Returns an `ICoreWebView2Deferral` object. Use this operation to complete
146+
/// the FileTypePolicyCheckingEvent.
147+
HRESULT GetDeferral(
148+
[out, retval] ICoreWebView2Deferral** value
149+
);
150+
}
151+
152+
/// Receives `FileTypePolicyChecking` events.
153+
interface ICoreWebView2StagingFileTypePolicyCheckingEventHandler : IUnknown {
154+
/// Provides the event args for the corresponding event.
155+
HRESULT Invoke(
156+
[in] ICoreWebView2* sender,
157+
[in] ICoreWebView2StagingFileTypePolicyCheckingEventArgs* args);
158+
}
159+
```
160+
161+
## .Net/ WinRT
162+
```c# (but really MIDL3)
163+
```

0 commit comments

Comments
 (0)