Trait webview2_sys::ICoreWebView2 [−][src]
pub trait ICoreWebView2: IUnknown {
Show 58 methods
unsafe fn get_settings(
&self,
settings: *mut *mut *mut ICoreWebView2SettingsVTable
) -> HRESULT;
unsafe fn get_source(&self, uri: *mut LPWSTR) -> HRESULT;
unsafe fn navigate(&self, uri: LPCWSTR) -> HRESULT;
unsafe fn navigate_to_string(&self, html_content: LPCWSTR) -> HRESULT;
unsafe fn add_navigation_starting(
&self,
event_handler: *mut *mut ICoreWebView2NavigationStartingEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_navigation_starting(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_content_loading(
&self,
event_handler: *mut *mut ICoreWebView2ContentLoadingEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_content_loading(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_source_changed(
&self,
event_handler: *mut *mut ICoreWebView2SourceChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_source_changed(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_history_changed(
&self,
event_handler: *mut *mut ICoreWebView2HistoryChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_history_changed(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_navigation_completed(
&self,
event_handler: *mut *mut ICoreWebView2NavigationCompletedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_navigation_completed(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_frame_navigation_starting(
&self,
event_handler: *mut *mut ICoreWebView2NavigationStartingEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_frame_navigation_starting(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_frame_navigation_completed(
&self,
event_handler: *mut *mut ICoreWebView2NavigationCompletedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_frame_navigation_completed(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_script_dialog_opening(
&self,
event_handler: *mut *mut ICoreWebView2ScriptDialogOpeningEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_script_dialog_opening(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_permission_requested(
&self,
event_handler: *mut *mut ICoreWebView2PermissionRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_permission_requested(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_process_failed(
&self,
event_handler: *mut *mut ICoreWebView2ProcessFailedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_process_failed(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_script_to_execute_on_document_created(
&self,
java_script: LPCWSTR,
handler: *mut *mut ICoreWebView2AddScriptToExecuteOnDocumentCreatedCompletedHandlerVTable
) -> HRESULT;
unsafe fn remove_script_to_execute_on_document_created(
&self,
id: LPCWSTR
) -> HRESULT;
unsafe fn execute_script(
&self,
java_script: LPCWSTR,
handler: *mut *mut ICoreWebView2ExecuteScriptCompletedHandlerVTable
) -> HRESULT;
unsafe fn capture_preview(
&self,
image_format: CapturePreviewImageFormat,
image_stream: *mut *mut IStreamVTable,
handler: *mut *mut ICoreWebView2CapturePreviewCompletedHandlerVTable
) -> HRESULT;
unsafe fn reload(&self) -> HRESULT;
unsafe fn post_web_message_as_json(
&self,
web_message_as_json: LPCWSTR
) -> HRESULT;
unsafe fn post_web_message_as_string(
&self,
web_message_as_string: LPCWSTR
) -> HRESULT;
unsafe fn add_web_message_received(
&self,
handler: *mut *mut ICoreWebView2WebMessageReceivedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_web_message_received(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn call_dev_tools_protocol_method(
&self,
method_name: LPCWSTR,
parameters_as_json: LPCWSTR,
handler: *mut *mut ICoreWebView2CallDevToolsProtocolMethodCompletedHandlerVTable
) -> HRESULT;
unsafe fn get_browser_process_id(&self, value: *mut u32) -> HRESULT;
unsafe fn get_can_go_back(&self, can_go_back: *mut BOOL) -> HRESULT;
unsafe fn get_can_go_forward(&self, can_go_forward: *mut BOOL) -> HRESULT;
unsafe fn go_back(&self) -> HRESULT;
unsafe fn go_forward(&self) -> HRESULT;
unsafe fn get_dev_tools_protocol_event_receiver(
&self,
event_name: LPCWSTR,
receiver: *mut *mut *mut ICoreWebView2DevToolsProtocolEventReceiverVTable
) -> HRESULT;
unsafe fn stop(&self) -> HRESULT;
unsafe fn add_new_window_requested(
&self,
event_handler: *mut *mut ICoreWebView2NewWindowRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_new_window_requested(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_document_title_changed(
&self,
event_handler: *mut *mut ICoreWebView2DocumentTitleChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_document_title_changed(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn get_document_title(&self, title: *mut LPWSTR) -> HRESULT;
unsafe fn add_host_object_to_script(
&self,
name: LPCWSTR,
object: *mut VARIANT
) -> HRESULT;
unsafe fn remove_host_object_from_script(&self, name: LPCWSTR) -> HRESULT;
unsafe fn open_dev_tools_window(&self) -> HRESULT;
unsafe fn add_contains_full_screen_element_changed(
&self,
event_handler: *mut *mut ICoreWebView2ContainsFullScreenElementChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_contains_full_screen_element_changed(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn get_contains_full_screen_element(
&self,
contains_full_screen_element: *mut BOOL
) -> HRESULT;
unsafe fn add_web_resource_requested(
&self,
event_handler: *mut *mut ICoreWebView2WebResourceRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_web_resource_requested(
&self,
token: EventRegistrationToken
) -> HRESULT;
unsafe fn add_web_resource_requested_filter(
&self,
uri: LPCWSTR,
resource_context: WebResourceContext
) -> HRESULT;
unsafe fn remove_web_resource_requested_filter(
&self,
uri: LPCWSTR,
resource_context: WebResourceContext
) -> HRESULT;
unsafe fn add_window_close_requested(
&self,
event_handler: *mut *mut ICoreWebView2WindowCloseRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT;
unsafe fn remove_window_close_requested(
&self,
token: EventRegistrationToken
) -> HRESULT;
}
Expand description
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
Required methods
unsafe fn get_settings(
&self,
settings: *mut *mut *mut ICoreWebView2SettingsVTable
) -> HRESULT
unsafe fn get_settings(
&self,
settings: *mut *mut *mut ICoreWebView2SettingsVTable
) -> HRESULT
The ICoreWebView2Settings
object contains various modifiable settings
for the running WebView.
unsafe fn get_source(&self, uri: *mut LPWSTR) -> HRESULT
unsafe fn get_source(&self, uri: *mut LPWSTR) -> HRESULT
The URI of the current top level document. This value potentially
changes as a part of the SourceChanged
event that runs for some cases
such as navigating to a different site or fragment navigations. It
remains the same for other types of navigations such as page refreshes
or history.pushState
with the same URL as the current page.
\snippet ControlComponent.cpp SourceChanged
Cause a navigation of the top-level document to run to the specified URI. For more information, navigate to [Navigation events][MicrosoftEdgeWebview2ConceptsNavigationevents].
[MicrosoftEdgeWebview2ConceptsNavigationevents]: /microsoft-edge/webview2/concepts/navigation-events “Navigation events | Microsoft Docs”
> [!NOTE]\n> This operation starts a navigation and the corresponding
NavigationStarting
event triggers sometime after Navigate
runs.
\snippet ControlComponent.cpp Navigate
Initiates a navigation to htmlContent as source HTML of a new document.
The htmlContent
parameter may not be larger than 2 MB (2 * 1024 * 1024 bytes) in total size.
The origin of the new page is about:blank
.
\snippet SettingsComponent.cpp NavigateToString
Add an event handler for the NavigationStarting
event.
NavigationStarting
runs when the WebView main frame is requesting
permission to navigate to a different URI. Redirects trigger this
operation as well, and the navigation id is the same as the original
one.
You may block corresponding navigations until the event handler returns.
\snippet SettingsComponent.cpp NavigationStarting
Remove an event handler previously added with add_NavigationStarting
.
unsafe fn add_content_loading(
&self,
event_handler: *mut *mut ICoreWebView2ContentLoadingEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_content_loading(
&self,
event_handler: *mut *mut ICoreWebView2ContentLoadingEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the ContentLoading
event. ContentLoading
triggers before any content is loaded, including scripts added with
AddScriptToExecuteOnDocumentCreated
. ContentLoading
does not trigger
if a same page navigation occurs (such as through fragment
navigations or history.pushState
navigations). This operation
follows the NavigationStarting
and SourceChanged
events and precedes
the HistoryChanged
and NavigationCompleted
events.
unsafe fn remove_content_loading(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_content_loading(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with add_ContentLoading
.
unsafe fn add_source_changed(
&self,
event_handler: *mut *mut ICoreWebView2SourceChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_source_changed(
&self,
event_handler: *mut *mut ICoreWebView2SourceChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the SourceChanged
event. SourceChanged
triggers when the Source
property changes. SourceChanged
runs when
navigating to a different site or fragment navigations. It does not
trigger for other types of navigations such as page refreshes or
history.pushState
with the same URL as the current page.
SourceChanged
runs before ContentLoading
for navigation to a new
document.
\snippet ControlComponent.cpp SourceChanged
unsafe fn remove_source_changed(&self, token: EventRegistrationToken) -> HRESULT
unsafe fn remove_source_changed(&self, token: EventRegistrationToken) -> HRESULT
Remove an event handler previously added with add_SourceChanged
.
unsafe fn add_history_changed(
&self,
event_handler: *mut *mut ICoreWebView2HistoryChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_history_changed(
&self,
event_handler: *mut *mut ICoreWebView2HistoryChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the HistoryChanged
event. HistoryChanged
listens to the change of navigation history for the top level document.
Use HistoryChanged
to verify that the CanGoBack
or CanGoForward
value has changed. HistoryChanged
also runs for using GoBack
or
GoForward
. HistoryChanged
runs after SourceChanged
and
ContentLoading
.
\snippet ControlComponent.cpp HistoryChanged
unsafe fn remove_history_changed(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_history_changed(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with add_HistoryChanged
.
Add an event handler for the NavigationCompleted
event.
NavigationCompleted
runs when the WebView has completely loaded
(body.onload
runs) or loading stopped with error.
\snippet ControlComponent.cpp NavigationCompleted
Remove an event handler previously added with add_NavigationCompleted
.
Add an event handler for the FrameNavigationStarting
event.
FrameNavigationStarting
triggers when a child frame in the WebView
requests permission to navigate to a different URI. Redirects trigger
this operation as well, and the navigation id is the same as the original
one.
You may block corresponding navigations until the event handler returns.
\snippet SettingsComponent.cpp FrameNavigationStarting
Remove an event handler previously added with
add_FrameNavigationStarting
.
Add an event handler for the FrameNavigationCompleted
event.
FrameNavigationCompleted
triggers when a child frame has completely
loaded (body.onload
has triggered) or loading stopped with error.
\snippet ControlComponent.cpp FrameNavigationCompleted
Remove an event handler previously added with
add_FrameNavigationCompleted
.
unsafe fn add_script_dialog_opening(
&self,
event_handler: *mut *mut ICoreWebView2ScriptDialogOpeningEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_script_dialog_opening(
&self,
event_handler: *mut *mut ICoreWebView2ScriptDialogOpeningEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the ScriptDialogOpening
event.
ScriptDialogOpening
runs when a JavaScript dialog (alert
, confirm
,
prompt
, or beforeunload
) displays for the webview. This event only
triggers if the ICoreWebView2Settings::AreDefaultScriptDialogsEnabled
property is set to FALSE
. The ScriptDialogOpening
event suppresses
dialogs or replaces default dialogs with custom dialogs.
If a deferral is not taken on the event args, the subsequent scripts are blocked until the event handler returns. If a deferral is taken, the scripts are blocked until the deferral is completed.
\snippet SettingsComponent.cpp ScriptDialogOpening
unsafe fn remove_script_dialog_opening(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_script_dialog_opening(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with add_ScriptDialogOpening
.
unsafe fn add_permission_requested(
&self,
event_handler: *mut *mut ICoreWebView2PermissionRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_permission_requested(
&self,
event_handler: *mut *mut ICoreWebView2PermissionRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the PermissionRequested
event.
PermissionRequested
runs when content in a WebView requests permission
to access some privileged resources.
If a deferral is not taken on the event args, the subsequent scripts are blocked until the event handler returns. If a deferral is taken, the scripts are blocked until the deferral is completed.
\snippet SettingsComponent.cpp PermissionRequested
unsafe fn remove_permission_requested(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_permission_requested(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with add_PermissionRequested
.
unsafe fn add_process_failed(
&self,
event_handler: *mut *mut ICoreWebView2ProcessFailedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_process_failed(
&self,
event_handler: *mut *mut ICoreWebView2ProcessFailedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the ProcessFailed
event. ProcessFailed
runs
when a WebView process ends unexpectedly or becomes unresponsive.
\snippet ProcessComponent.cpp ProcessFailed
unsafe fn remove_process_failed(&self, token: EventRegistrationToken) -> HRESULT
unsafe fn remove_process_failed(&self, token: EventRegistrationToken) -> HRESULT
Remove an event handler previously added with add_ProcessFailed.
unsafe fn add_script_to_execute_on_document_created(
&self,
java_script: LPCWSTR,
handler: *mut *mut ICoreWebView2AddScriptToExecuteOnDocumentCreatedCompletedHandlerVTable
) -> HRESULT
unsafe fn add_script_to_execute_on_document_created(
&self,
java_script: LPCWSTR,
handler: *mut *mut ICoreWebView2AddScriptToExecuteOnDocumentCreatedCompletedHandlerVTable
) -> HRESULT
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
and child frame page navigations. This method runs asynchronously, and
you must wait for the completion handler to finish before the injected
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
after the new window is set. For more details see ICoreWebView2NewWindowRequestedEventArgs::put_NewWindow
.
> [!NOTE]\n> If an HTML document is running in a sandbox of some kind using
[sandbox][MdnDocsWebHtmlElementIframeAttrSandbox]
properties or the
[Content-Security-Policy][MdnDocsWebHttpHeadersContentSecurityPolicy]
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.
\snippet ScriptComponent.cpp AddScriptToExecuteOnDocumentCreated
[MdnDocsWebHtmlElementIframeAttrSandbox]: https://developer.mozilla.org/docs/Web/HTML/Element/iframe#attr-sandbox “sandbox - <iframe>: The Inline Frame element | MDN”
[MdnDocsWebHttpHeadersContentSecurityPolicy]: https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy “Content-Security-Policy | MDN”
unsafe fn remove_script_to_execute_on_document_created(
&self,
id: LPCWSTR
) -> HRESULT
unsafe fn remove_script_to_execute_on_document_created(
&self,
id: LPCWSTR
) -> HRESULT
Remove the corresponding JavaScript added using
AddScriptToExecuteOnDocumentCreated
with the specified script ID.
unsafe fn execute_script(
&self,
java_script: LPCWSTR,
handler: *mut *mut ICoreWebView2ExecuteScriptCompletedHandlerVTable
) -> HRESULT
unsafe fn execute_script(
&self,
java_script: LPCWSTR,
handler: *mut *mut ICoreWebView2ExecuteScriptCompletedHandlerVTable
) -> HRESULT
Run JavaScript code from the javascript parameter in the current
top-level document rendered in the WebView. The result of evaluating
the provided JavaScript is used in this parameter. The result value is
a JSON encoded string. If the result is undefined, contains a reference
cycle, or otherwise is not able to be encoded into JSON, the JSON null
value is returned as the null
string.
> [!NOTE]\n> 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 after the NavigationStarting
event during a navigation, the script
runs in the new document when loading it, around the time
ContentLoading
is run. This operation works even if
ICoreWebView2Settings::IsScriptEnabled
is set to FALSE
.
\snippet ScriptComponent.cpp ExecuteScript
unsafe fn capture_preview(
&self,
image_format: CapturePreviewImageFormat,
image_stream: *mut *mut IStreamVTable,
handler: *mut *mut ICoreWebView2CapturePreviewCompletedHandlerVTable
) -> HRESULT
unsafe fn capture_preview(
&self,
image_format: CapturePreviewImageFormat,
image_stream: *mut *mut IStreamVTable,
handler: *mut *mut ICoreWebView2CapturePreviewCompletedHandlerVTable
) -> HRESULT
Capture an image of what WebView is displaying. Specify the format of
the image with the imageFormat
parameter. The resulting image binary
data is written to the provided imageStream
parameter. When
CapturePreview
finishes writing to the stream, the Invoke
method on
the provided handler
parameter is run. This method fails if called
before the first ContentLoading event. For example if this is called in
the NavigationStarting event for the first navigation it will fail.
For subsequent navigations, the method may not fail, but will not capture
an image of a given webpage until the ContentLoading event has been fired
for it. Any call to this method prior to that will result in a capture of
the page being navigated away from.
\snippet FileComponent.cpp CapturePreview
Reload the current page. This is similar to navigating to the URI of current top level document including all navigation events firing and respecting any entries in the HTTP cache. But, the back or forward history are not modified.
unsafe fn post_web_message_as_json(
&self,
web_message_as_json: LPCWSTR
) -> HRESULT
unsafe fn post_web_message_as_json(
&self,
web_message_as_json: LPCWSTR
) -> HRESULT
Post the specified webMessage to the top level document in this WebView.
Runs the message event of the window.chrome.webview
of the top-level
document. JavaScript in that document may subscribe and unsubscribe to
the event using the following code.
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
this method fails with E_INVALIDARG
. 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]. The message is sent asynchronously. If a
navigation occurs before the message is posted to the page, the message
is not sent.
\snippet ScenarioWebMessage.cpp WebMessageReceived
unsafe fn post_web_message_as_string(
&self,
web_message_as_string: LPCWSTR
) -> HRESULT
unsafe fn post_web_message_as_string(
&self,
web_message_as_string: LPCWSTR
) -> HRESULT
Posts a message that is a simple string rather than a JSON string
representation of a JavaScript object. This behaves in exactly the same
manner as PostWebMessageAsJson
, but the data
property of the event
arg of the window.chrome.webview
message is a string with the same
value as webMessageAsString
. Use this instead of
PostWebMessageAsJson
if you want to communicate using simple strings
rather than JSON objects.
unsafe fn add_web_message_received(
&self,
handler: *mut *mut ICoreWebView2WebMessageReceivedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_web_message_received(
&self,
handler: *mut *mut ICoreWebView2WebMessageReceivedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the WebMessageReceived
event.
WebMessageReceived
runs when the
ICoreWebView2Settings::IsWebMessageEnabled
setting is set and the
top-level document of the WebView runs
window.chrome.webview.postMessage
. The postMessage
function is
void postMessage(object)
where object is any object supported by JSON
conversion.
\snippet assets\ScenarioWebMessage.html chromeWebView
When postMessage
is run, the Invoke
method of the handler
is run
with the object
parameter of the postMessage
converted to a JSON
string.
\snippet ScenarioWebMessage.cpp WebMessageReceived
unsafe fn remove_web_message_received(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_web_message_received(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with add_WebMessageReceived
.
unsafe fn call_dev_tools_protocol_method(
&self,
method_name: LPCWSTR,
parameters_as_json: LPCWSTR,
handler: *mut *mut ICoreWebView2CallDevToolsProtocolMethodCompletedHandlerVTable
) -> HRESULT
unsafe fn call_dev_tools_protocol_method(
&self,
method_name: LPCWSTR,
parameters_as_json: LPCWSTR,
handler: *mut *mut ICoreWebView2CallDevToolsProtocolMethodCompletedHandlerVTable
) -> HRESULT
Runs an asynchronous DevToolsProtocol
method. For more information
about available methods, navigate to
[DevTools Protocol Viewer][GithubChromedevtoolsDevtoolsProtocolTot]
. 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
asynchronously completes. Invoke
is run with the return object of the
method as a JSON string.
\snippet ScriptComponent.cpp CallDevToolsProtocolMethod
[GithubChromedevtoolsDevtoolsProtocolTot]: https://chromedevtools.github.io/devtools-protocol/tot “latest (tip-of-tree) protocol - Chrome DevTools Protocol | GitHub”
unsafe fn get_browser_process_id(&self, value: *mut u32) -> HRESULT
unsafe fn get_browser_process_id(&self, value: *mut u32) -> HRESULT
The process ID of the browser process that hosts the WebView.
unsafe fn get_can_go_back(&self, can_go_back: *mut BOOL) -> HRESULT
unsafe fn get_can_go_back(&self, can_go_back: *mut BOOL) -> HRESULT
TRUE
if the WebView is able to navigate to a previous page in the
navigation history. If CanGoBack
changes value, the HistoryChanged
event runs.
unsafe fn get_can_go_forward(&self, can_go_forward: *mut BOOL) -> HRESULT
unsafe fn get_can_go_forward(&self, can_go_forward: *mut BOOL) -> HRESULT
TRUE
if the WebView is able to navigate to a next page in the
navigation history. If CanGoForward
changes value, the
HistoryChanged
event runs.
Navigates the WebView to the previous page in the navigation history.
unsafe fn go_forward(&self) -> HRESULT
unsafe fn go_forward(&self) -> HRESULT
Navigates the WebView to the next page in the navigation history.
unsafe fn get_dev_tools_protocol_event_receiver(
&self,
event_name: LPCWSTR,
receiver: *mut *mut *mut ICoreWebView2DevToolsProtocolEventReceiverVTable
) -> HRESULT
unsafe fn get_dev_tools_protocol_event_receiver(
&self,
event_name: LPCWSTR,
receiver: *mut *mut *mut ICoreWebView2DevToolsProtocolEventReceiverVTable
) -> HRESULT
Get a DevTools Protocol event receiver that allows you to subscribe to a
DevTools Protocol event. The eventName
parameter is the full name of
the event in the format {domain}.{event}
. For more information about
DevTools Protocol events description and event args, navigate to
[DevTools Protocol Viewer][GithubChromedevtoolsDevtoolsProtocolTot].
\snippet ScriptComponent.cpp DevToolsProtocolEventReceived
[GithubChromedevtoolsDevtoolsProtocolTot]: https://chromedevtools.github.io/devtools-protocol/tot “latest (tip-of-tree) protocol - Chrome DevTools Protocol | GitHub”
Stop all navigations and pending resource fetches. Does not stop scripts.
unsafe fn add_new_window_requested(
&self,
event_handler: *mut *mut ICoreWebView2NewWindowRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_new_window_requested(
&self,
event_handler: *mut *mut ICoreWebView2NewWindowRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the NewWindowRequested
event.
NewWindowRequested
runs when content inside the WebView requests to
open a new window, such as through window.open
. The app passes a
target WebView that is considered the opened window.
If a deferral is not taken on the event args, scripts that resulted in the new window that are requested are blocked until the event handler returns. If a deferral is taken, then scripts are blocked until the deferral is completed or new window is set.
For more details and considerations on the target WebView to be supplied
at the opened window, see ICoreWebView2NewWindowRequestedEventArgs::put_NewWindow
.
\snippet AppWindow.cpp NewWindowRequested
unsafe fn remove_new_window_requested(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_new_window_requested(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with add_NewWindowRequested
.
unsafe fn add_document_title_changed(
&self,
event_handler: *mut *mut ICoreWebView2DocumentTitleChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_document_title_changed(
&self,
event_handler: *mut *mut ICoreWebView2DocumentTitleChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the DocumentTitleChanged
event.
DocumentTitleChanged
runs when the DocumentTitle
property of the
WebView changes and may run before or after the NavigationCompleted
event.
\snippet FileComponent.cpp DocumentTitleChanged
unsafe fn remove_document_title_changed(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_document_title_changed(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with add_DocumentTitleChanged
.
unsafe fn get_document_title(&self, title: *mut LPWSTR) -> HRESULT
unsafe fn get_document_title(&self, title: *mut LPWSTR) -> HRESULT
The title for the current top-level document. If the document has no explicit title or is otherwise empty, a default that may or may not match the URI of the document is used.
Add the provided host object to script running in the WebView with the
specified name. Host objects are exposed as host object proxies using
window.chrome.webview.hostObjects.{name}
. Host object proxies are
promises and resolves to an object representing the host object. The
promise is rejected if the app has not added an object with the name.
When JavaScript code access a property or method of the object, a promise
is return, which resolves to the value returned from the host for the
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, generic
IUnknown
, VT_DECIMAL
, or VT_RECORD
variant is not supported.
Remote JavaScript objects like callback functions are represented as an
VT_DISPATCH
VARIANT
with the object implementing IDispatch
. The
JavaScript callback method may be invoked using DISPID_VALUE
for the
DISPID
. Nested arrays are supported up to a depth of 3. Arrays of by
reference types are not supported. VT_EMPTY
and VT_NULL
are mapped
into JavaScript as null
. In JavaScript, null
and undefined are
mapped to VT_EMPTY
.
Additionally, all host objects are exposed as
window.chrome.webview.hostObjects.sync.{name}
. Here the host objects
are exposed as synchronous host object proxies. These are not promises
and function runtimes or property access synchronously block running
script waiting to communicate cross process for the host code to run.
Accordingly the result may have reliability issues and it is recommended
that you use the promise-based asynchronous
window.chrome.webview.hostObjects.{name}
API.
Synchronous host object proxies and asynchronous host object proxies may both use a proxy to the same host object. Remote changes made by one proxy propagates to any other proxy of that same host object whether the other proxies and synchronous or asynchronous.
While JavaScript is blocked on a synchronous run to native code, that
native code is unable to run back to JavaScript. Attempts to do so fail
with HRESULT_FROM_WIN32(ERROR_POSSIBLE_DEADLOCK)
.
Host object proxies are JavaScript Proxy objects that intercept all
property get, property set, and method invocations. Properties or methods
that are a part of the Function or Object prototype are run locally.
Additionally any property or method in the
chrome.webview.hostObjects.options.forceLocalProperties
array are also run locally. This defaults to including optional methods
that have meaning in JavaScript like toJSON
and Symbol.toPrimitive
.
Add more to the array as required.
The chrome.webview.hostObjects.cleanupSome
method performs a best
effort garbage collection on host object proxies.
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. |
getLocalProperty , setLocalProperty | Perform property get, or property set locally. Use the methods to force getting or setting a property on the host object proxy rather than on the host object it represents. For instance, proxy.unknownProperty gets the property named unknownProperty from the host proxied object. But proxy.getLocalProperty(‘unknownProperty’) gets the value of the property unknownProperty on the proxy object. |
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
object proxies return a promise representing asynchronous completion of
remotely invoking the method, or getting the property. The promise
resolves after the remote operations complete and the promises resolve to
the resulting value of the operation. Synchronous host object proxies
work similarly, but block running JavaScript and wait for the remote
operation to complete.
Setting a property on an asynchronous host object proxy works slightly
differently. The set returns immediately and the return value is the
value that is set. This is a requirement of the JavaScript Proxy object.
If you need to asynchronously wait for the property set to complete, use
the setHostProperty
method which returns a promise as described above.
Synchronous object property set property synchronously blocks until the
property is set.
For example, suppose you have a COM object with the following interface.
\snippet HostObjectSample.idl AddHostObjectInterface
Add an instance of this interface into your JavaScript with
AddHostObjectToScript
. In this case, name it sample
.
\snippet ScenarioAddHostObject.cpp AddHostObjectToScript
In the HTML document, use the COM object using
chrome.webview.hostObjects.sample
.
\snippet assets\ScenarioAddHostObject.html HostObjectUsage
Exposing host objects to script has security risk. For more information about best practices, navigate to [Best practices for developing secure WebView2 applications][MicrosoftEdgeWebview2ConceptsSecurity].
[MicrosoftEdgeWebview2ConceptsSecurity]: /microsoft-edge/webview2/concepts/security “Best practices for developing secure WebView2 applications | Microsoft Docs”
unsafe fn remove_host_object_from_script(&self, name: LPCWSTR) -> HRESULT
unsafe fn remove_host_object_from_script(&self, name: LPCWSTR) -> HRESULT
Remove the host object specified by the name so that it is no longer accessible from JavaScript code in the WebView. While new access attempts are denied, if the object is already obtained by JavaScript code in the WebView, the JavaScript code continues to have access to that object. Run this method for a name that is already removed or never added fails.
unsafe fn open_dev_tools_window(&self) -> HRESULT
unsafe fn open_dev_tools_window(&self) -> HRESULT
Opens the DevTools window for the current document in the WebView. Does nothing if run when the DevTools window is already open.
unsafe fn add_contains_full_screen_element_changed(
&self,
event_handler: *mut *mut ICoreWebView2ContainsFullScreenElementChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_contains_full_screen_element_changed(
&self,
event_handler: *mut *mut ICoreWebView2ContainsFullScreenElementChangedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the ContainsFullScreenElementChanged
event.
ContainsFullScreenElementChanged
triggers when the
ContainsFullScreenElement
property changes. An HTML element inside the
WebView may enter fullscreen to the size of the WebView or leave
fullscreen. This event is useful when, for example, a video element
requests to go fullscreen. The listener of
ContainsFullScreenElementChanged
may resize the WebView in response.
\snippet AppWindow.cpp ContainsFullScreenElementChanged
unsafe fn remove_contains_full_screen_element_changed(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_contains_full_screen_element_changed(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with
add_ContainsFullScreenElementChanged
.
unsafe fn get_contains_full_screen_element(
&self,
contains_full_screen_element: *mut BOOL
) -> HRESULT
unsafe fn get_contains_full_screen_element(
&self,
contains_full_screen_element: *mut BOOL
) -> HRESULT
Indicates if the WebView contains a fullscreen HTML element.
unsafe fn add_web_resource_requested(
&self,
event_handler: *mut *mut ICoreWebView2WebResourceRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_web_resource_requested(
&self,
event_handler: *mut *mut ICoreWebView2WebResourceRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the WebResourceRequested
event.
WebResourceRequested
runs when the WebView is performing a URL request
to a matching URL and resource context filter that was added with
AddWebResourceRequestedFilter
. At least one filter must be added for
the event to run.
The web resource requested may be blocked until the event handler returns if a deferral is not taken on the event args. If a deferral is taken, then the web resource requested is blocked until the deferral is completed.
If the method is run in add_NewWindowRequested handler it should be called
after the new window is set. For more details see ICoreWebView2NewWindowRequestedEventArgs::put_NewWindow
.
Currently this only supports file, http, and https URI schemes.
\snippet SettingsComponent.cpp WebResourceRequested0 \snippet SettingsComponent.cpp WebResourceRequested1
unsafe fn remove_web_resource_requested(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_web_resource_requested(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with add_WebResourceRequested
.
unsafe fn add_web_resource_requested_filter(
&self,
uri: LPCWSTR,
resource_context: WebResourceContext
) -> HRESULT
unsafe fn add_web_resource_requested_filter(
&self,
uri: LPCWSTR,
resource_context: WebResourceContext
) -> HRESULT
Adds a URI and resource context filter for the WebResourceRequested
event. A web resource request with a resource context that matches this
filter’s resource context and a URI that matches this filter’s URI
wildcard string will be raised via the WebResourceRequested
event.
The uri
parameter value is a wildcard string matched against the URI
of the web resource request. This is a glob style
wildcard string in which a *
matches zero or more characters and a ?
matches exactly one character.
These wildcard characters can be escaped using a backslash just before
the wildcard character in order to represent the literal *
or ?
.
The matching occurs over the URI as a whole string and not limiting wildcard matches to particular parts of the URI. The wildcard filter is compared to the URI after the URI has been normalized, any URI fragment has been removed, and non-ASCII hostnames have been converted to punycode.
Specifying a nullptr
for the uri is equivalent to an empty string which
matches no URIs.
For more information about resource context filters, navigate to [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 fitler 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 normalzied before filter matching so the actual URI used for comparison is https://example.com/ |
*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 |
unsafe fn remove_web_resource_requested_filter(
&self,
uri: LPCWSTR,
resource_context: WebResourceContext
) -> HRESULT
unsafe fn remove_web_resource_requested_filter(
&self,
uri: LPCWSTR,
resource_context: WebResourceContext
) -> HRESULT
Removes a matching WebResource filter that was previously added for the
WebResourceRequested
event. If the same filter was added multiple
times, then it must be removed as many times as it was added for the
removal to be effective. Returns E_INVALIDARG
for a filter that was
never added.
unsafe fn add_window_close_requested(
&self,
event_handler: *mut *mut ICoreWebView2WindowCloseRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
unsafe fn add_window_close_requested(
&self,
event_handler: *mut *mut ICoreWebView2WindowCloseRequestedEventHandlerVTable,
token: *mut EventRegistrationToken
) -> HRESULT
Add an event handler for the WindowCloseRequested
event.
WindowCloseRequested
triggers when content inside the WebView
requested to close the window, such as after window.close
is run. The
app should close the WebView and related app window if that makes sense
to the app.
\snippet AppWindow.cpp WindowCloseRequested
unsafe fn remove_window_close_requested(
&self,
token: EventRegistrationToken
) -> HRESULT
unsafe fn remove_window_close_requested(
&self,
token: EventRegistrationToken
) -> HRESULT
Remove an event handler previously added with add_WindowCloseRequested
.
Trait Implementations
type VTable = ICoreWebView2VTable
type VTable = ICoreWebView2VTable
A COM compatible V-Table
Check whether a given IID is in the inheritance hierarchy of this interface