Skip to content

Commit 3da9a73

Browse files
author
Çağrı Kaan Yıldırım
authored
API Spec for NavigateWithWebResourceRequest
Add API Spec for WebView2 NavigateWithWebResourceRequest API
1 parent 2f7820e commit 3da9a73

1 file changed

Lines changed: 143 additions & 0 deletions

File tree

‎specs/NavigateWithWebResourceRequest.md‎

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

0 commit comments

Comments
 (0)