Skip to content

Commit 4de2c28

Browse files
ashuray007ashuray007
authored
Add WebRtcPortConfiguration.md
1 parent 0c2a858 commit 4de2c28

1 file changed

Lines changed: 159 additions & 0 deletions

File tree

‎specs/WebRtcPortConfiguration.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
2+
WebRTC Port Range Configuration
3+
===
4+
5+
# Background
6+
WebRTC by default allocates ports dynamically from the system’s ephemeral range.
7+
In enterprise or testing environments, developers often need deterministic or firewall-friendly port allocation.
8+
9+
This API enables developers to configure the port range WebRTC uses for ICE candidates and media connections.
10+
The initial support is for **UDP**, with room to extend to **TCP** in the future.
11+
12+
By exposing a `WebRtcPortConfiguration` object on `CoreWebView2EnvironmentOptions`, developers can set and retrieve the port range before creating the WebView2 environment.
13+
14+
# Conceptual pages (How To)
15+
16+
Developers can use this API to restrict WebRTC’s UDP ports to a specific range.
17+
18+
Common scenarios:
19+
- Configure ports for **enterprise firewall compliance**.
20+
- Run **deterministic tests** where ICE candidate ports are predictable.
21+
- Avoid conflicts with other applications that may already use ephemeral ranges.
22+
23+
Usage steps:
24+
1. Create `CoreWebView2EnvironmentOptions`.
25+
2. Access the `WebRtcPortConfiguration` object.
26+
3. Call `SetPortRange` for `CoreWebView2WebRtcProtocolKind.Udp`.
27+
4. Pass the options when creating the WebView2 environment.
28+
29+
30+
# Examples
31+
### Configure UDP Port Range
32+
```
33+
wil::com_ptr<ICoreWebView2EnvironmentOptions> options =
34+
Microsoft::WRL::Make<CoreWebView2EnvironmentOptions>();
35+
36+
wil::com_ptr<ICoreWebView2WebRtcPortConfiguration> portConfig;
37+
CHECK_FAILURE(options->get_WebRtcPortConfiguration(&portConfig));
38+
39+
CHECK_FAILURE(portConfig->SetPortRange(
40+
CoreWebView2WebRtcProtocolKind::Udp, 50000, 51000));
41+
```
42+
43+
### C++ Sample
44+
```cpp
45+
using namespace Microsoft::WRL;
46+
47+
ScenarioWebRtcUdpPortConfiguration::ScenarioWebRtcUdpPortConfiguration(AppWindow* appWindow)
48+
: m_appWindow(appWindow), m_webView(appWindow->GetWebView())
49+
{
50+
// Navigate to a demo page that will trigger WebRTC usage.
51+
m_demoUri = L"https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/";
52+
CHECK_FAILURE(m_webView->Navigate(m_demoUri.c_str()));
53+
54+
// If we navigate away from the demo page, turn off this scenario.
55+
CHECK_FAILURE(m_webView->add_ContentLoading(
56+
Callback<ICoreWebView2ContentLoadingEventHandler>(
57+
[this](ICoreWebView2* sender, ICoreWebView2ContentLoadingEventArgs* /*args*/)
58+
-> HRESULT
59+
{
60+
wil::unique_cotaskmem_string uri;
61+
sender->get_Source(&uri);
62+
if (uri.get() != m_demoUri)
63+
{
64+
m_appWindow->DeleteComponent(this);
65+
}
66+
return S_OK;
67+
})
68+
.Get(),
69+
&m_contentLoadingToken));
70+
}
71+
72+
ScenarioWebRtcUdpPortConfiguration::~ScenarioWebRtcUdpPortConfiguration()
73+
{
74+
CHECK_FAILURE(m_webView->remove_ContentLoading(m_contentLoadingToken));
75+
}
76+
77+
```
78+
79+
# API Details
80+
## C++
81+
```
82+
/// Specifies the WebRTC protocol type for port range configuration.
83+
[ms_owner("core", "juhishah@microsoft.com")]
84+
enum CoreWebView2WebRtcProtocolKind
85+
{
86+
/// UDP protocol for WebRTC media and ICE candidates.
87+
Udp = 0,
88+
/// TCP protocol for WebRTC media and ICE candidates (future support).
89+
Tcp = 1,
90+
};
91+
[availability("staging")]
92+
runtimeclass CoreWebView2WebRtcPortConfiguration : [default] ICoreWebView2WebRtcPortConfiguration{}
93+
94+
/// <com>
95+
/// WebRTC port configuration interface for managing WebRTC port range configuration.
96+
/// This interface provides methods to configure and retrieve custom port ranges
97+
/// that WebRTC will use for ICE candidates and media connections across different protocols.
98+
/// </com>
99+
[availability("staging")]
100+
[com_interface("staging=ICoreWebView2StagingWebRtcPortConfiguration")]
101+
[ms_owner("core", "juhishah@microsoft.com")]
102+
interface ICoreWebView2WebRtcPortConfiguration
103+
{
104+
// ICoreWebView2StagingWebRtcPortConfiguration members
105+
/// The `SetPortRange` method allows you to set a custom port range for WebRTC to use
106+
/// for a specific protocol type.
107+
/// This method allows configuring a specific port range that WebRTC will use
108+
/// for ICE candidates and media connections for the specified protocol.
109+
///
110+
/// `protocol` specifies the WebRTC protocol type (UDP, TCP, etc.).
111+
/// `minPort` and `maxPort` must be in the range 1025-65535 (inclusive).
112+
/// `minPort` must be less than or equal to `maxPort`.
113+
/// If `minPort` equals `maxPort`, it represents a single port.
114+
///
115+
/// Calling this method will replace any previously configured port range for the specified protocol.
116+
/// <com>
117+
/// \snippet AppWindow.cpp WebRtcPortConfiguration
118+
/// </com>
119+
void SetPortRange(CoreWebView2WebRtcProtocolKind protocol, UInt32 minPort, UInt32 maxPort);
120+
121+
/// The `GetPortRange` method gets the currently configured port range for a specific protocol.
122+
/// Returns TRUE if a custom port range is configured for the specified protocol,
123+
/// with the range values in out parameters.
124+
/// Returns FALSE if no custom range is set for the protocol (using default dynamic allocation),
125+
/// in which case the out parameter values should be ignored.
126+
/// <com>
127+
/// \snippet AppWindow.cpp WebRtcPortConfiguration
128+
/// </com>
129+
Boolean GetPortRange(CoreWebView2WebRtcProtocolKind protocol, out UInt32 minPort, out UInt32 maxPort);
130+
}
131+
```
132+
133+
```
134+
/// <com>
135+
/// Additional options used to create WebView2 Environment to manage WebRTC UDP port range configuration.
136+
/// </com>
137+
[availability("staging")]
138+
[com_interface("staging=ICoreWebView2StagingEnvironmentOptions10")]
139+
[ms_owner("core", "juhishah@microsoft.com")]
140+
[exclusiveto(CoreWebView2EnvironmentOptions)]
141+
interface ICoreWebView2StagingEnvironmentOptions10
142+
{
143+
// ICoreWebView2StagingEnvironmentOptions10 members
144+
/// Gets the WebRTC UDP port allocator for configuring a custom UDP port range.
145+
/// This allocator can be used to set and retrieve UDP port range configuration
146+
/// that WebRTC will use for ICE candidates and media connections.
147+
/// <com>
148+
/// \snippet AppWindow.cpp WebRtcPortConfiguration
149+
/// </com>
150+
ICoreWebView2WebRtcPortConfiguration WebRtcPortConfiguration { get; };
151+
}
152+
```
153+
154+
155+
# Appendix
156+
Validation rules: Ports must be within 1025–65535. Calls with invalid ranges return E_INVALIDARG.
157+
Default behavior: If no range is configured, WebRTC uses the OS ephemeral port range.
158+
Thread safety: Configuration must be completed before the environment is created.
159+
Extensibility: API is protocol-based to allow future support (e.g., TCP).

0 commit comments

Comments
 (0)