Skip to content

API Review: Adding CoreWebView2NetworkComponentScope to Port Configuration #5397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

API Review: Adding CoreWebView2NetworkComponentScope to Port Configuration #5397

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ead15cb
Adding CoreWebView2NetworkComponentScope
ashuray007 Oct 13, 2025
71cc958
Resolving Comments
ashuray007 Oct 15, 2025
3eb8923
Resolving Comments
ashuray007 Oct 15, 2025
3ebe61d
Resolving Comments
ashuray007 Oct 28, 2025
1f4504a
Renaming to CoreWebview2AllowedPortRangeScope
ashuray007 Oct 28, 2025
1f5e8ee
Minor Fix
ashuray007 Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 104 additions & 26 deletions specs/WebRtcPortConfiguration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,25 +23,26 @@ Common scenarios:

Usage steps:
1. Create `CoreWebView2EnvironmentOptions`.
2. Call `SetAllowedPortRange` for `COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND_UDP`.
3. Pass the options when creating the WebView2 environment.

2. Call `SetAllowedPortRange` for `COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE_DEFAULT` and `COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND_UDP`.
3. Pass the options when creating the WebView2 environment.

# Examples
### C++ Configure UDP Port Range
```cpp
Microsoft::WRL::ComPtr<ICoreWebView2StagingEnvironmentOptions10> optionsStaging10;
if (options.As(&optionsStaging10) == S_OK)
{
// Configure port ranges for WebRTC UDP traffic to work within enterprise firewalls
// Configure port ranges for UDP traffic to work within enterprise firewalls
// Set UDP port range (example: 50000-55000 for enterprise environments)
const INT32 udpMin = 50000, udpMax = 55000;

CHECK_FAILURE(optionsStaging10->SetAllowedPortRange(
COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE_DEFAULT,
COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND_UDP, udpMin, udpMax));

// Get the configured port range
CHECK_FAILURE(optionsStaging10->GetAllowedPortRange(
CHECK_FAILURE(optionsStaging10->GetEffectiveAllowedPortRange(
COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE_DEFAULT,
COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND_UDP, &m_udpPortRange.minPort,
&m_udpPortRange.maxPort));
}
Expand All @@ -59,15 +60,17 @@ var options = CoreWebView2Environment.CreateCoreWebView2EnvironmentOptions();
var optionsStaging10 = options as ICoreWebView2StagingEnvironmentOptions10;
if (optionsStaging10 != null)
{
// Configure port ranges for WebRTC UDP traffic to work within enterprise firewalls
// Configure port ranges for UDP traffic to work within enterprise firewalls
// Set UDP port range (example: 50000-55000 for enterprise environments)
const int udpMin = 50000, udpMax = 55000;

optionsStaging10.SetAllowedPortRange(
COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE_DEFAULT,
COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND_UDP, udpMin, udpMax);

// Get the configured port range
optionsStaging10.GetAllowedPortRange(
optionsStaging10.GetEffectiveAllowedPortRange(
COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE_DEFAULT,
COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND_UDP, out m_udpPortRange.minPort,
out m_udpPortRange.maxPort);
}
Expand All @@ -77,9 +80,49 @@ var environment = await CoreWebView2Environment.CreateAsync(
OnCreateEnvironmentCompleted(environment);
```

API Rules and Precedence

1. Port Range Restriction Scope param in SetAllowedPortRange
- A component specific scope (e.g. _WEB_RTC) always takes precedence over _DEFAULT for that component in `SetAllowedPortRange`.
- `_DEFAULT` defines the base port range restrictions for all components without specific overrides.
- Passing `(0, 0)` for a component scope unset its specific range restriction and inherit range restriction from `_DEFAULT`
- If `_DEFAULT` is set and a specific scope is unset, that component inherits `_DEFAULT`.
- Passing `(1025,65535)` for a component scope make port range unrestricted for that component.

| Scope State | Behaviour |
| ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| Only `_DEFAULT` is set | `_DEFAULT` applies port range restrictions to all components |
| `_DEFAULT` and `_WEB_RTC` are both set | `_WEB_RTC` port range restrictions applies to WebRTC; `_DEFAULT` applies to others |
| `_WEB_RTC` only is set | `_WEB_RTC` applies port range restrictions only to WebRTC; others unrestricted |
| `_DEFAULT` set and `_WEB_RTC` reset to `(0,0)` | `_DEFAULT` applies port range restrictions to all and WebRTC inherits `_DEFAULT` |
| `_DEFAULT` set and `_WEB_RTC` set to `(1025,65535)` | `_DEFAULT` applies port range restrictions to all except WebRTC which is unrestricted |

2. Port Range Restriction Scope param in GetEffectiveAllowedPortRange
- `GetEffectiveAllowedPortRange` returns the range explicitly set for the queried scope.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not return the explicitly-set range. It calculates the range to use by reconciling the explicitly-set range and the default range.

GetEffectiveAllowedPortRange returns the port range to use for the specified scope.
If the scope is _DEFAULT or if the specified scope is unset, then the _DEFAULT port range is returned.
A range of (0, 0) means that no port range has been set.

- If a specific scope is unset, it inherits `_DEFAULT`.
- Querying `_DEFAULT` only returns `_DEFAULT`; it does not aggregate component-specific settings.
- If neither `_DEFAULT` nor a component-specific scope is set, the default `(0,0)` (unset) is returned.

| `GetEffectiveAllowedPortRange` Scope query | Returned Range |
| -------------------------------------------------------------------- | ----------------------------- |
| Pass `_WEB_RTC` when only `_DEFAULT` is set | Returns `_DEFAULT` range |
| Pass `_WEB_RTC` when `_WEB_RTC` explicitly set | Returns `_WEB_RTC` range |
| Pass `_WEB_RTC` when `_DEFAULT` unset and `_WEB_RTC` unset | Returns `(0, 0)` |
| Pass `_WEB_RTC` when `_DEFAULT` set and `_WEB_RTC` reset to `(0, 0)` | Returns `_DEFAULT` |
| Pass `_DEFAULT` when only `_WEB_RTC` set | Returns `(0,0)` |

# API Details
### C++
```
/// Specifies the scope for port configuration.
[v1_enum]
typedef enum COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE {
/// Scope applies to all components.
COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE_DEFAULT,
/// Applies only to WebRTC peer-to-peer connection.
COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE_WEB_RTC,
} COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE;

/// Specifies the network protocol for port configuration.
[v1_enum]
typedef enum COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND {
Expand All @@ -88,45 +131,74 @@ typedef enum COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND {
} COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND;

/// Additional options used to create WebView2 Environment to manage port range configuration.
[uuid(eaf22436-27a1-5e3d-a4e3-84d7e7a69a1a), object, pointer_default(unique)]
[uuid(6ce30f6b-5dcc-5dc1-9c09-723cf233dbe5), object, pointer_default(unique)]
interface ICoreWebView2StagingEnvironmentOptions10 : IUnknown {
/// Sets the allowed port range for the specified transport protocol.
/// Sets the allowed port range restriction for the specified
/// scope and transport protocol.
///
/// This API enables WebView2 to operate within enterprise network or firewall
/// restrictions by limiting network communication to a defined port range.
/// It provides fine-grained control by allowing port restrictions to be applied
/// per network component scope, such as WebRTC.
///
/// Currently, only WebRTC UDP Port Range restriction is supported.
///
/// `minPort` and `maxPort` must be within the range 1025–65535 (inclusive),
/// and `minPort` must be less than or equal to `maxPort`.
/// `minPort` and `maxPort` must be within the range 1025-65535 (inclusive).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// `minPort` and `maxPort` must be within the range 1025-65535 (inclusive).
/// `minPort` and `maxPort` must be within the range 1025-65535 (inclusive), or must both be the sentinel value 0.

/// `minPort` must be less than or equal to `maxPort`.
/// If `minPort` equals `maxPort`, the range represents a single port.
///
/// Passing `(0, 0)` resets to the default behavior, meaning no restrictions
/// are applied and the system assigns ports from the full ephemeral range.
///
/// Calls with invalid ranges fail with `E_INVALIDARG`.
///
/// `protocol` The transport protocol (currently only UDP is supported).
///
/// A component specific scope (e.g. _WEB_RTC) always takes precedence over _DEFAULT for that component in `SetAllowedPortRange`.
/// `_DEFAULT` defines the port range restrictions for all components without specific overrides.
/// Passing `(0, 0)` for a component scope unset its specific range restriction and inherit range restriction from `_DEFAULT`
/// If `_DEFAULT` is set and a specific scope is unset, that component inherits `_DEFAULT`.
/// Passing `(1025,65535)` for a component scope make port range unrestricted for that component.

/// | Scope State | Behaviour |
/// | --------------------------------------------------- | ----------------------------------------------------------------------------------------|
/// | Only `_DEFAULT` is set | `_DEFAULT` applies port range restrictions to all components |
/// | `_DEFAULT` and `_WEB_RTC` are both set | `_WEB_RTC` port range restrictions applies to WebRTC; `_DEFAULT` applies to others |
/// | `_WEB_RTC` only is set | `_WEB_RTC` applies port range restrictions only to WebRTC; others unrestricted |
/// | `_DEFAULT` set and `_WEB_RTC` reset to `(0,0)` | `_DEFAULT` applies port range restrictions to all and WebRTC inherits `_DEFAULT` |
/// | `_DEFAULT` set and `_WEB_RTC` set to `(1025,65535)` | `_DEFAULT` applies port range restrictions to all except WebRTC which is unrestricted |

/// `scope` scope on which restrictions will apply.
/// `protocol` Transport protocol on which restrictions will apply.
/// `minPort` The minimum allowed port number (inclusive).
/// `maxPort` The maximum allowed port number (inclusive).
///
HRESULT SetAllowedPortRange(
[in] COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE scope,
[in] COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND protocol,
[in] INT32 minPort,
[in] INT32 maxPort
);

/// Retrieves the allowed port range for the specified transport protocol.
/// Returns the currently configured port range previously set via
/// Retrieves the effective allowed port range for the specified transport protocol.
/// Returns the effective port range previously set via
/// `SetAllowedPortRange`.
///
/// By default, `(0, 0)` is returned, which indicates no restrictions are applied
/// and ports are allocated from the system’s ephemeral range (1025–65535 inclusive).
///
/// `protocol` The transport protocol (currently only UDP is supported).
///
/// `GetEffectiveAllowedPortRange` returns the range explicitly set for the queried scope.
/// If a specific scope is unset, it inherits `_DEFAULT`.
/// Querying `_DEFAULT` only returns `_DEFAULT`; it does not aggregate component-specific settings.
/// If neither `_DEFAULT` nor a component-specific scope is set, the default `(0,0)` (unset) is returned.

/// | `GetEffectiveAllowedPortRange` Scope query | Returned Range |
/// | -------------------------------------------------------------------- | ----------------------------- |
/// | Pass `_WEB_RTC` when only `_DEFAULT` is set | Returns `_DEFAULT` range |
/// | Pass `_WEB_RTC` when `_WEB_RTC` explicitly set | Returns `_WEB_RTC` range |
/// | Pass `_WEB_RTC` when `_DEFAULT` unset and `_WEB_RTC` unset | Returns `(0, 0)` |
/// | Pass `_WEB_RTC` when `_DEFAULT` set and `_WEB_RTC` reset to `(0, 0)` | Returns `_DEFAULT` |
/// | Pass `_DEFAULT` when only `_WEB_RTC` set | Returns `(0,0)` |

/// `scope` scope on which restrictions is applied.
/// `protocol` Transport protocol on which restrictions is applied.
/// `minPort` Receives the minimum allowed port number (inclusive).
/// `maxPort` Receives the maximum allowed port number (inclusive).
///
HRESULT GetAllowedPortRange(
HRESULT GetEffectiveAllowedPortRange (
[in] COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE scope,
[in] COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND protocol,
[out] INT32* minPort,
[out] INT32* maxPort
Expand All @@ -140,6 +212,12 @@ interface ICoreWebView2StagingEnvironmentOptions10 : IUnknown {
```csharp
namespace Microsoft.Web.WebView2.Core
{
enum CoreWebview2AllowedPortRangeScope
{
Default = 0,
WebRtc = 1,
};

enum CoreWebView2TransportProtocolKind
{
Udp = 0,
Expand All @@ -150,8 +228,8 @@ namespace Microsoft.Web.WebView2.Core
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2StagingEnvironmentOptions10")]
{
// ICoreWebView2StagingEnvironmentOptions10 members
void SetAllowedPortRange(CoreWebView2TransportProtocolKind protocol, Int32 minPort, Int32 maxPort);
void GetAllowedPortRange(CoreWebView2TransportProtocolKind protocol, out Int32 minPort, out Int32 maxPort);
void SetAllowedPortRange(CoreWebview2AllowedPortRangeScope scope, CoreWebView2TransportProtocolKind protocol, Int32 minPort, Int32 maxPort);
void GetEffectiveAllowedPortRange(CoreWebview2AllowedPortRangeScope scope, CoreWebView2TransportProtocolKind protocol, out Int32 minPort, out Int32 maxPort);
}
}
}
Expand Down