Skip to content

Commit 7e84b2d

Browse files
LiangTheDevLiangTheDev
authored
Update HostResourceMapping.md
1 parent f15bc3d commit 7e84b2d

File tree

1 file changed

+97
-26
lines changed

1 file changed

+97
-26
lines changed

‎specs/HostResourceMapping.md

Lines changed: 97 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,34 +3,55 @@ We have received feedbacks that there is a need to access local files in WebView
33

44

55
# Description
6-
To access local files in WebView2, define a virutal host name to local folder mapping using the `AddVirtualHostNameToFolderMapping` API,
6+
To access local files in WebView2, define a virtual host name to local folder mapping using the `SetVirtualHostNameToFolderMapping` API,
77
and then refer to local files under the folder with a normal http/https url with the virtual host name.
88

99
# Examples
10-
Suppose the app has index.html file next to its exe file. The following code snippet demonstrates how to define a mapping
11-
for `app-file.invalid` host name so that it can be accessed from pages using normal http/https url like https://app-file.invalid/index.html.
10+
Suppose the app has index.html file in `asset` sub folder in the folder where its exe file is. The following code snippet demonstrates how to define a mapping
11+
for `appassets.webview2.microsoft.com` host name so that it can be accessed using normal http/https url like https://appassets.webview2.microsoft.com/index.html.
1212

1313
## Win32 C++
1414
```cpp
15-
webview2->AddVirtualHostNameToFolderMapping(
16-
L"app-file.invalid", L".", COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY_CORS);
17-
webview2->Navigate("https://app-file.invalid/index.html");
15+
webview2->SetVirtualHostNameToFolderMapping(
16+
L"appassets.webview2.microsoft.com", L"assets", COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY_CORS);
17+
webview2->Navigate(L"https://appassets.webview2.microsoft.com/index.html");
1818
```
1919
20-
## .Net and WinRT
20+
## .Net
2121
```c#
22-
webView.CoreWebView2.AddVirtualHostNameToFolderMapping(
23-
"app-file.invalid", ".", CoreWebView2HostResourceAccessKind.DenyCors);
24-
webView.Navigate("https://app-file.invalid/index.html");
22+
webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
23+
"appassets.webview2.microsoft.com",
24+
"assets", CoreWebView2HostResourceAccessKind.DenyCors);
25+
webView.Source = new Uri("https://appassets.webview2.microsoft.com/index.html");
2526
```
2627

28+
## WinRT
29+
Suppose the app has index.html file in a `book1` sub folder of the app's LocalFolder folder. The following code snippet demonstrates how to define a mapping
30+
for `book1.appassets.webview2.microsoft.com` host name so that it can be accessed using normal http/https url like https://book1.appassets.webview2.microsoft.com/index.html.
31+
```c#
32+
Windows.Storage.StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;
33+
string book1_path = localFolder.Path + @"\book1";
34+
webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
35+
new Windows.Networking.HostName("book1.appassets.webview2.microsoft.com"),
36+
book1_path, CoreWebView2HostResourceAccessKind.DenyCors);
37+
webView.Source = new Uri("https://book1.appassets.webview2.microsoft.com/index.html");
38+
```
39+
40+
2741
# Remarks
2842
Choose a virtual host name that will not be used by real sites.
2943
If you own a domain (like example.com), an option is to use a sub domain reserved for the app (like my-app.example.com).
30-
If you don't own a domain, [RFC 6761](https://tools.ietf.org/html/rfc6761) has reserved several special-use domain names that would
31-
not be used by real sites, like .example, .test, and .invalid.
44+
We have also reserved a special domain appassets.webview2.microsoft.com for this usage.
45+
46+
The host name used in the APIs is canonicalized using Chromium's host name parsing logic
47+
before being used internally.
48+
All host names that are canonicalized to the same string are considered identical.
49+
For example, `EXAMPLE.COM` and `example.com` are considered the same host name.
50+
An international host name and its puny coded host name are considered the same host name.
51+
There is no DSN resolution for host name and trailing '.' is not normalized as part of canonicalization.
52+
Therefore `example.com` and `example.com.` are treated as different host names. So are `virtual-host-name` and `virtual-host-name.example.com` when the DNS suffix of the machine is `example.com`.
3253

33-
Give only minimal cross orign access neccessary to run the app. If there is no need to access local resources
54+
Give only minimal cross origin access necessary to run the app. If there is no need to access local resources
3455
from other origins, use COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY.
3556

3657
# API Notes
@@ -39,15 +60,22 @@ See [API Details](#api-details) section below for API reference.
3960
# API Details
4061

4162
## Win32 C++
42-
The follow table illustrates the host resource cross origin access according to access context and `COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND`.
63+
The following table illustrates the host resource cross origin access according to
64+
access context and `COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND`.
4365
Cross Origin Access Context | DENY | ALLOW | DENY_CORS
4466
--- | --- | --- | ---
45-
From DOM like src of img or script element| Deny | Allow | Allow
67+
From DOM like src of img, script or iframe element| Deny | Allow | Allow
4668
From Script like Fetch or XMLHttpRequest| Deny | Allow | Deny
4769
```IDL
4870
/// Kind of cross origin resource access allowed for host resources during download.
4971
/// Note that other normal access checks like same origin DOM access check and [Content
5072
/// Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) still apply.
73+
/// The following table illustrates the host resource cross origin access according to
74+
/// access context and `COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND`.
75+
/// Cross Origin Access Context | DENY | ALLOW | DENY_CORS
76+
/// --- | --- | --- | ---
77+
/// From DOM like src of img, script or iframe element| Deny | Allow | Allow
78+
/// From Script like Fetch or XMLHttpRequest| Deny | Allow | Deny
5179
[v1_enum]
5280
typedef enum COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND {
5381
/// All cross origin resource access is denied, including normal sub resource access
@@ -69,25 +97,68 @@ typedef enum COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND {
6997
7098
interface ICoreWebView2_2 : ICoreWebView2 {
7199
72-
/// Add a host name mapping for host resources in a folder.
73-
/// After adding the mapping, the app can then use http or https urls with the specified hostName as host name
100+
/// Set a mapping between a virtual host name and host resources in a folder.
101+
/// After setting the mapping, the app can then use http or https urls with the specified hostName as host name
74102
/// of the urls to access files in the local folder specified by folderPath.
75103
/// This applies to top level document and iframe navigations as well as sub resource references from a document.
104+
/// This also applies to dedicated and shared worker scripts, but does not apply to service worker scripts.
76105
/// accessKind specifies the kind of access control to the host resources from other sites.
77-
/// Relative folderPath is supported and interpreted as relative to the exe path of the app.
78-
/// For example, after calling AddVirtualHostNameToFolderMapping(L"app-file.invalid", L".",
79-
/// COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY), navigating to https://app-file.invalid/my-local-file.html
80-
/// will show content from my-local-file.html in the same folder as the app's exe file.
81-
HRESULT AddVirtualHostNameToFolderMapping(
106+
/// Both absolute and relative path are supported for folderPath. Relative path is interpreted as relative
107+
/// to the folder where the exe of the app is in.
108+
/// For example, after calling AddVirtualHostNameToFolderMapping(L"appassets.webview2.microsoft.com", L"assets",
109+
/// COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY), navigating to https://appassets.webview2.microsoft.com/my-local-file.html
110+
/// will show content from my-local-file.html in the assets sub folder of the folder that has the app's exe file.
111+
///
112+
/// Choose a virtual host name that will not be used by real sites.
113+
/// If you own a domain (like example.com), an option is to use a sub domain reserved for
114+
/// the app (like my-app.example.com).
115+
/// We have also reserved a special domain appassets.webview2.microsoft.com for this usage.
116+
///
117+
/// The host name used in the APIs is canonicalized using Chromium's host name parsing logic
118+
/// before being used internally.
119+
/// All host names that are canonicalized to the same string are considered identical.
120+
/// For example, `EXAMPLE.COM` and `example.com` are considered the same host name.
121+
/// An international host name and its puny coded host name are considered the same host name.
122+
/// There is no DSN resolution for host name and trailing '.' is not normalized as part of canonicalization.
123+
/// Therefore `example.com` and `example.com.` are treated as different host names. So are
124+
/// `virtual-host-name` and `virtual-host-name.example.com` when the DNS suffix of the machine is `example.com`.
125+
///
126+
/// Give only minimal cross origin access necessary to run the app. If there is no need to
127+
/// access local resources from other origins, use COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY.
128+
///
129+
HRESULT SetVirtualHostNameToFolderMapping(
82130
[in] LPCWSTR hostName,
83131
[in] LPCWSTR folderPath,
84132
[in] COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND accessKind);
85-
/// Remove a host name mapping for local folder that was added by AddVirtualHostNameToFolderMapping.
86-
HRESULT RemoveVirtualHostNameToFolderMapping(
133+
/// Clear a host name mapping for local folder that was added by SetVirtualHostNameToFolderMapping.
134+
HRESULT ClearVirtualHostNameToFolderMapping(
87135
[in] LPCWSTR hostName);
88136
}
89137
```
90138

139+
## .Net
140+
141+
```c#
142+
namespace Microsoft.Web.WebView2.Core
143+
{
144+
public enum CoreWebView2HostResourceAccessKind
145+
{
146+
Deny = 0,
147+
Allow = 1,
148+
DenyCors = 2
149+
}
150+
151+
public partial class CoreWebView2
152+
{
153+
// There are other API in this interface that we are not showing
154+
public void SetVirtualHostNameToFolderMapping(string hostName, string folderPath, CoreWebView2HostResourceAccessKind accessKind);
155+
public void ClearVirtualHostNameToFolderMapping(string hostName);
156+
}
157+
}
158+
```
159+
160+
## WinRT
161+
91162
```c#
92163
namespace Microsoft.Web.WebView2.Core
93164
{
@@ -101,8 +172,8 @@ namespace Microsoft.Web.WebView2.Core
101172
public partial class CoreWebView2
102173
{
103174
// There are other API in this interface that we are not showing
104-
public void AddVirtualHostNameToFolderMapping(string hostName, string folderPath, CoreWebView2HostResourceAccessKind accessKind);
105-
public void RemoveVirtualHostNameToFolderMapping(string hostName);
175+
public void SetVirtualHostNameToFolderMapping(Windows.Networking.HostName hostName, string folderPath, CoreWebView2HostResourceAccessKind accessKind);
176+
public void ClearVirtualHostNameToFolderMapping(string hostName);
106177
}
107178
}
108179
```

0 commit comments

Comments
 (0)