Skip to content

Commit 5941905

Browse files
author
Çağrı Kaan Yıldırım
authored
Merge pull request #483 from MicrosoftEdge/api-navigate-with-web-resource-request
API Spec for NavigateWithWebResourceRequest
2 parents ec0a62a + 4ddd96f commit 5941905

1 file changed

Lines changed: 142 additions & 0 deletions

File tree

‎specs/NavigateWithWebResourceRequest.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
2+
# Background
3+
Consumers of the old WebBrowser control that relied on the [Navigate](https://docs.microsoft.com/en-us/previous-versions/aa752133(v=vs.85)) API that allowed them to specify HTTP POST data and extra headers as part of navigation, [requested](https://github.com/MicrosoftEdge/WebViewFeedback/issues/69) same ability in WebView2.
4+
5+
# Description
6+
We propose adding NavigateWithWebResourceRequest to CoreWebView2 as the API that allows a WebView2 to navigate with a specified [CoreWebView2WebResourceRequest](https://docs.microsoft.com/en-us/microsoft-edge/webview2/reference/dotnet/0-9-628/microsoft-web-webview2-core-corewebview2). This allows the developer to specify extra headers and POST data as part of their request for navigation.
7+
We also propose adding a CreateWebResourceRequest API to [CoreWebView2Environment](https://docs.microsoft.com/en-us/microsoft-edge/webview2/reference/dotnet/0-9-515/microsoft-web-webview2-core-corewebview2environment) so that developers can create the WebResourceRequest object they'd like to use with NavigateWithWebResourceRequest.
8+
9+
# Examples
10+
11+
```cpp
12+
// Need to convert post data to UTF-8 as required by the application/x-www-form-urlencoded Content-Type
13+
std::wstring postData = std::wstring(L"input=Hello");
14+
int sizeNeededForMultiByte = WideCharToMultiByte(
15+
CP_UTF8, 0, postData.c_str(), postData.size(), nullptr,
16+
0, nullptr, nullptr);
17+
18+
std::unique_ptr<char[]> postDataBytes = std::make_unique<char[]>(sizeNeededForMultiByte);
19+
WideCharToMultiByte(
20+
CP_UTF8, 0, postData.c_str(), postData.size(), postDataBytes.get(),
21+
sizeNeededForMultiByte, nullptr, nullptr);
22+
23+
wil::com_ptr<ICoreWebView2WebResourceRequest> webResourceRequest;
24+
wil::com_ptr<IStream> postDataStream = SHCreateMemStream(
25+
reinterpret_cast<const BYTE*>(postDataBytes.get()), sizeNeededForMultiByte);
26+
27+
// This acts as a HTML form submit to https://www.w3schools.com/action_page.php
28+
CHECK_FAILURE(webviewEnvironment->CreateWebResourceRequest(
29+
L"https://www.w3schools.com/action_page.php", L"POST", postDataStream.get(),
30+
L"Content-Type: application/x-www-form-urlencoded", &webResourceRequest));
31+
CHECK_FAILURE(webview->NavigateWithWebResourceRequest(webResourceRequest.get()));
32+
```
33+
34+
```csharp
35+
UTF8Encoding utfEncoding = new UTF8Encoding();
36+
byte[] postData = utfEncoding.GetBytes("input=Hello");
37+
38+
MemoryStream postDataStream = new MemoryStream(postData.Length);
39+
postDataStream.Write(postData, 0, postData.Length);
40+
postDataStream.Seek(0, SeekOrigin.Begin);
41+
CoreWebView2WebResourceRequest webResourceRequest =
42+
environment.CreateWebResourceRequest(
43+
"https://www.w3schools.com/action_page.php",
44+
"POST",
45+
postDataStream,
46+
"Content-Type: application/x-www-form-urlencoded");
47+
webView.CoreWebView2.NavigateWithWebResourceRequest(webResourceRequest);
48+
49+
```
50+
51+
# Remarks
52+
<!-- Explanation and guidance that doesn't fit into the Examples section. -->
53+
54+
<!-- APIs should only throw exceptions in exceptional conditions; basically,
55+
only when there's a bug in the caller, such as argument exception. But if for some
56+
reason it's necessary for a caller to catch an exception from an API, call that
57+
out with an explanation either here or in the Examples -->
58+
59+
# API Notes
60+
<!-- Option 1: Give a one or two line description of each API (type
61+
and member), or at least the ones that aren't obvious
62+
from their name. These descriptions are what show up
63+
in IntelliSense. For properties, specify the default value of the property if it
64+
isn't the type's default (for example an int-typed property that doesn't default to zero.) -->
65+
66+
<!-- Option 2: Put these descriptions in the below API Details section,
67+
with a "///" comment above the member or type. -->
68+
69+
# API Details
70+
<!-- The exact API, in MIDL3 format (https://docs.microsoft.com/en-us/uwp/midl-3/) -->
71+
```idl
72+
[uuid(7fbad153-fb94-452e-acab-3cbb9ab341ec), object, pointer_default(unique)]
73+
interface ICoreWebView2_2 : ICoreWebView2 {
74+
....
75+
/// Navigate using a constructed WebResourceRequest object. This lets you
76+
/// provide post data or additional request headers during navigation.
77+
/// The headers in the WebResourceRequest override headers
78+
/// added by WebView2 runtime except for Cookie headers.
79+
/// Method can only be either "GET" or "POST". Provided post data will only
80+
/// be sent only if the method is "POST" and the uri scheme is HTTP(S).
81+
/// \snippet ScenarioNavigateWithWebResourceRequest.cpp NavigateWithWebResourceRequest
82+
HRESULT NavigateWithWebResourceRequest([in] ICoreWebView2WebResourceRequest* request);
83+
}
84+
85+
[uuid(1c11735a-d57d-4614-a9e1-8b48d81da38c), object, pointer_default(unique)]
86+
interface ICoreWebView2Environment_2 : ICoreWebView2Environment {
87+
/// Create a new web resource request object.
88+
/// URI parameter must be absolute URI.
89+
/// The headers string is the raw request header string delimited by CRLF
90+
/// (optional in last header).
91+
/// It's also possible to create this object with null headers string
92+
/// and then use the ICoreWebView2HttpRequestHeaders to construct the headers
93+
/// line by line.
94+
/// For information on other parameters see ICoreWebView2WebResourceRequest.
95+
///
96+
/// \snippet ScenarioNavigateWithWebResourceRequest.cpp NavigateWithWebResourceRequest
97+
HRESULT CreateWebResourceRequest([in] LPCWSTR uri,
98+
[in] LPCWSTR method,
99+
[in] IStream* postData,
100+
[in] LPCWSTR headers,
101+
[out, retval] ICoreWebView2WebResourceRequest** request);
102+
}
103+
```
104+
105+
```c#
106+
namespace Microsoft.Web.WebView2.Core
107+
{
108+
runtimeclass CoreWebView2Environment
109+
{
110+
...
111+
/// Create a new web resource request object.
112+
/// URI parameter must be absolute URI.
113+
/// The headers string is the raw request header string delimited by CRLF
114+
/// (optional in last header).
115+
/// It's also possible to create this object with null headers string
116+
/// and then use the CoreWebView2HttpRequestHeaders to construct the headers
117+
/// line by line.
118+
/// For information on other parameters see ICoreWebView2WebResourceRequest.
119+
///
120+
public CoreWebView2WebResourceRequest CreateWebResourceRequest(String uri,
121+
String method,
122+
Stream postData,
123+
String headers);
124+
}
125+
runtimeclass CoreWebView2
126+
{
127+
...
128+
/// Navigate using a constructed WebResourceRequest object. This let's you
129+
/// provide post data or additional request headers during navigation.
130+
/// The headers in the WebResourceRequest override headers
131+
/// added by WebView2 runtime except for Cookie headers.
132+
/// Method can only be either "GET" or "POST". Provided post data will only
133+
/// be sent only if the method is "POST" and the uri scheme is HTTP(S).
134+
public void NavigateWithWebResourceRequest(CoreWebView2WebResourceRequest request);
135+
}
136+
}
137+
```
138+
139+
# Appendix
140+
<!-- Anything else that you want to write down for posterity, but
141+
that isn't necessary to understand the purpose and usage of the API.
142+
For example, implementation details. -->

0 commit comments

Comments
 (0)