Skip to content

Commit e7087aa

Browse files
LiangTheDevLiangTheDev
authored
Merge pull request #514 from MicrosoftEdge/api-host-resources
Host resources API Spec
2 parents d496de8 + e8a9e20 commit e7087aa

File tree

1 file changed

+192
-0
lines changed

1 file changed

+192
-0
lines changed

‎specs/HostResourceMapping.md

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Background
2+
We have received feedbacks that there is a need to access local files in WebView2. In this document we describe the APIs for this scenario. We'd appreciate your feedback.
3+
4+
5+
# Description
6+
To access local files in WebView2, define a virtual host name to local folder mapping using the `SetVirtualHostNameToFolderMapping` API,
7+
and then refer to local files under the folder with a normal http/https url with the virtual host name.
8+
9+
# Examples
10+
Suppose the app has index.html file in `asset` subfolder located on disk under the same path as the app's executable file.
11+
The following code snippet demonstrates how to define a mapping for `appassets.example` host name so that it can be accessed
12+
using normal http/https url like https://appassets.example/index.html.
13+
14+
## Win32 C++
15+
```cpp
16+
webview2->SetVirtualHostNameToFolderMapping(
17+
L"appassets.example", L"assets", COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY_CORS);
18+
webview2->Navigate(L"https://appassets.example/index.html");
19+
```
20+
21+
## .Net
22+
```c#
23+
webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
24+
"appassets.example",
25+
"assets", CoreWebView2HostResourceAccessKind.DenyCors);
26+
webView.Source = new Uri("https://appassets.example/index.html");
27+
```
28+
29+
## WinRT
30+
Suppose the app has index.html file in a `book1` subfolder under the app's LocalFolder folder. The following code snippet demonstrates how to define a mapping
31+
for `book1.example` host name so that it can be accessed using normal http/https url like https://book1.example/index.html.
32+
```c#
33+
Windows.Storage.StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;
34+
string book1Path = localFolder.Path + @"\book1";
35+
webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
36+
"book1.example",
37+
book1Path, CoreWebView2HostResourceAccessKind.DenyCors);
38+
webView.Source = new Uri("https://book1.example/index.html");
39+
```
40+
41+
42+
# Remarks
43+
You should typically choose virtual host names that are never used by real sites.
44+
If you own a domain such as example.com, another option is to use a subdomain reserved for the app (like my-app.example.com).
45+
[RFC 6761](https://tools.ietf.org/html/rfc6761) has reserved several special-use domain
46+
names that are guaranteed to not be used by real sites (for example, .example, .test, and
47+
.invalid.)
48+
Apps should use distinct domain names when mapping folder from different sources that
49+
should be isolated from each other. For instance, the app might use app-file.example for
50+
files that ship as part of the app, and book1.example might be used for files containing
51+
books from a less trusted source that were previously downloaded and saved to the disk by
52+
the app.
53+
The host name used in the APIs is canonicalized using Chromium's host name parsing logic
54+
before being used internally.
55+
All host names that are canonicalized to the same string are considered identical.
56+
For example, `EXAMPLE.COM` and `example.com` are treated as the same host name.
57+
An international host name and its Punycode-encoded host name are considered the same host
58+
name. There is no DNS resolution for host name and the trailing '.' is not normalized as
59+
part of canonicalization.
60+
Therefore `example.com` and `example.com.` are treated as different host names. Similarly,
61+
`virtual-host-name` and `virtual-host-name.example.com` are treated as different host names
62+
even if the machine has a DNS suffix of `example.com`.
63+
Specify the minimal cross-origin access necessary to run the app. If there is not a need to
64+
access local resources from other origins, use COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY.
65+
66+
# API Notes
67+
See [API Details](#api-details) section below for API reference.
68+
69+
# API Details
70+
71+
## Win32 C++
72+
The following table illustrates the host resource cross origin access according to
73+
access context and `COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND`.
74+
Cross Origin Access Context | DENY | ALLOW | DENY_CORS
75+
--- | --- | --- | ---
76+
From DOM like src of img, script or iframe element| Deny | Allow | Allow
77+
From Script like Fetch or XMLHttpRequest| Deny | Allow | Deny
78+
```IDL
79+
/// Kind of cross origin resource access allowed for host resources during download.
80+
/// Note that other normal access checks like same origin DOM access check and [Content
81+
/// Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) still apply.
82+
/// The following table illustrates the host resource cross origin access according to
83+
/// access context and `COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND`.
84+
/// Cross Origin Access Context | DENY | ALLOW | DENY_CORS
85+
/// --- | --- | --- | ---
86+
/// From DOM like src of img, script or iframe element| Deny | Allow | Allow
87+
/// From Script like Fetch or XMLHttpRequest| Deny | Allow | Deny
88+
[v1_enum]
89+
typedef enum COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND {
90+
/// All cross origin resource access is denied, including normal sub resource access
91+
/// as src of a script or image element.
92+
COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY,
93+
94+
/// All cross origin resource access is allowed, including accesses that are
95+
/// subject to Cross-Origin Resource Sharing(CORS) check. The behavior is similar to
96+
/// a web site sends back http header Access-Control-Allow-Origin: *.
97+
COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_ALLOW,
98+
99+
/// Cross origin resource access is allowed for normal sub resource access like
100+
/// as src of a script or image element, while any access that subjects to CORS check
101+
/// will be denied.
102+
/// See [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
103+
/// for more information.
104+
COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY_CORS,
105+
} COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND;
106+
107+
interface ICoreWebView2_2 : ICoreWebView2 {
108+
109+
/// Set a mapping between a virtual host name and a folder path to make available to web sites
110+
/// via that host name.
111+
///
112+
/// After setting the mapping, documents loaded in the WebView can use HTTP or HTTPS URLs at
113+
/// the specified host name specified by hostName to access files in the local folder specified
114+
/// by folderPath.
115+
///
116+
/// This mapping applies to both top-level document and iframe navigations as well as subresource
117+
/// references from a document. This also applies to dedicated and shared worker scripts but does
118+
/// not apply to service worker scripts.
119+
///
120+
/// accessKind specifies the level of access to resources under the virtual host from other sites.
121+
/// Both absolute and relative paths are supported for folderPath. Relative paths are interpreted
122+
/// as relative to the folder where the exe of the app is in.
123+
///
124+
/// For example, after calling
125+
/// ```
126+
/// SetVirtualHostNameToFolderMapping(
127+
/// L"appassets.example", L"assets",
128+
/// COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY);
129+
/// ```
130+
/// navigating to `https://appassets.example/my-local-file.html` will
131+
/// show content from my-local-file.html in the assets subfolder located on disk under the same
132+
/// path as the app's executable file.
133+
///
134+
/// You should typically choose virtual host names that are never used by real sites.
135+
/// If you own a domain such as example.com, another option is to use a subdomain reserved for
136+
/// the app (like my-app.example.com).
137+
///
138+
/// [RFC 6761](https://tools.ietf.org/html/rfc6761) has reserved several special-use domain
139+
/// names that are guaranteed to not be used by real sites (for example, .example, .test, and
140+
/// .invalid.)
141+
///
142+
/// Apps should use distinct domain names when mapping folder from different sources that
143+
/// should be isolated from each other. For instance, the app might use app-file.example for
144+
/// files that ship as part of the app, and book1.example might be used for files containing
145+
/// books from a less trusted source that were previously downloaded and saved to the disk by
146+
/// the app.
147+
///
148+
/// The host name used in the APIs is canonicalized using Chromium's host name parsing logic
149+
/// before being used internally.
150+
///
151+
/// All host names that are canonicalized to the same string are considered identical.
152+
/// For example, `EXAMPLE.COM` and `example.com` are treated as the same host name.
153+
/// An international host name and its Punycode-encoded host name are considered the same host
154+
/// name. There is no DNS resolution for host name and the trailing '.' is not normalized as
155+
/// part of canonicalization.
156+
///
157+
/// Therefore `example.com` and `example.com.` are treated as different host names. Similarly,
158+
/// `virtual-host-name` and `virtual-host-name.example.com` are treated as different host names
159+
/// even if the machine has a DNS suffix of `example.com`.
160+
///
161+
/// Specify the minimal cross-origin access necessary to run the app. If there is not a need to
162+
/// access local resources from other origins, use COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY.
163+
HRESULT SetVirtualHostNameToFolderMapping(
164+
[in] LPCWSTR hostName,
165+
[in] LPCWSTR folderPath,
166+
[in] COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND accessKind);
167+
/// Clear a host name mapping for local folder that was added by SetVirtualHostNameToFolderMapping.
168+
HRESULT ClearVirtualHostNameToFolderMapping(
169+
[in] LPCWSTR hostName);
170+
}
171+
```
172+
173+
## .Net WinRT
174+
175+
```c#
176+
namespace Microsoft.Web.WebView2.Core
177+
{
178+
public enum CoreWebView2HostResourceAccessKind
179+
{
180+
Deny = 0,
181+
Allow = 1,
182+
DenyCors = 2
183+
}
184+
185+
public partial class CoreWebView2
186+
{
187+
// There are other API in this interface that we are not showing
188+
public void SetVirtualHostNameToFolderMapping(string hostName, string folderPath, CoreWebView2HostResourceAccessKind accessKind);
189+
public void ClearVirtualHostNameToFolderMapping(string hostName);
190+
}
191+
}
192+
```

0 commit comments

Comments
 (0)