diff --git a/specs/WebRtcPortConfiguration.md b/specs/WebRtcPortConfiguration.md index fc7f025a..d13879bb 100644 --- a/specs/WebRtcPortConfiguration.md +++ b/specs/WebRtcPortConfiguration.md @@ -23,9 +23,8 @@ 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 @@ -33,15 +32,17 @@ Usage steps: Microsoft::WRL::ComPtr 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)); } @@ -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); } @@ -77,9 +80,50 @@ 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 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. +- 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 { @@ -88,45 +132,75 @@ 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(2c0f597d-2958-5a94-82f9-c750cf86cb88), 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), 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 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. + /// 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 @@ -140,6 +214,12 @@ interface ICoreWebView2StagingEnvironmentOptions10 : IUnknown { ```csharp namespace Microsoft.Web.WebView2.Core { + enum CoreWebview2AllowedPortRangeScope + { + Default = 0, + WebRtc = 1, + }; + enum CoreWebView2TransportProtocolKind { Udp = 0, @@ -150,8 +230,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); } } }