Skip to content

Commit 861ae27

Browse files
ashuray007ashuray007
authored
Resolving Comments
1 parent d2e8eef commit 861ae27

File tree

1 file changed

+103
-117
lines changed

1 file changed

+103
-117
lines changed

‎specs/WebRtcPortConfiguration.md‎

Lines changed: 103 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,13 @@ WebRTC Port Range Configuration
33
===
44

55
# Background
6-
WebRTC by default allocates ports dynamically from the system’s ephemeral range.
6+
In webview2 components like WebRTC by default allocates ports dynamically from the system’s ephemeral range.
77
In enterprise or testing environments, developers often need deterministic or firewall-friendly port allocation.
88

99
This API enables developers to configure the port range WebRTC uses for [ICE](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Protocols#ice) candidates and media connections.
1010

1111
The initial support is for **UDP**, with room to extend to **TCP** in the future.
1212

13-
By exposing a `WebRtcPortConfiguration` object on `CoreWebView2EnvironmentOptions`, developers can set and retrieve the port range before creating the WebView2 environment.
14-
1513
# Conceptual pages (How To)
1614

1715
Developers can use this API to restrict WebRTC’s UDP ports to a specific range which WebRTC uses for ICE candidate and media connections.
@@ -24,23 +22,29 @@ Common scenarios:
2422
- Avoid conflicts with other applications that may already use ephemeral ranges.
2523

2624
Usage steps:
27-
1. Create `CoreWebView2EnvironmentOptions`.
28-
2. Access the `WebRtcPortConfiguration` object.
29-
3. Call `SetPortRange` for `CoreWebView2WebRtcProtocolKind.Udp`.
30-
4. Pass the options when creating the WebView2 environment.
25+
1. Create `CoreWebView2EnvironmentOptions`.
26+
2. Call `SetAllowedPortRange` for `COREWEBVIEW2_NETWORK_PROTOCOL_UDP`.
27+
3. Pass the options when creating the WebView2 environment.
3128

3229

3330
# Examples
3431
### C++ Configure UDP Port Range
3532
```cpp
36-
wil::com_ptr<ICoreWebView2EnvironmentOptions> options =
37-
Microsoft::WRL::Make<CoreWebView2EnvironmentOptions>();
33+
Microsoft::WRL::ComPtr<ICoreWebView2StagingEnvironmentOptions10> optionsStaging10;
34+
if (options.As(&optionsStaging10) == S_OK)
35+
{
36+
// Configure port ranges for WebRTC UDP traffic to work within enterprise firewalls
37+
// Set UDP port range (example: 50000-55000 for enterprise environments)
38+
const INT32 udpMin = 50000, udpMax = 55000;
3839

39-
wil::com_ptr<ICoreWebView2WebRtcPortConfiguration> portConfig;
40-
CHECK_FAILURE(options->get_WebRtcPortConfiguration(&portConfig));
40+
CHECK_FAILURE(optionsStaging10->SetAllowedPortRange(
41+
COREWEBVIEW2_NETWORK_PROTOCOL_UDP, udpMin, udpMax));
4142

42-
CHECK_FAILURE(portConfig->SetPortRange(
43-
CoreWebView2WebRtcProtocolKind::Udp, 50000, 51000));
43+
// Get the configured port range
44+
CHECK_FAILURE(optionsStaging10->GetAllowedPortRange(
45+
COREWEBVIEW2_NETWORK_PROTOCOL_UDP, &m_udpPortRange.minPort,
46+
&m_udpPortRange.maxPort));
47+
}
4448

4549
HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
4650
subFolder, m_userDataFolder.c_str(), options.Get(),
@@ -51,145 +55,127 @@ HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
5155

5256
### C# Configure UDP Port Range
5357
```csharp
54-
var options = new CoreWebView2EnvironmentOptions();
58+
var options = CoreWebView2Environment.CreateCoreWebView2EnvironmentOptions();
59+
var optionsStaging10 = options as ICoreWebView2StagingEnvironmentOptions10;
60+
if (optionsStaging10 != null)
61+
{
62+
// Configure port ranges for WebRTC UDP traffic to work within enterprise firewalls
63+
// Set UDP port range (example: 50000-55000 for enterprise environments)
64+
const int udpMin = 50000, udpMax = 55000;
5565

56-
var portConfig = options.WebRtcPortConfiguration;
57-
portConfig.SetPortRange(CoreWebView2WebRtcProtocolKind.Udp, 50000, 51000);
66+
optionsStaging10.SetAllowedPortRange(
67+
COREWEBVIEW2_NETWORK_PROTOCOL_UDP, udpMin, udpMax);
5868

59-
var environment = await CoreWebView2Environment.CreateAsync(
60-
browserExecutableFolder: subFolder,
61-
userDataFolder: m_userDataFolder,
62-
options: options);
69+
// Get the configured port range
70+
optionsStaging10.GetAllowedPortRange(
71+
COREWEBVIEW2_NETWORK_PROTOCOL_UDP, out m_udpPortRange.minPort,
72+
out m_udpPortRange.maxPort);
73+
}
6374

75+
var environment = await CoreWebView2Environment.CreateAsync(
76+
subFolder, m_userDataFolder, options);
6477
OnCreateEnvironmentCompleted(environment);
6578
```
6679

6780
# API Details
6881
### C++
6982
```
70-
/// Additional options used to create WebView2 Environment to manage WebRTC UDP port range configuration.
71-
[uuid(0eebe393-8dcf-5bc5-a15d-d862088242e9), object, pointer_default(unique)]
72-
interface ICoreWebView2EnvironmentOptions10 : IUnknown {
73-
/// Get the WebRTC port range configuration object for configuring a custom port range.
74-
/// This configuration object can be used to set and retrieve port range configuration
75-
/// that WebRTC will use for ICE candidates and media connections.
76-
/// If no custom range is configured, WebRTC will use the operating system's default dynamic port range.
77-
/// Configuration must be completed before the environment is created. Once the environment is
78-
/// created, the port range cannot be customized.
83+
/// Specifies the network protocol type for port configuration.
84+
[v1_enum]
85+
typedef enum COREWEBVIEW2_NETWORK_PROTOCOL {
86+
/// Transmission Control Protocol - reliable, connection-oriented protocol.
87+
COREWEBVIEW2_NETWORK_PROTOCOL_TCP,
88+
/// User Datagram Protocol - fast, connectionless protocol.
89+
COREWEBVIEW2_NETWORK_PROTOCOL_UDP,
90+
} COREWEBVIEW2_NETWORK_PROTOCOL;
91+
92+
/// Additional options used to create WebView2 Environment to manage port range configuration.
93+
[uuid(eaf22436-27a1-5e3d-a4e3-84d7e7a69a1a), object, pointer_default(unique)]
94+
interface ICoreWebView2StagingEnvironmentOptions10 : IUnknown {
95+
/// Sets the allowed port range for the specified network protocol.
96+
/// This allows WebView2 to work within enterprise firewall constraints
97+
/// by restricting network communication to the specified port range.
98+
/// Currently WebRTC UDP port restriction is supported.
7999
///
100+
/// `protocol` The network protocol (TCP or UDP) for which to set the port range.
101+
/// `minPort` The minimum port number in the allowed range (inclusive).
102+
/// `maxPort` The maximum port number in the allowed range (inclusive).
80103
///
81-
/// \snippet AppWindow.cpp WebRtcPortConfiguration
82-
[propget] HRESULT WebRtcPortConfiguration([out, retval] ICoreWebView2WebRtcPortConfiguration** value);
83-
}
104+
HRESULT SetAllowedPortRange(
105+
[in] COREWEBVIEW2_NETWORK_PROTOCOL protocol,
106+
[in] INT32 minPort,
107+
[in] INT32 maxPort
108+
);
84109
85-
/// WebRTC port configuration interface for managing WebRTC port range configuration.
86-
/// This interface provides methods to configure and retrieve custom port ranges
87-
/// that WebRTC will use for ICE candidates and media connections across different protocols.
88-
[uuid(b1ac2eb4-15b5-574f-aeb7-c51b9f1520fa), object, pointer_default(unique)]
89-
interface ICoreWebView2WebRtcPortConfiguration : IUnknown {
90-
/// The `SetPortRange` method allows you to set a custom port range for WebRTC to use
91-
/// for a specific protocol type.
92-
/// This method allows configuring a specific port range that WebRTC will use
93-
/// for ICE candidates and media connections for the specified protocol.
110+
/// Gets the allowed port range for the specified network protocol.
111+
/// Returns the current port range configuration that was set via
112+
/// SetAllowedPortRange. Default value is 0,0, which means no restrictions applied
113+
/// and ports are allocated randomly between system's ephemeral range.
94114
///
95-
/// `protocol` specifies the WebRTC protocol type (UDP, TCP, etc.).
96-
/// `minPort` and `maxPort` must be in the range 1025-65535 (inclusive).
97-
/// Calls with invalid ranges return E_INVALIDARG.
98-
/// `minPort` must be less than or equal to `maxPort`.
99-
/// If `minPort` equals `maxPort`, it represents a single port.
115+
/// `protocol` The network protocol (TCP or UDP) for which to get the port range.
116+
/// `minPort` Receives the minimum port number in the allowed range.
117+
/// `maxPort` Receives the maximum port number in the allowed range.
100118
///
101-
/// Calling this method will replace any previously configured port range for the specified protocol.
102-
///
103-
///
104-
/// \snippet AppWindow.cpp WebRtcPortConfiguration
105-
HRESULT SetPortRange(
106-
[in] COREWEBVIEW2_WEB_RTC_PROTOCOL_KIND protocol,
107-
[in] UINT32 minPort,
108-
[in] UINT32 maxPort
119+
HRESULT GetAllowedPortRange(
120+
[in] COREWEBVIEW2_NETWORK_PROTOCOL protocol,
121+
[out] INT32* minPort,
122+
[out] INT32* maxPort
109123
);
110124
111-
/// The `GetPortRange` method gets the currently configured port range for a specific protocol.
112-
/// Returns TRUE if a custom port range is configured for the specified protocol,
113-
/// with the range values in out parameters.
114-
/// Returns FALSE if no custom range is set for the protocol (using default dynamic allocation),
115-
/// in which case the out parameter values should be ignored.
116-
///
117-
///
118-
/// \snippet AppWindow.cpp WebRtcPortConfiguration
119-
HRESULT GetPortRange(
120-
[in] COREWEBVIEW2_WEB_RTC_PROTOCOL_KIND protocol,
121-
[out] UINT32* minPort,
122-
[out] UINT32* maxPort
123-
, [out, retval] BOOL* value);
125+
124126
}
125127
```
126128

127129
### C#
128130
```csharp
129131
/// <summary>
130-
/// Specifies the WebRTC protocol type for port range configuration.
132+
/// Specifies the network protocol type for port configuration.
131133
/// </summary>
132-
public enum CoreWebView2WebRtcProtocolKind
134+
public enum COREWEBVIEW2_NETWORK_PROTOCOL
133135
{
134136
/// <summary>
135-
/// UDP protocol for WebRTC media and ICE candidates.
137+
/// Transmission Control Protocol - reliable, connection-oriented protocol.
138+
/// </summary>
139+
COREWEBVIEW2_NETWORK_PROTOCOL_TCP,
140+
/// <summary>
141+
/// User Datagram Protocol - fast, connectionless protocol.
136142
/// </summary>
137-
Udp = 0,
143+
COREWEBVIEW2_NETWORK_PROTOCOL_UDP,
138144
}
139145

140146
/// <summary>
141-
/// WebRTC port configuration interface for managing WebRTC port range configuration.
142-
/// This interface provides methods to configure and retrieve custom port ranges
143-
/// that WebRTC will use for ICE candidates and media connections across different protocols.
147+
/// Additional options used to create WebView2 Environment to manage port range configuration.
144148
/// </summary>
145-
public interface ICoreWebView2WebRtcPortConfiguration
149+
public interface ICoreWebView2StagingEnvironmentOptions10
146150
{
147151
/// <summary>
148-
/// The SetPortRange method allows you to set a custom port range for WebRTC to use
149-
/// for a specific protocol type.
150-
/// This method allows configuring a specific port range that WebRTC will use
151-
/// for ICE candidates and media connections for the specified protocol.
152-
///
153-
/// protocol specifies the WebRTC protocol type.
154-
/// minPort and maxPort must be in the range 1025-65535 (inclusive).
155-
/// Calls with invalid ranges return E_INVALIDARG.
156-
/// minPort must be less than or equal to maxPort.
157-
/// If minPort equals maxPort, it represents a single port.
158-
///
159-
/// Calling this method will replace any previously configured port range for the specified protocol.
152+
/// Sets the allowed port range for the specified network protocol.
153+
/// This allows WebView2 to work within enterprise firewall constraints
154+
/// by restricting network communication to the specified port range.
155+
/// Currently WebRTC UDP port restriction is supported.
160156
/// </summary>
161-
/// <param name="protocol">The WebRTC protocol type</param>
162-
/// <param name="minPort">Minimum port in the range (1025-65535)</param>
163-
/// <param name="maxPort">Maximum port in the range (1025-65535)</param>
164-
void SetPortRange(CoreWebView2WebRtcProtocolKind protocol, uint minPort, uint maxPort);
157+
/// <param name="protocol">The network protocol (TCP or UDP) for which to set the port range.</param>
158+
/// <param name="minPort">The minimum port number in the allowed range (inclusive).</param>
159+
/// <param name="maxPort">The maximum port number in the allowed range (inclusive).</param>
160+
void SetAllowedPortRange(
161+
COREWEBVIEW2_NETWORK_PROTOCOL protocol,
162+
int minPort,
163+
int maxPort
164+
);
165165

166166
/// <summary>
167-
/// The GetPortRange method gets the currently configured port range for a specific protocol.
168-
/// Returns true if a custom port range is configured for the specified protocol,
169-
/// with the range values in out parameters.
170-
/// Returns false if no custom range is set for the protocol (using default dynamic allocation),
171-
/// in which case the out parameter values should be ignored.
172-
/// </summary>
173-
/// <param name="protocol">The WebRTC protocol type</param>
174-
/// <param name="minPort">Output parameter for minimum port in the range</param>
175-
/// <param name="maxPort">Output parameter for maximum port in the range</param>
176-
/// <returns>True if custom range is configured, false if using default allocation</returns>
177-
bool GetPortRange(CoreWebView2WebRtcProtocolKind protocol, out uint minPort, out uint maxPort);
178-
}
179-
180-
/// <summary>
181-
/// Additional options used to create WebView2 Environment to manage WebRTC port range configuration.
182-
/// </summary>
183-
public interface ICoreWebView2EnvironmentOptions
184-
{
185-
/// <summary>
186-
/// Gets the WebRTC port configuration object for configuring custom port ranges.
187-
/// This configuration can be used to set and retrieve port range configuration
188-
/// that WebRTC will use for ICE candidates and media connections.
189-
/// If no range is configured, WebRTC uses the OS ephemeral port range.
190-
/// Configuration must be completed before the environment is created. Once the environment is
191-
/// setup, the port range can not be customized.
167+
/// Gets the allowed port range for the specified network protocol.
168+
/// Returns the current port range configuration that was set via
169+
/// SetAllowedPortRange. Default value is 0,0, which means no restrictions applied
170+
/// and ports are allocated randomly between system's ephemeral range.
192171
/// </summary>
193-
ICoreWebView2WebRtcPortConfiguration WebRtcPortConfiguration { get; }
172+
/// <param name="protocol">The network protocol (TCP or UDP) for which to get the port range.</param>
173+
/// <param name="minPort">Receives the minimum port number in the allowed range.</param>
174+
/// <param name="maxPort">Receives the maximum port number in the allowed range.</param>
175+
void GetAllowedPortRange(
176+
COREWEBVIEW2_NETWORK_PROTOCOL protocol,
177+
out int minPort,
178+
out int maxPort
179+
);
194180
}
195181
```

0 commit comments

Comments
 (0)