diff --git a/README.md b/README.md index f9c6a16..42b3713 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ WebView4Delphi is an open source project created by Salvador Díaz Fau to embed WebView4Delphi only supports Windows. If you need to embed a web browser in Linux, Windows or MacOS consider using [CEF4Delphi](https://github.com/salvadordf/CEF4Delphi) instead. -WebView4Delphi uses the [Microsoft Edge WebView2 Runtime](https://docs.microsoft.com/en-us/microsoft-edge/webview2/) and [Microsoft.Web.WebView2 NuGet package version 1.0.1901.177](https://www.nuget.org/packages/Microsoft.Web.WebView2) to embed a web browser. +WebView4Delphi uses the [Microsoft Edge WebView2 Runtime](https://docs.microsoft.com/en-us/microsoft-edge/webview2/) and [Microsoft.Web.WebView2 NuGet package version 1.0.1938.49](https://www.nuget.org/packages/Microsoft.Web.WebView2) to embed a web browser. WebView4Delphi was developed and tested on Delphi 11.3, Delphi XE2, Delphi 7 and Lazarus 2.2.6/FPC 3.2.2. diff --git a/bin32/WebView2Loader.dll b/bin32/WebView2Loader.dll index 65674bd..83f73b6 100644 Binary files a/bin32/WebView2Loader.dll and b/bin32/WebView2Loader.dll differ diff --git a/bin64/WebView2Loader.dll b/bin64/WebView2Loader.dll index 361e25d..e9e0ce0 100644 Binary files a/bin64/WebView2Loader.dll and b/bin64/WebView2Loader.dll differ diff --git a/docs/WebView4Delphi.chm b/docs/WebView4Delphi.chm index 6e92690..fd02a0b 100644 Binary files a/docs/WebView4Delphi.chm and b/docs/WebView4Delphi.chm differ diff --git a/packages/webview4delphi.lpk b/packages/webview4delphi.lpk index e4c4298..b961233 100644 --- a/packages/webview4delphi.lpk +++ b/packages/webview4delphi.lpk @@ -16,7 +16,7 @@ - + diff --git a/source/uWVBrowserBase.pas b/source/uWVBrowserBase.pas index ab08126..de2f2ff 100644 --- a/source/uWVBrowserBase.pas +++ b/source/uWVBrowserBase.pas @@ -840,9 +840,25 @@ TWVBrowserBase = class(TComponent, IWVBrowserEvents) /// function OpenTaskManagerWindow : boolean; /// - /// Post the specified webMessage to the top level document in this WebView. + /// Post the specified webMessage to the top level document in this WebView. /// The main page receives the message by subscribing to the `message` event of the - /// `window.chrome.webview` of the page document. + /// `window.chrome.webview` of the page document. + /// + /// ```cpp + /// window.chrome.webview.addEventListener('message', handler) + /// window.chrome.webview.removeEventListener('message', handler) + /// ``` + /// + /// The event args is an instance of `MessageEvent`. The + /// `ICoreWebView2Settings.IsWebMessageEnabled` setting must be `TRUE` or + /// the web message will not be sent. The `data` property of the event + /// arg is the `webMessage` string parameter parsed as a JSON string into a + /// JavaScript object. The `source` property of the event arg is a reference + /// to the `window.chrome.webview` object. For information about sending + /// messages from the HTML document in the WebView to the host, navigate to + /// [add_WebMessageReceived](/microsoft-edge/webview2/reference/win32/icorewebview2#add_webmessagereceived). + /// The message is delivered asynchronously. If a navigation occurs before + /// the message is posted to the page, the message is discarded. /// /// /// See the ICoreWebView2 article. @@ -878,6 +894,23 @@ TWVBrowserBase = class(TComponent, IWVBrowserEvents) /// normalized, any URI fragment has been removed, and non-ASCII hostnames /// have been converted to punycode. /// Specifying an empty string for aURI matches no URIs. + /// For more information about resource context filters, navigate to + /// [COREWEBVIEW2_WEB_RESOURCE_CONTEXT](/microsoft-edge/webview2/reference/win32/webview2-idl#corewebview2_web_resource_context). + /// + /// | URI Filter String | Request URI | Match | Notes | + /// | ---- | ---- | ---- | ---- | + /// | `*` | `https://contoso.com/a/b/c` | Yes | A single * will match all URIs | + /// | `*://contoso.com/*` | `https://contoso.com/a/b/c` | Yes | Matches everything in contoso.com across all schemes | + /// | `*://contoso.com/*` | `https://example.com/?https://contoso.com/` | Yes | But also matches a URI with just the same text anywhere in the URI | + /// | `example` | `https://contoso.com/example` | No | The filter does not perform partial matches | + /// | `*example` | `https://contoso.com/example` | Yes | The filter matches across URI parts | + /// | `*example` | `https://contoso.com/path/?example` | Yes | The filter matches across URI parts | + /// | `*example` | `https://contoso.com/path/?query#example` | No | The filter is matched against the URI with no fragment | + /// | `*example` | `https://example` | No | The URI is normalized before filter matching so the actual URI used for comparison is `https://example/` | + /// | `*example/` | `https://example` | Yes | Just like above, but this time the filter ends with a / just like the normalized URI | + /// | `https://xn--qei.example/` | `https://❤.example/` | Yes | Non-ASCII hostnames are normalized to punycode before wildcard comparison | + /// | `https://❤.example/` | `https://xn--qei.example/` | No | Non-ASCII hostnames are normalized to punycode before wildcard comparison | + /// /// /// /// See the ICoreWebView2 article. @@ -2421,7 +2454,22 @@ TWVBrowserBase = class(TComponent, IWVBrowserEvents) /// property OnPermissionRequested : TOnPermissionRequestedEvent read FOnPermissionRequested write FOnPermissionRequested; /// - /// `OnProcessFailed` runs when a WebView process ends unexpectedly or becomes unresponsive. + /// `OnProcessFailed` runs when any of the processes in the + /// [WebView2 Process Group](https://learn.microsoft.com/microsoft-edge/webview2/concepts/process-model?tabs=csharp#processes-in-the-webview2-runtime) + /// encounters one of the following conditions: + /// + /// Condition | Details + /// ---|--- + /// Unexpected exit | The process indicated by the event args has exited unexpectedly (usually due to a crash). The failure might or might not be recoverable and some failures are auto-recoverable. + /// Unresponsiveness | The process indicated by the event args has become unresponsive to user input. This is only reported for renderer processes, and will run every few seconds until the process becomes responsive again. + /// + /// NOTE: When the failing process is the browser process, a + /// `ICoreWebView2Environment5.BrowserProcessExited` event will run too. + /// Your application can use `ICoreWebView2ProcessFailedEventArgs` and + /// `ICoreWebView2ProcessFailedEventArgs2` to identify which condition and + /// process the event is for, and to collect diagnostics and handle recovery + /// if necessary. For more details about which cases need to be handled by + /// your application, see `COREWEBVIEW2_PROCESS_FAILED_KIND`. /// /// /// See the ICoreWebView2 article. diff --git a/source/uWVCoreWebView2.pas b/source/uWVCoreWebView2.pas index 6e6eae8..df847a1 100644 --- a/source/uWVCoreWebView2.pas +++ b/source/uWVCoreWebView2.pas @@ -288,11 +288,13 @@ TCoreWebView2 = class /// accessKind specifies the level of access to resources under the virtual host from other sites. /// /// For example, after calling + /// /// ```cpp /// SetVirtualHostNameToFolderMapping( /// L"appassets.example", L"assets", /// COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_DENY); /// ``` + /// /// navigating to `https://appassets.example/my-local-file.html` will /// show the content from my-local-file.html in the assets subfolder located on disk under /// the same path as the app's executable file. @@ -300,10 +302,12 @@ TCoreWebView2 = class /// DOM elements that want to reference local files will have their host reference virtual host in the source. /// If there are multiple folders being used, define one unique virtual host per folder. /// For example, you can embed a local image like this + /// /// ```cpp /// WCHAR c_navString[] = L""; /// m_webView->NavigateToString(c_navString); /// ``` + /// /// The example above shows the image wv2.png by resolving the folder mapping above. /// /// You should typically choose virtual host names that are never used by real sites. @@ -379,16 +383,16 @@ TCoreWebView2 = class /// function OpenDevToolsWindow : boolean; /// - /// Post the specified webMessage to the top level document in this WebView. + /// Post the specified webMessage to the top level document in this WebView. /// The main page receives the message by subscribing to the `message` event of the - /// `window.chrome.webview` of the page document. - /// + /// `window.chrome.webview` of the page document. + /// /// ```cpp /// window.chrome.webview.addEventListener('message', handler) /// window.chrome.webview.removeEventListener('message', handler) /// ``` - /// - /// The event args is an instance of `MessageEvent`. The + /// + /// The event args is an instance of `MessageEvent`. The /// `ICoreWebView2Settings::IsWebMessageEnabled` setting must be `TRUE` or /// the web message will not be sent. The `data` property of the event /// arg is the `webMessage` string parameter parsed as a JSON string into a @@ -397,7 +401,7 @@ TCoreWebView2 = class /// messages from the HTML document in the WebView to the host, navigate to /// [add_WebMessageReceived](/microsoft-edge/webview2/reference/win32/icorewebview2#add_webmessagereceived). /// The message is delivered asynchronously. If a navigation occurs before - /// the message is posted to the page, the message is discarded. + /// the message is posted to the page, the message is discarded. /// function PostWebMessageAsJson(const aWebMessageAsJson : wvstring) : boolean; /// @@ -411,23 +415,23 @@ TCoreWebView2 = class /// function PostWebMessageAsString(const aWebMessageAsString : wvstring) : boolean; /// - /// Runs an asynchronous `DevToolsProtocol` method. For more information + /// Runs an asynchronous `DevToolsProtocol` method. For more information /// about available methods, navigate to - /// [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/tot) - /// . The `methodName` parameter is the full name of the method in the + /// [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/tot). + /// The `methodName` parameter is the full name of the method in the /// `{domain}.{method}` format. The `parametersAsJson` parameter is a JSON - /// formatted string containing the parameters for the corresponding method. - /// The `Invoke` method of the `handler` is run when the method + /// formatted string containing the parameters for the corresponding method. + /// The `Invoke` method of the `handler` is run when the method /// asynchronously completes. `Invoke` is run with the return object of the /// method as a JSON string. This function returns E_INVALIDARG if the `methodName` is /// unknown or the `parametersAsJson` has an error. In the case of such an error, the /// `returnObjectAsJson` parameter of the handler will include information - /// about the error. - /// Note even though WebView2 dispatches the CDP messages in the order called, + /// about the error. + /// Note even though WebView2 dispatches the CDP messages in the order called, /// CDP method calls may be processed out of order. /// If you require CDP methods to run in a particular order, you should wait /// for the previous method's completed handler to run before calling the - /// next method. + /// next method. /// function CallDevToolsProtocolMethod(const aMethodName, aParametersAsJson : wvstring; aExecutionID : integer; const aBrowserComponent : TComponent) : boolean; /// @@ -484,7 +488,7 @@ TCoreWebView2 = class /// /// For more information about resource context filters, navigate to /// [COREWEBVIEW2_WEB_RESOURCE_CONTEXT](/microsoft-edge/webview2/reference/win32/webview2-idl#corewebview2_web_resource_context). - /// + /// /// | URI Filter String | Request URI | Match | Notes | /// | ---- | ---- | ---- | ---- | /// | `*` | `https://contoso.com/a/b/c` | Yes | A single * will match all URIs | @@ -498,6 +502,7 @@ TCoreWebView2 = class /// | `*example/` | `https://example` | Yes | Just like above, but this time the filter ends with a / just like the normalized URI | /// | `https://xn--qei.example/` | `https://❤.example/` | Yes | Non-ASCII hostnames are normalized to punycode before wildcard comparison | /// | `https://❤.example/` | `https://xn--qei.example/` | No | Non-ASCII hostnames are normalized to punycode before wildcard comparison | + /// /// function AddWebResourceRequestedFilter(const URI : wvstring; ResourceContext: TWVWebResourceContext) : boolean; /// @@ -519,7 +524,7 @@ TCoreWebView2 = class /// property or method, or rejected in case of error, for example, no /// property or method on the object or parameters are not valid. /// - /// \> [!NOTE]\n\> While simple types, `IDispatch` and array are supported, and + /// NOTE: While simple types, `IDispatch` and array are supported, and /// `IUnknown` objects that also implement `IDispatch` are treated as `IDispatch`, /// generic `IUnknown`, `VT_DECIMAL`, or `VT_RECORD` variant is not supported. /// Remote JavaScript objects like callback functions are represented as an @@ -562,7 +567,7 @@ TCoreWebView2 = class /// /// The `chrome.webview.hostObjects.options` object provides the ability to /// change some functionality of host objects. - /// + /// /// Options property | Details /// ---|--- /// `forceLocalProperties` | This is an array of host object property names that will be run locally, instead of being called on the native host object. This defaults to `then`, `toJSON`, `Symbol.toString`, and `Symbol.toPrimitive`. You can add other properties to specify that they should be run locally on the javascript host object proxy. @@ -571,10 +576,10 @@ TCoreWebView2 = class /// `defaultSyncProxy` | When calling a method on a synchronous proxy, the result should also be a synchronous proxy. But in some cases, the sync/async context is lost (for example, when providing to native code a reference to a function, and then calling that function in native code). In these cases, the proxy will be asynchronous, unless this property is set. /// `forceAsyncMethodMatches ` | This is an array of regular expressions. When calling a method on a synchronous proxy, the method call will be performed asynchronously if the method name matches a string or regular expression in this array. Setting this value to `Async` will make any method that ends with Async be an asynchronous method call. If an async method doesn't match here and isn't forced to be asynchronous, the method will be invoked synchronously, blocking execution of the calling JavaScript and then returning the resolution of the promise, rather than returning a promise. /// `ignoreMemberNotFoundError` | By default, an exception is thrown when attempting to get the value of a proxy property that doesn't exist on the corresponding native class. Setting this property to `true` switches the behavior to match Chakra WinRT projection (and general JavaScript) behavior of returning `undefined` with no error. - /// + /// /// Host object proxies additionally have the following methods which run /// locally. - /// + /// /// Method name | Details /// ---|--- ///`applyHostFunction`, `getHostProperty`, `setHostProperty` | Perform a method invocation, property get, or property set on the host object. Use the methods to explicitly force a method or property to run remotely if a conflicting local method or property exists. For instance, `proxy.toString()` runs the local `toString` method on the proxy object. But proxy.applyHostFunction('toString') runs `toString` on the host proxied object instead. @@ -582,7 +587,7 @@ TCoreWebView2 = class ///`sync` | Asynchronous host object proxies expose a sync method which returns a promise for a synchronous host object proxy for the same host object. For example, `chrome.webview.hostObjects.sample.methodCall()` returns an asynchronous host object proxy. Use the `sync` method to obtain a synchronous host object proxy instead: `const syncProxy = await chrome.webview.hostObjects.sample.methodCall().sync()`. ///`async` | Synchronous host object proxies expose an async method which blocks and returns an asynchronous host object proxy for the same host object. For example, `chrome.webview.hostObjects.sync.sample.methodCall()` returns a synchronous host object proxy. Running the `async` method on this blocks and then returns an asynchronous host object proxy for the same host object: `const asyncProxy = chrome.webview.hostObjects.sync.sample.methodCall().async()`. ///`then` | Asynchronous host object proxies have a `then` method. Allows proxies to be awaitable. `then` returns a promise that resolves with a representation of the host object. If the proxy represents a JavaScript literal, a copy of that is returned locally. If the proxy represents a function, a non-awaitable proxy is returned. If the proxy represents a JavaScript object with a mix of literal properties and function properties, the a copy of the object is returned with some properties as host object proxies. - /// + /// /// All other property and method invocations (other than the above Remote /// object proxy methods, `forceLocalProperties` list, and properties on /// Function and Object prototypes) are run remotely. Asynchronous host @@ -612,7 +617,7 @@ TCoreWebView2 = class /// function RemoveHostObjectFromScript(const aName : wvstring) : boolean; /// - /// Add the provided JavaScript to a list of scripts that should be run after + /// Add the provided JavaScript to a list of scripts that should be run after /// the global object has been created, but before the HTML document has /// been parsed and before any other script included by the HTML document is /// run. This method injects a script that runs on all top-level document @@ -621,20 +626,18 @@ TCoreWebView2 = class /// script is ready to run. When this method completes, the `Invoke` method /// of the handler is run with the `id` of the injected script. `id` is a /// string. To remove the injected script, use - /// `RemoveScriptToExecuteOnDocumentCreated`. - /// - /// If the method is run in add_NewWindowRequested handler it should be called + /// `RemoveScriptToExecuteOnDocumentCreated`. + /// If the method is run in add_NewWindowRequested handler it should be called /// before the new window is set. If called after setting the NewWindow property, the initial script /// may or may not apply to the initial navigation and may only apply to the subsequent navigation. - /// For more details see `ICoreWebView2NewWindowRequestedEventArgs::put_NewWindow`. - /// - /// \> [!NOTE]\n\> If an HTML document is running in a sandbox of some kind using + /// For more details see `ICoreWebView2NewWindowRequestedEventArgs::put_NewWindow`. + /// NOTE: If an HTML document is running in a sandbox of some kind using /// [sandbox](https://developer.mozilla.org/docs/Web/HTML/Element/iframe#attr-sandbox) /// properties or the /// [Content-Security-Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) /// HTTP header affects the script that runs. For example, if the /// `allow-modals` keyword is not set then requests to run the `alert` - /// function are ignored. + /// function are ignored. /// function AddScriptToExecuteOnDocumentCreated(const JavaScript : wvstring; const aBrowserComponent : TComponent) : boolean; /// @@ -675,22 +678,20 @@ TCoreWebView2 = class /// function GetFavicon(aFormat: TWVFaviconImageFormat; const aBrowserComponent : TComponent) : boolean; /// - /// Print the current web page asynchronously to the specified printer with the provided settings. + /// Print the current web page asynchronously to the specified printer with the provided settings. /// See `ICoreWebView2PrintSettings` for description of settings. Passing - /// nullptr for `printSettings` results in default print settings used. - /// - /// The handler will return `errorCode` as `S_OK` and `printStatus` as COREWEBVIEW2_PRINT_STATUS_PRINTER_UNAVAILABLE + /// nullptr for `printSettings` results in default print settings used. + /// The handler will return `errorCode` as `S_OK` and `printStatus` as COREWEBVIEW2_PRINT_STATUS_PRINTER_UNAVAILABLE /// if `printerName` doesn't match with the name of any installed printers on the user OS. The handler /// will return `errorCode` as `E_INVALIDARG` and `printStatus` as COREWEBVIEW2_PRINT_STATUS_OTHER_ERROR - /// if the caller provides invalid settings for a given printer. - /// - /// The async `Print` operation completes when it finishes printing to the printer. + /// if the caller provides invalid settings for a given printer. + /// The async `Print` operation completes when it finishes printing to the printer. /// At this time the `ICoreWebView2PrintCompletedHandler` is invoked. /// Only one `Printing` operation can be in progress at a time. If `Print` is called while a `Print` or `PrintToPdf` /// or `PrintToPdfStream` or `ShowPrintUI` job is in progress, the completed handler is immediately invoked /// with `E_ABORT` and `printStatus` is COREWEBVIEW2_PRINT_STATUS_OTHER_ERROR. - /// This is only for printing operation on one webview. - /// + /// This is only for printing operation on one webview. + /// /// | errorCode | printStatus | Notes | /// | --- | --- | --- | /// | S_OK | COREWEBVIEW2_PRINT_STATUS_SUCCEEDED | Print operation succeeded. | @@ -698,54 +699,50 @@ TCoreWebView2 = class /// | S_OK | COREWEBVIEW2_PRINT_STATUS_OTHER_ERROR | Print operation is failed. | /// | E_INVALIDARG | COREWEBVIEW2_PRINT_STATUS_OTHER_ERROR | If the caller provides invalid settings for the specified printer. | /// | E_ABORT | COREWEBVIEW2_PRINT_STATUS_OTHER_ERROR | Print operation is failed as printing job already in progress. | + /// /// function Print(const aPrintSettings: ICoreWebView2PrintSettings; const aHandler: ICoreWebView2PrintCompletedHandler): boolean; /// - /// Opens the print dialog to print the current web page. See `COREWEBVIEW2_PRINT_DIALOG_KIND` - /// for descriptions of print dialog kinds. - /// - /// Invoking browser or system print dialog doesn't open new print dialog if - /// it is already open. + /// Opens the print dialog to print the current web page. See `COREWEBVIEW2_PRINT_DIALOG_KIND` + /// for descriptions of print dialog kinds. + /// Invoking browser or system print dialog doesn't open new print dialog if + /// it is already open. /// function ShowPrintUI(aPrintDialogKind: TWVPrintDialogKind): boolean; /// - /// Provides the Pdf data of current web page asynchronously for the provided settings. - /// Stream will be rewound to the start of the pdf data. - /// - /// See `ICoreWebView2PrintSettings` for description of settings. Passing - /// nullptr for `printSettings` results in default print settings used. - /// - /// The async `PrintToPdfStream` operation completes when it finishes + /// Provides the Pdf data of current web page asynchronously for the provided settings. + /// Stream will be rewound to the start of the pdf data. + /// See `ICoreWebView2PrintSettings` for description of settings. Passing + /// nullptr for `printSettings` results in default print settings used. + /// The async `PrintToPdfStream` operation completes when it finishes /// writing to the stream. At this time the `ICoreWebView2PrintToPdfStreamCompletedHandler` /// is invoked. Only one `Printing` operation can be in progress at a time. If /// `PrintToPdfStream` is called while a `PrintToPdfStream` or `PrintToPdf` or `Print` /// or `ShowPrintUI` job is in progress, the completed handler is immediately invoked with `E_ABORT`. - /// This is only for printing operation on one webview. + /// This is only for printing operation on one webview. /// function PrintToPdfStream(const aPrintSettings: ICoreWebView2PrintSettings; const aHandler: ICoreWebView2PrintToPdfStreamCompletedHandler): boolean; /// - /// Share a shared buffer object with script of the main frame in the WebView. + /// Share a shared buffer object with script of the main frame in the WebView. /// The script will receive a `sharedbufferreceived` event from chrome.webview. - /// The event arg for that event will have the following methods and properties: - /// `getBuffer()`: return an ArrayBuffer object with the backing content from the shared buffer. - /// `additionalData`: an object as the result of parsing `additionalDataAsJson` as JSON string. - /// This property will be `undefined` if `additionalDataAsJson` is nullptr or empty string. - /// `source`: with a value set as `chrome.webview` object. - /// If a string is provided as `additionalDataAsJson` but it is not a valid JSON string, - /// the API will fail with `E_INVALIDARG`. - /// If `access` is COREWEBVIEW2_SHARED_BUFFER_ACCESS_READ_ONLY, the script will only have read access to the buffer. + /// The event arg for that event will have the following methods and properties: + /// `getBuffer()`: return an ArrayBuffer object with the backing content from the shared buffer. + /// `additionalData`: an object as the result of parsing `additionalDataAsJson` as JSON string. + /// This property will be `undefined` if `additionalDataAsJson` is nullptr or empty string. + /// `source`: with a value set as `chrome.webview` object. + /// If a string is provided as `additionalDataAsJson` but it is not a valid JSON string, + /// the API will fail with `E_INVALIDARG`. + /// If `access` is COREWEBVIEW2_SHARED_BUFFER_ACCESS_READ_ONLY, the script will only have read access to the buffer. /// If the script tries to modify the content in a read only buffer, it will cause an access /// violation in WebView renderer process and crash the renderer process. - /// If the shared buffer is already closed, the API will fail with `RO_E_CLOSED`. - /// - /// The script code should call `chrome.webview.releaseBuffer` with + /// If the shared buffer is already closed, the API will fail with `RO_E_CLOSED`. + /// The script code should call `chrome.webview.releaseBuffer` with /// the shared buffer as the parameter to release underlying resources as soon - /// as it does not need access to the shared buffer any more. - /// - /// The application can post the same shared buffer object to multiple web pages or iframes, or + /// as it does not need access to the shared buffer any more. + /// The application can post the same shared buffer object to multiple web pages or iframes, or /// post to the same web page or iframe multiple times. Each `PostSharedBufferToScript` will /// create a separate ArrayBuffer object with its own view of the memory and is separately - /// released. The underlying shared memory will be released when all the views are released. + /// released. The underlying shared memory will be released when all the views are released. /// function PostSharedBufferToScript(const aSharedBuffer: ICoreWebView2SharedBuffer; aAccess: TWVSharedBufferAccess; const aAdditionalDataAsJson: wvstring): boolean; diff --git a/source/uWVCoreWebView2Args.pas b/source/uWVCoreWebView2Args.pas index a80c4b7..31983f0 100644 --- a/source/uWVCoreWebView2Args.pas +++ b/source/uWVCoreWebView2Args.pas @@ -459,7 +459,7 @@ TCoreWebView2NavigationStartingEventArgs = class property NavigationID : uint64 read GetNavigationID; /// /// The HTTP request headers for the navigation. - /// \> [!NOTE]\n\> You are not able to modify the HTTP request headers in a + /// \>NOTE: You are not able to modify the HTTP request headers in a /// `NavigationStarting` event. /// /// @@ -657,9 +657,9 @@ TCoreWebView2PermissionRequestedEventArgs = class /// property PermissionKind : TWVPermissionKind read GetPermissionKind; /// - /// `TRUE` when the permission request was initiated through a user gesture. - /// \> [!NOTE]\n\> Being initiated through a user gesture does not mean that user intended - /// to access the associated resource. + /// `TRUE` when the permission request was initiated through a user gesture. + /// NOTE: Being initiated through a user gesture does not mean that user intended + /// to access the associated resource. /// /// /// See the ICoreWebView2PermissionRequestedEventArgs article. @@ -740,23 +740,33 @@ TCoreWebView2ProcessFailedEventArgs = class /// property BaseIntf : ICoreWebView2ProcessFailedEventArgs read FBaseIntf; /// - /// The kind of process failure that has occurred. `processFailedKind` is - /// `COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_EXITED` if the - /// failed process is the main frame's renderer, even if there were subframes - /// rendered by such process; all frames are gone when this happens. + /// The kind of process failure that has occurred. This is a combination of + /// process kind (for example, browser, renderer, gpu) and failure (exit, + /// unresponsiveness). Renderer processes are further divided in _main frame_ + /// renderer (`RenderProcessExited`, `RenderProcessUnresponsive`) and + /// _subframe_ renderer (`FrameRenderProcessExited`). To learn about the + /// conditions under which each failure kind occurs, see + /// `COREWEBVIEW2_PROCESS_FAILED_KIND`. /// /// /// See the ICoreWebView2ProcessFailedEventArgs article. /// property ProcessFailedKind : TWVProcessFailedKind read GetProcessFailedKind; /// - /// The reason for the process failure. The reason is always - /// `COREWEBVIEW2_PROCESS_FAILED_REASON_UNEXPECTED` when `ProcessFailedKind` - /// is `COREWEBVIEW2_PROCESS_FAILED_KIND_BROWSER_PROCESS_EXITED`, and - /// `COREWEBVIEW2_PROCESS_FAILED_REASON_UNRESPONSIVE` when `ProcessFailedKind` - /// is `COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_UNRESPONSIVE`. - /// For other process failure kinds, the reason may be any of the reason - /// values. + /// The reason for the process failure. Some of the reasons are only + /// applicable to specific values of + /// `ICoreWebView2ProcessFailedEventArgs.ProcessFailedKind`, and the + /// following `ProcessFailedKind` values always return the indicated reason + /// value: + /// + /// ProcessFailedKind | Reason + /// ---|--- + /// COREWEBVIEW2_PROCESS_FAILED_KIND_BROWSER_PROCESS_EXITED | COREWEBVIEW2_PROCESS_FAILED_REASON_UNEXPECTED + /// COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_UNRESPONSIVE | COREWEBVIEW2_PROCESS_FAILED_REASON_UNRESPONSIVE + /// + /// For other `ProcessFailedKind` values, the reason may be any of the reason + /// values. To learn about what these values mean, see + /// `COREWEBVIEW2_PROCESS_FAILED_REASON`. /// /// /// See the ICoreWebView2ProcessFailedEventArgs2 article. @@ -1705,7 +1715,7 @@ TCoreWebView2LaunchingExternalUriSchemeEventArgs = class property InitiatingOrigin : wvstring read GetInitiatingOrigin; /// /// `TRUE` when the external URI scheme request was initiated through a user gesture. - /// \> [!NOTE]\n\> Being initiated through a user gesture does not mean that user intended + /// \>NOTE: Being initiated through a user gesture does not mean that user intended /// to access the associated resource. /// /// diff --git a/source/uWVCoreWebView2Frame.pas b/source/uWVCoreWebView2Frame.pas index c156b54..7826f0f 100644 --- a/source/uWVCoreWebView2Frame.pas +++ b/source/uWVCoreWebView2Frame.pas @@ -120,7 +120,7 @@ TCoreWebView2Frame = class /// contains a reference cycle, or otherwise is not able to be encoded into /// JSON, then the result is considered to be null, which is encoded /// in JSON as the string "null". - /// \> [!NOTE]\n\> A function that has no explicit return value returns undefined. If the + /// NOTE: A function that has no explicit return value returns undefined. If the /// script that was run throws an unhandled exception, then the result is /// also "null". This method is applied asynchronously. If the method is /// run before `ContentLoading`, the script will not be executed @@ -137,10 +137,11 @@ TCoreWebView2Frame = class /// The frame receives the message by subscribing to the `message` event of /// the `window.chrome.webview` of the frame document. /// + /// /// ```cpp /// window.chrome.webview.addEventListener('message', handler) /// window.chrome.webview.removeEventListener('message', handler) - /// ``` + /// ``` /// /// The event args is an instances of `MessageEvent`. The /// `ICoreWebView2Settings::IsWebMessageEnabled` setting must be `TRUE` or diff --git a/source/uWVTypeLibrary.pas b/source/uWVTypeLibrary.pas index ea523b2..9607873 100644 --- a/source/uWVTypeLibrary.pas +++ b/source/uWVTypeLibrary.pas @@ -662,7 +662,7 @@ interface type /// /// Specifies the process failure type used in the - /// ICoreWebView2ProcessFailedEventHandler interface. The values in this enum + /// `ICoreWebView2ProcessFailedEventArgs` interface. The values in this enum /// make reference to the process kinds in the Chromium architecture. For more /// information about what these processes are and what they do, see /// [Browser Architecture - Inside look at modern web browser](https://developers.google.com/web/updates/2018/09/inside-browser-part1). @@ -682,72 +682,106 @@ interface /// COREWEBVIEW2_PROCESS_FAILED_KIND_BROWSER_PROCESS_EXITED = $00000000; /// - /// Indicates that the main frame's render process ended unexpectedly. A new - /// render process is created automatically and navigated to an error page. - /// You can use the Reload method to try to reload the page that failed. + /// Indicates that the main frame's render process ended unexpectedly. Any + /// subframes in the WebView will be gone too. A new render process is + /// created automatically and navigated to an error page. You can use the + /// `Reload` method to try to recover from this failure. Alternatively, you + /// can `Close` and recreate the WebView. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_KIND values. /// COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_EXITED = $00000001; /// - /// Indicates that the main frame's render process is unresponsive. + /// Indicates that the main frame's render process is unresponsive. Renderer + /// process unresponsiveness can happen for the following reasons: + /// * There is a **long-running script** being executed. For example, the + /// web content in your WebView might be performing a synchronous XHR, or have + /// entered an infinite loop. + /// * The **system is busy**. + /// The `ProcessFailed` event will continue to be raised every few seconds + /// until the renderer process has become responsive again. The application + /// can consider taking action if the event keeps being raised. For example, + /// the application might show UI for the user to decide to keep waiting or + /// reload the page, or navigate away. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_KIND values. - /// Note that this does not seem to work right now. - /// Does not fire for simple long running script case, the only related test - /// SitePerProcessBrowserTest::NoCommitTimeoutForInvisibleWebContents is - /// disabled. /// COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_UNRESPONSIVE = $00000002; /// /// Indicates that a frame-only render process ended unexpectedly. The process /// exit does not affect the top-level document, only a subset of the /// subframes within it. The content in these frames is replaced with an error - /// page in the frame. + /// page in the frame. Your application can communicate with the main frame to + /// recover content in the impacted frames, using + /// `ICoreWebView2ProcessFailedEventArgs2.FrameInfosForFailedProcess` to get + /// information about the impacted frames. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_KIND values. /// COREWEBVIEW2_PROCESS_FAILED_KIND_FRAME_RENDER_PROCESS_EXITED = $00000003; /// - /// Indicates that a utility process ended unexpectedly. + /// Indicates that a utility process ended unexpectedly. The failed process + /// is recreated automatically. Your application does **not** need to handle + /// recovery for this event, but can use `ICoreWebView2ProcessFailedEventArgs` + /// and `ICoreWebView2ProcessFailedEventArgs2` to collect information about + /// the failure, including `ProcessDescription`. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_KIND values. /// COREWEBVIEW2_PROCESS_FAILED_KIND_UTILITY_PROCESS_EXITED = $00000004; /// - /// Indicates that a sandbox helper process ended unexpectedly. + /// Indicates that a sandbox helper process ended unexpectedly. This failure + /// is not fatal. Your application does **not** need to handle recovery for + /// this event, but can use `ICoreWebView2ProcessFailedEventArgs` and + /// `ICoreWebView2ProcessFailedEventArgs2` to collect information about + /// the failure. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_KIND values. /// COREWEBVIEW2_PROCESS_FAILED_KIND_SANDBOX_HELPER_PROCESS_EXITED = $00000005; /// - /// Indicates that the GPU process ended unexpectedly. + /// Indicates that the GPU process ended unexpectedly. The failed process + /// is recreated automatically. Your application does **not** need to handle + /// recovery for this event, but can use `ICoreWebView2ProcessFailedEventArgs` + /// and `ICoreWebView2ProcessFailedEventArgs2` to collect information about + /// the failure. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_KIND values. /// COREWEBVIEW2_PROCESS_FAILED_KIND_GPU_PROCESS_EXITED = $00000006; /// - /// Indicates that a PPAPI plugin process ended unexpectedly. + /// Indicates that a PPAPI plugin process ended unexpectedly. This failure + /// is not fatal. Your application does **not** need to handle recovery for + /// this event, but can use `ICoreWebView2ProcessFailedEventArgs` and + /// `ICoreWebView2ProcessFailedEventArgs2` to collect information about + /// the failure, including `ProcessDescription`. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_KIND values. /// COREWEBVIEW2_PROCESS_FAILED_KIND_PPAPI_PLUGIN_PROCESS_EXITED = $00000007; /// - /// Indicates that a PPAPI plugin broker process ended unexpectedly. + /// Indicates that a PPAPI plugin broker process ended unexpectedly. This failure + /// is not fatal. Your application does **not** need to handle recovery for + /// this event, but can use `ICoreWebView2ProcessFailedEventArgs` and + /// `ICoreWebView2ProcessFailedEventArgs2` to collect information about + /// the failure. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_KIND values. /// COREWEBVIEW2_PROCESS_FAILED_KIND_PPAPI_BROKER_PROCESS_EXITED = $00000008; /// - /// Indicates that a process of unspecified kind ended unexpectedly. + /// Indicates that a process of unspecified kind ended unexpectedly. Your + /// application can use `ICoreWebView2ProcessFailedEventArgs` and + /// `ICoreWebView2ProcessFailedEventArgs2` to collect information about + /// the failure. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_KIND values. @@ -2179,7 +2213,8 @@ interface /// COREWEBVIEW2_PROCESS_FAILED_REASON_TERMINATED = $00000002; /// - /// The process crashed. + /// The process crashed. Most crashes will generate dumps in the location + /// indicated by `ICoreWebView2Environment11.get_FailureReportFolderPath`. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_REASON values. @@ -2193,7 +2228,7 @@ interface /// COREWEBVIEW2_PROCESS_FAILED_REASON_LAUNCH_FAILED = $00000004; /// - /// The process died due to running out of memory. + /// The process terminated due to running out of memory. /// /// /// This is one of the COREWEBVIEW2_PROCESS_FAILED_REASON values. @@ -3465,15 +3500,31 @@ EventRegistrationToken = record /// function remove_PermissionRequested(token: EventRegistrationToken): HResult; stdcall; /// - /// Add an event handler for the `ProcessFailed` event. `ProcessFailed` runs - /// when a WebView process ends unexpectedly or becomes unresponsive. + /// Add an event handler for the `ProcessFailed` event. + /// `ProcessFailed` runs when any of the processes in the + /// [WebView2 Process Group](https://learn.microsoft.com/microsoft-edge/webview2/concepts/process-model?tabs=csharp#processes-in-the-webview2-runtime) + /// encounters one of the following conditions: + /// + /// Condition | Details + /// ---|--- + /// Unexpected exit | The process indicated by the event args has exited unexpectedly (usually due to a crash). The failure might or might not be recoverable and some failures are auto-recoverable. + /// Unresponsiveness | The process indicated by the event args has become unresponsive to user input. This is only reported for renderer processes, and will run every few seconds until the process becomes responsive again. + /// + /// \> [!NOTE]\n\> When the failing process is the browser process, a + /// `ICoreWebView2Environment5::BrowserProcessExited` event will run too. + /// + /// Your application can use `ICoreWebView2ProcessFailedEventArgs` and + /// `ICoreWebView2ProcessFailedEventArgs2` to identify which condition and + /// process the event is for, and to collect diagnostics and handle recovery + /// if necessary. For more details about which cases need to be handled by + /// your application, see `COREWEBVIEW2_PROCESS_FAILED_KIND`. /// /// \snippet ProcessComponent.cpp ProcessFailed /// - function add_ProcessFailed(const eventHandler: ICoreWebView2ProcessFailedEventHandler; + function add_ProcessFailed(const eventHandler: ICoreWebView2ProcessFailedEventHandler; out token: EventRegistrationToken): HResult; stdcall; /// - /// Remove an event handler previously added with add_ProcessFailed. + /// Remove an event handler previously added with `add_ProcessFailed`. /// function remove_ProcessFailed(token: EventRegistrationToken): HResult; stdcall; /// @@ -3849,6 +3900,9 @@ EventRegistrationToken = record /// /// In the HTML document, use the COM object using /// `chrome.webview.hostObjects.sample`. + /// Note that `CoreWebView2.AddHostObjectToScript` only applies to the + /// top-level document and not to frames. To add host objects to frames use + /// `CoreWebView2Frame.AddHostObjectToScript`. /// /// \snippet assets\ScenarioAddHostObject.html HostObjectUsage /// @@ -4571,10 +4625,13 @@ EventRegistrationToken = record ICoreWebView2ProcessFailedEventArgs = interface(IUnknown) ['{8155A9A4-1474-4A86-8CAE-151B0FA6B8CA}'] /// - /// The kind of process failure that has occurred. `processFailedKind` is - /// `COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_EXITED` if the - /// failed process is the main frame's renderer, even if there were subframes - /// rendered by such process; all frames are gone when this happens. + /// The kind of process failure that has occurred. This is a combination of + /// process kind (for example, browser, renderer, gpu) and failure (exit, + /// unresponsiveness). Renderer processes are further divided in _main frame_ + /// renderer (`RenderProcessExited`, `RenderProcessUnresponsive`) and + /// _subframe_ renderer (`FrameRenderProcessExited`). To learn about the + /// conditions under which each failure kind occurs, see + /// `COREWEBVIEW2_PROCESS_FAILED_KIND`. /// function Get_ProcessFailedKind(out ProcessFailedKind: COREWEBVIEW2_PROCESS_FAILED_KIND): HResult; stdcall; end; @@ -10826,13 +10883,20 @@ EventRegistrationToken = record ICoreWebView2ProcessFailedEventArgs2 = interface(ICoreWebView2ProcessFailedEventArgs) ['{4DAB9422-46FA-4C3E-A5D2-41D2071D3680}'] /// - /// The reason for the process failure. The reason is always - /// `COREWEBVIEW2_PROCESS_FAILED_REASON_UNEXPECTED` when `ProcessFailedKind` - /// is `COREWEBVIEW2_PROCESS_FAILED_KIND_BROWSER_PROCESS_EXITED`, and - /// `COREWEBVIEW2_PROCESS_FAILED_REASON_UNRESPONSIVE` when `ProcessFailedKind` - /// is `COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_UNRESPONSIVE`. - /// For other process failure kinds, the reason may be any of the reason - /// values. + /// The reason for the process failure. Some of the reasons are only + /// applicable to specific values of + /// `ICoreWebView2ProcessFailedEventArgs::ProcessFailedKind`, and the + /// following `ProcessFailedKind` values always return the indicated reason + /// value: + /// + /// ProcessFailedKind | Reason + /// ---|--- + /// COREWEBVIEW2_PROCESS_FAILED_KIND_BROWSER_PROCESS_EXITED | COREWEBVIEW2_PROCESS_FAILED_REASON_UNEXPECTED + /// COREWEBVIEW2_PROCESS_FAILED_KIND_RENDER_PROCESS_UNRESPONSIVE | COREWEBVIEW2_PROCESS_FAILED_REASON_UNRESPONSIVE + /// + /// For other `ProcessFailedKind` values, the reason may be any of the reason + /// values. To learn about what these values mean, see + /// `COREWEBVIEW2_PROCESS_FAILED_REASON`. /// function Get_reason(out reason: COREWEBVIEW2_PROCESS_FAILED_REASON): HResult; stdcall; /// diff --git a/source/uWVTypes.pas b/source/uWVTypes.pas index e3507ff..479c987 100644 --- a/source/uWVTypes.pas +++ b/source/uWVTypes.pas @@ -70,7 +70,7 @@ interface TWVPermissionKind = type COREWEBVIEW2_PERMISSION_KIND; /// /// Specifies the process failure type used in the - /// ICoreWebView2ProcessFailedEventHandler interface. The values in this enum + /// `ICoreWebView2ProcessFailedEventArgs` interface. The values in this enum /// make reference to the process kinds in the Chromium architecture. For more /// information about what these processes are and what they do, see /// [Browser Architecture - Inside look at modern web browser](https://developers.google.com/web/updates/2018/09/inside-browser-part1). diff --git a/source/uWVVersion.inc b/source/uWVVersion.inc index 0a08348..0645e99 100644 --- a/source/uWVVersion.inc +++ b/source/uWVVersion.inc @@ -1,12 +1,12 @@ WEBVIEW2LOADERLIB_VERSION_MAJOR = 1; WEBVIEW2LOADERLIB_VERSION_MINOR = 0; - WEBVIEW2LOADERLIB_VERSION_RELEASE = 1901; - WEBVIEW2LOADERLIB_VERSION_BUILD = 177; + WEBVIEW2LOADERLIB_VERSION_RELEASE = 1938; + WEBVIEW2LOADERLIB_VERSION_BUILD = 49; // For full API compatibility, WebView4Delphi requires the same // WebView2 Runtime version mentioned in the release notes : // https://docs.microsoft.com/en-us/microsoft-edge/webview2/release-notes - CHROMIUM_VERSION_MAJOR = 115; + CHROMIUM_VERSION_MAJOR = 116; CHROMIUM_VERSION_MINOR = 0; CHROMIUM_VERSION_RELEASE = WEBVIEW2LOADERLIB_VERSION_RELEASE; CHROMIUM_VERSION_BUILD = WEBVIEW2LOADERLIB_VERSION_BUILD; \ No newline at end of file diff --git a/update_WebView4Delphi.json b/update_WebView4Delphi.json index 0113239..bd83571 100644 --- a/update_WebView4Delphi.json +++ b/update_WebView4Delphi.json @@ -2,9 +2,9 @@ "UpdateLazPackages" : [ { "ForceNotify" : true, - "InternalVersion" : 114, + "InternalVersion" : 115, "Name" : "webview4delphi.lpk", - "Version" : "1.0.1901.177" + "Version" : "1.0.1938.49" } ], "UpdatePackageData" : {