Skip to content

Commit a3dcb45

Browse files
author
Çağrı Kaan Yıldırım
authored
Create NavigateWithWebResourceRequest.md
1 parent 6d95286 commit a3dcb45

1 file changed

Lines changed: 140 additions & 0 deletions

File tree

‎specs/NavigateWithWebResourceRequest.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
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+
char* postDataString = new char[postData.length()];
15+
WideCharToMultiByte(
16+
CP_UTF8, 0, postData.c_str(), postData.length(), postDataString, postData.length(),
17+
nullptr, nullptr);
18+
19+
wil::com_ptr<ICoreWebView2WebResourceRequest> webResourceRequest;
20+
wil::com_ptr<IStream> postDataStream = SHCreateMemStream(
21+
reinterpret_cast<const BYTE*>(postDataString), postData.length());
22+
23+
// This acts as a HTML form submit to https://www.w3schools.com/action_page.php
24+
CHECK_FAILURE(webviewEnvironment->CreateWebResourceRequest(
25+
L"https://www.w3schools.com/action_page.php", L"POST", postDataStream.get(),
26+
L"Content-Type: application/x-www-form-urlencoded", &webResourceRequest));
27+
CHECK_FAILURE(webview->NavigateWithWebResourceRequest(webResourceRequest.get()));
28+
```
29+
30+
```csharp
31+
UTF8Encoding utfEncoding = new UTF8Encoding();
32+
byte[] postData = utfEncoding.GetBytes("input=Hello");
33+
34+
using (MemoryStream postDataStream = new MemoryStream(postData.Length))
35+
{
36+
postDataStream.Write(postData, 0, postData.Length);
37+
CoreWebView2WebResourceRequest webResourceRequest =
38+
environment.CreateWebResourceRequest(
39+
"https://www.w3schools.com/action_page.php",
40+
"POST",
41+
postDataStream,
42+
"Content-Type: application/x-www-form-urlencoded");
43+
webView.CoreWebView2.NavigateWithWebResourceRequest(webResourceRequest);
44+
}
45+
```
46+
47+
# Remarks
48+
<!-- Explanation and guidance that doesn't fit into the Examples section. -->
49+
50+
<!-- APIs should only throw exceptions in exceptional conditions; basically,
51+
only when there's a bug in the caller, such as argument exception. But if for some
52+
reason it's necessary for a caller to catch an exception from an API, call that
53+
out with an explanation either here or in the Examples -->
54+
55+
# API Notes
56+
<!-- Option 1: Give a one or two line description of each API (type
57+
and member), or at least the ones that aren't obvious
58+
from their name. These descriptions are what show up
59+
in IntelliSense. For properties, specify the default value of the property if it
60+
isn't the type's default (for example an int-typed property that doesn't default to zero.) -->
61+
62+
<!-- Option 2: Put these descriptions in the below API Details section,
63+
with a "///" comment above the member or type. -->
64+
65+
# API Details
66+
<!-- The exact API, in MIDL3 format (https://docs.microsoft.com/en-us/uwp/midl-3/) -->
67+
```idl
68+
// This is the ICoreWebView2 Staging interface.
69+
[uuid(9810c82b-8483-4f1c-b2f4-6244f1010c05), object, pointer_default(unique)]
70+
interface ICoreWebView2Staging : IUnknown {
71+
....
72+
/// Navigate using a constructed WebResourceRequest object. This let's you
73+
/// provide post data or additional request headers during navigation.
74+
/// The headers in the WebResourceRequest override headers
75+
/// added by WebView2 runtime except for Cookie headers. To override cookies
76+
/// please use the Cookie API.
77+
/// Method can only be either "GET" or "POST". Provided post data will only
78+
/// be sent only if the method is "POST" and the uri scheme is HTTP(S).
79+
/// \snippet ScenarioNavigateWithWebResourceRequest.cpp NavigateWithWebResourceRequest
80+
HRESULT NavigateWithWebResourceRequest([in] ICoreWebView2WebResourceRequest* request);
81+
}
82+
83+
// This is the ICoreWebView2Environment Staging interface.
84+
[uuid(512e6181-6e99-4744-9b75-183fbefb090b), object, pointer_default(unique)]
85+
interface ICoreWebView2StagingEnvironment : IUnknown {
86+
/// Create a new web resource request object.
87+
/// URI parameter must be absolute URI.
88+
/// The headers string is the raw request header string delimited by newline
89+
/// (\r\n). It's also possible to create this object with null headers string
90+
/// and then use the ICoreWebView2HttpRequestHeaders to construct the headers
91+
/// line by line.
92+
/// For information on other parameters see ICoreWebView2WebResourceRequest.
93+
///
94+
/// \snippet ScenarioNavigateWithWebResourceRequest.cpp NavigateWithWebResourceRequest
95+
HRESULT CreateWebResourceRequest([in] LPCWSTR uri,
96+
[in] LPCWSTR method,
97+
[in] IStream* postData,
98+
[in] LPCWSTR headers,
99+
[out, retval] ICoreWebView2WebResourceRequest** request);
100+
}
101+
```
102+
103+
```c#
104+
namespace Microsoft.Web.WebView2.Core
105+
{
106+
runtimeclass CoreWebView2Environment
107+
{
108+
...
109+
/// Create a new web resource request object.
110+
/// URI parameter must be absolute URI.
111+
/// The headers string is the raw request header string delimited by newline
112+
/// (\r\n). It's also possible to create this object with null headers string
113+
/// and then use the ICoreWebView2HttpRequestHeaders to construct the headers
114+
/// line by line.
115+
/// For information on other parameters see ICoreWebView2WebResourceRequest.
116+
///
117+
public CoreWebView2WebResourceRequest CreateWebResourceRequest(String uri,
118+
String method,
119+
Stream postData,
120+
String headers);
121+
}
122+
runtimeclass CoreWebView2
123+
{
124+
...
125+
/// Navigate using a constructed WebResourceRequest object. This let's you
126+
/// provide post data or additional request headers during navigation.
127+
/// The headers in the WebResourceRequest override headers
128+
/// added by WebView2 runtime except for Cookie headers. To override cookies
129+
/// please use the Cookie API.
130+
/// Method can only be either "GET" or "POST". Provided post data will only
131+
/// be sent only if the method is "POST" and the uri scheme is HTTP(S).
132+
public void NavigateWithWebResourceRequest(CoreWebView2WebResourceRequest request);
133+
}
134+
}
135+
```
136+
137+
# Appendix
138+
<!-- Anything else that you want to write down for posterity, but
139+
that isn't necessary to understand the purpose and usage of the API.
140+
For example, implementation details. -->

0 commit comments

Comments
 (0)