diff --git a/microsoft-edge/dualengine/concepts/adapter-dll.md b/microsoft-edge/dualengine/concepts/adapter-dll.md new file mode 100644 index 0000000000..0f7f0f72eb --- /dev/null +++ b/microsoft-edge/dualengine/concepts/adapter-dll.md @@ -0,0 +1,83 @@ +--- +title: Creating a DualEngine adapter plugin DLL +description: Understanding the requirements and uses of the DualEngine Adapter DLL. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.localizationpriority: high +ms.date: 11/06/2023 +--- +# Creating a DualEngine adapter plugin DLL + +The DualEngine API can only be used from inside the Internet Explorer process. Therefore, to use the DualEngine API, you must create a plugin DLL that Internet Explorer loads. This DLL hosts your code that uses the DualEngine API, as well as any code that's needed for communicating with your main application; that's why it's referred to as the _adapter_. + +To have Internet Explorer successfully load your DLL, do the following. + + + +## Unlock the Limited Access Feature + +The DualEngine API is a Limited Access Feature (LAF); that is, a feature that needs to be unlocked before it can be used. For more information, see [LimitedAccessFeatures Class](/uwp/api/windows.applicationmodel.limitedaccessfeatures). + +The DualEngine API is not a typical LAF, in that `Windows.ApplicationModel.TryUnlockFeature` is not used to unlock the feature. This is because LAF typically uses the application identity of the calling process to grant access, and as a plugin DLL, this will always be Internet Explorer. Therefore, to unlock the API, you need to call [DualEngineSessionFactory::TryUnlockFeature](../reference/dualenginesessionfactory.md#tryunlockfeature). + +In addition, the identity of your application must be provided to Internet Explorer via a specific resource string that's set in your DLL. You can set the value in your resource file as follows: + +```cpp +IDENTITY LIMITEDACCESSFEATURE { L"ExampleApp_6v1kqc8g0gcae" } +``` + +Your specific identity string will be provided to you by Microsoft when LAF access is granted. + + + +## Implement function exports + +Your adapter DLL must implement the following function exports: +* `DualEngineInitialize` +* `DualEngineReady` + +These exports are called by Internet Explorer when loading your DLL. They provide you with the factory objects for creating DualEngine API objects. + +These exports are called from the main thread of the Internet Explorer process, so doing any long-term processing inside the exports will halt Internet Explorer. Therefore, to handle any long-running work, you should create a new thread. + + + +#### DualEngineInitialize + +```cpp +HRESULT APIENTRY DualEngineInitialize(DualEngineSessionFactory* pSessionFactory, PCWSTR pipeName) +``` + +###### Parameters + +* `pSessionFactory` The factory object to use to access the DualEngine API. +* `pipeName` A string that was passed in to Internet Explorer via the `-DualEnginePipe` command-line flag. + +This export is called immediately after Internet Explorer successfully loads the DLL. This is your first chance to set up anything necessary for your application. + +This is where you would typically set up communication between the adapter DLL and your host app. The `pipeName` string is provided for this purpose. Despite its name, the `pipeName` string doesn't need to be a pipe name; it's simply a string that's passed to your adapter based on the value of the `-DualEnginePipe` command-line flag that Internet Explorer was launched with, and has no other semantic meaning. + +Although the `pSessionFactory` object is provided in this call, it's not valid to call `GetVersionedBrowserSession` yet, because at this point, Internet Explorer isn't ready to create Sessions. + + + +#### DualEngineReady + +```cpp +HRESULT APIENTRY DualEngineReady() +``` + +This export is called after Internet Explorer has finished all of its initial setup and the API is ready to use. It's now possible to call `GetVersionedBrowserSession` and get the Session object, assuming a successful call to `TryUnlockFeature` has been made. + + + +## Bypass signing the adapter DLL + +Internet Explorer has a requirement that for an adapter DLL to be loaded, it must be signed with a trusted signature. For testing and development purposes, this check can be bypassed, by turning on `TestSigning` for the device that you're testing on, as follows: + +```cmd +Bcdedit.exe -set TESTSIGNING ON +``` diff --git a/microsoft-edge/dualengine/concepts/launching-internet-explorer.md b/microsoft-edge/dualengine/concepts/launching-internet-explorer.md new file mode 100644 index 0000000000..ecde45bacb --- /dev/null +++ b/microsoft-edge/dualengine/concepts/launching-internet-explorer.md @@ -0,0 +1,99 @@ +--- +title: Launching Internet Explorer +description: Launching Internet Explorer for DualEngine API Use +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.localizationpriority: high +ms.date: 11/06/2023 +--- +# Launching Internet Explorer + +After you've built your adapter DLL, you must launch Internet Explorer such that it is aware that it is being used for the DualEngine API, as follows. + + + +## Required command-line arguments + +The following command-line arguments must be present in order to launch Internet Explorer in the correct way to use the DualEngine API. + + + +#### DualEngineAdapter + +`-DualEngineAdapter=` + +Indicates the path to the DualEngine API adapter DLL to load. For information on how to write an adapter DLL, see [Creating a DualEngine adapter plugin DLL](adapter-dll.md). + + + +#### DualEnginePipe + +`-DualEnginePipe=` + +This argument provides a string that is eventually passed to the adapter DLL via the `DualEngineInitialize` export. This can be used to pass a pipe name to your adapter code in order to bootstrap communication between your adapter and main application. Although `DualEnginePipe` is a required command-line parameter, it's only used if it's passed to your code through `DualEngineInitialize`. Therefore, despite its name, this need not be a pipe name; it can be any arbitrary string that you require. + + + +#### APPID + +`APPID:` + +This argument provides the Application User Model ID of your application. This ID is used to associate the Internet Explorer process with your application, for a number of Windows Shell features. For more information, see [Application User Model IDs](/windows/win32/shell/appids). + + + +## Optional command-line arguments + +The following command-line argument is optional, to adjust Internet Explorer's behavior for the Dual Engine API. + + + +#### DualEngineVersion + +`-DualEngineVersion=` + +Forces Internet Explorer to instantiate DualEngine objects of the provided version, if it can. This will block the creation of DualEngine objects that don't match the provided version number, even if this version of Internet Explorer supports this version. + + + +## Diagnosing launch issues + +There are a number of reasons that Internet Explorer may fail when launching. If this occurs before or while loading your DLL, it can be difficult to determine the exact reason and communicate it back to your application. Therefore, if Internet Explorer fails to launch while launching it for DualEngine use, get detailed error handling information by checking the `StartupFailurePoint` registry value. + + + +#### StartupFailurePoint + +`HKCU\SOFTWARE\Microsoft\Internet Explorer\EdgeIntegration\StartupFailurePoint` + +Contains a DWORD that indicates the location of the failure in the DualEngine startup path. + +The DWORD maps to the following reasons: + +| DWORD | Reason | +|:-----:|-----------------------------------------------------------------------------------------------------| +| 0 | No failure. | +| 1 | Unused. | +| 2 | Unused. | +| 3 | The version specified by the `DualEngineVersion` argument was 0. | +| 4 | Failed to canonicalize the path passed in via `DualEngineAdapter`; see the `StartupFailureHresult`. | +| 5 | Unused. | +| 6 | Unused. | +| 7 | `LoadLibrary` failed for the provided adapter DLL; see the `StartupFailureHresult`. | +| 8 | Could not find `DualEngineInitialize` in the adapter DLL. | +| 9 | The call to `DualEngineInitialize` failed; see the `StartupFailureHresult`. | +| 10 | Failed to set the provided Application User Model ID; see the `StartupFailureHresult`. | +| 11 | DLL failed signature check. | +| 12 | Unused. | +| 13 | DLL did not have IDENTITY LIMITEDACCESSFEATURE resource. | + + + +#### StartupFailureHresult + +`HKCU\Software\Microsoft\Internet Explorer\EdgeIntegration\StartupFailureHresult` + +Contains a DWORD that's the failing HRESULT from the `StartupFailurePoint`, if there was a `StartupFailureHresult`. To see whether a given reason provides a `StartupFailureHresult`, see the above table. diff --git a/microsoft-edge/dualengine/get-started.md b/microsoft-edge/dualengine/get-started.md new file mode 100644 index 0000000000..46dda41ca5 --- /dev/null +++ b/microsoft-edge/dualengine/get-started.md @@ -0,0 +1,48 @@ +--- +title: Getting started with the DualEngine API +description: Get started using the Microsoft DualEngine API to embed and control an Internet Explorer instance within your app, to provide a browsing experience that's equivalent to a normal Internet Explorer tab, providing increased compatibility with legacy websites. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.localizationpriority: high +ms.date: 11/17/2023 +--- +# Getting started with the DualEngine API + +This article walks you through the steps to start using the DualEngine API. + + + +## Step 1: Get access to the DualEngine Limited Access Feature + +Access to the DualEngine API is controlled via a Limited Access Feature (LAF). To gain access to the feature, reach out to dualengineapiaccess@microsoft.com. + +The DualEngine LAF is handled somewhat atypically; for details, see [Unlock the Limited Access Feature](concepts/adapter-dll.md#unlock-the-limited-access-feature) in _Creating a DualEngine adapter plugin DLL_. + + + +## Step 2: Download the DualEngine API header + +The DualEngine API is a COM interface that's only officially supported via C++, and is not part of the normal Windows SDK. Therefore, you must [download the DualEngine API header dualengine.h](https://download.microsoft.com/download/c/5/0/c5035487-bd78-4fd0-9cc4-e1c5a3b654b7/dualengine.h), and then include it in your adapter DLL project. + + + +## Step 3: Making an adapter DLL + +The DualEngine API is accessed by providing a plugin DLL to Internet Explorer at launch. Internet Explorer loads the DLL on startup, calls some exports on the DLL, and provides you with the objects that you need in order to access the API. See [Creating a DualEngine adapter plugin DLL](concepts/adapter-dll.md). + + + +## Step 4: Launching Internet Explorer + +Finally, Internet Explorer must be launched and told where and how to load the adapter that you created. This can be done by launching Internet Explorer with the correct command-line arguments, as follows: + +``` +C:\Program Files\Internet Explorer\iexplore.exe -DualEngineAdapter=C:\temp\TestApp\TestAdapter.dll -DualEnginePipe=784 APPID:TESTAPP +``` + +For more information about these command-line arguments, see [Launching Internet Explorer](concepts/launching-internet-explorer.md). + +At this point, Internet Explorer is now running your adapter code, which can now access the DualEngine API. To see what functionality is available, explore [DualEngine Win32 C++ Reference](reference/index.md). diff --git a/microsoft-edge/dualengine/intro.md b/microsoft-edge/dualengine/intro.md new file mode 100644 index 0000000000..05cc2d2d2b --- /dev/null +++ b/microsoft-edge/dualengine/intro.md @@ -0,0 +1,42 @@ +--- +title: Introduction to the Microsoft DualEngine API +description: Host web content in your Win32 apps with the Microsoft DualEngine interface. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.localizationpriority: high +ms.date: 11/06/2023 +--- +# Introduction to the Microsoft DualEngine API + +Use the Microsoft DualEngine API to embed and control an Internet Explorer instance within your app. The DualEngine API provides a browsing experience that's equivalent to a normal Internet Explorer tab, to provide increased compatibility with legacy websites. + +The DualEngine API differs from similar APIs like the Web Browser Control, and requires distinct development work. + +See also: +* [Getting started with the DualEngine API](./get-started.md) + + + +## Supported platforms + +The following programming environments are supported: + +* Win32 C/C++ + +DualEngine APIs can be used on the following versions of Windows: + +* Windows 11 +* Windows 10 +* Windows Server 2022 + + + +## See also + +* [Getting started with the DualEngine API](./get-started.md) +* [Creating a DualEngine adapter plugin DLL](concepts/adapter-dll.md) +* [Launching Internet Explorer](concepts/launching-internet-explorer.md) +* [DualEngine Win32 C++ Reference](reference/index.md) diff --git a/microsoft-edge/dualengine/reference/accelerator.md b/microsoft-edge/dualengine/reference/accelerator.md new file mode 100644 index 0000000000..23340b561a --- /dev/null +++ b/microsoft-edge/dualengine/reference/accelerator.md @@ -0,0 +1,58 @@ +--- +title: DualEngine Win32 C++ ACCELERATOR +description: Represents a keyboard accelerator (keyboard shortcut). +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/09/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, ACCELERATOR +topic_type: +- APIRef +api_name: +- ACCELERATOR +- ACCELERATOR.eventType +- ACCELERATOR.flags +- ACCELERATOR.keyCode +api_type: +- COM +api_location: +- ieframe.dll +--- + +# struct ACCELERATOR + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +Represents a keyboard accelerator (keyboard shortcut). + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[eventType](#eventtype) | The type of keyboard event that the accelerator is processed on. +[flags](#flags) | The modifier keys present in the accelerator keystroke. +[keyCode](#keycode) | The virtual-key code of the keystroke. + +## Members + +#### eventType + +The type of keyboard event that the accelerator is processed on. + +> public ACCELERATOREVENTTYPE [eventType](#eventtype) + +#### flags + +The modifier keys present in the accelerator keystroke. + +> public ACCELERATORFLAGS [flags](#flags) + +#### keyCode + +The virtual-key code of the keystroke. + +> public DWORD [keyCode](#keycode) + diff --git a/microsoft-edge/dualengine/reference/cryptdatablob.md b/microsoft-edge/dualengine/reference/cryptdatablob.md new file mode 100644 index 0000000000..ddbe19c742 --- /dev/null +++ b/microsoft-edge/dualengine/reference/cryptdatablob.md @@ -0,0 +1,50 @@ +--- +title: DualEngine Win32 C++ CryptDataBlob +description: Represents an SSL Certificate. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/09/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, CryptDataBlob +topic_type: +- APIRef +api_name: +- CryptDataBlob +- CryptDataBlob.cbData +- CryptDataBlob.pbData +api_type: +- COM +api_location: +- ieframe.dll +--- + +# struct CryptDataBlob + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +Represents an SSL Certificate. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[cbData](#cbdata) | The number of bytes in `pbData`. +[pbData](#pbdata) | A buffer containing a DER-encoded X.509 certificate string. + +## Members + +#### cbData + +The number of bytes in `pbData`. + +> public DWORD [cbData](#cbdata) + +#### pbData + +A buffer containing a DER-encoded X.509 certificate string. + +> public BYTE * [pbData](#pbdata) + diff --git a/microsoft-edge/dualengine/reference/dualengine-idl.md b/microsoft-edge/dualengine/reference/dualengine-idl.md new file mode 100644 index 0000000000..6b1ff3417e --- /dev/null +++ b/microsoft-edge/dualengine/reference/dualengine-idl.md @@ -0,0 +1,371 @@ +--- +title: Globals +description: DualEngine Win32 Globals +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/09/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html +topic_type: +- APIRef +api_name: +- DualEngineInitialize +- DualEngineReady +api_type: +- DllExport +api_loction: +- ieframe.dll +--- + +# Globals + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[ACCELERATOREVENTTYPE](#acceleratoreventtype) | Specifies the type of accelerator event. +[ACCELERATORFLAGS](#acceleratorflags) | Specifies the virtual key modifiers present in the accelerator keystroke. +[ATTENTIONSTATE](#attentionstate) | Represents the reason attention is being requested. +[BROWSERVISIBILITY](#browservisibility) | Represents a browser visibility state. +[CERTERRORFLAG](#certerrorflag) | Represents a certificate error. +[DUALENGINE_FOCUSDIRECTION](#dualengine_focusdirection) | Represents the direction of a focus change. +[DualEngineConfigurableSitesFlags](#dualengineconfigurablesitesflags) | Flags to control special engine switching headers and behaviors for configurable sites. +[DUALENGINECONFIGURATION](#dualengineconfiguration) | Configuration options to define desired behavior for the hosted browser window. +[DualEngineCookieIntegrity](#dualenginecookieintegrity) | Represents the Process Integrity Context Level of a cookie. +[DualEngineWindowOpenDisposition](#dualenginewindowopendisposition) | Represents the disposition of a new window. +[EngineSwitchingPolicyFlags](#engineswitchingpolicyflags) | Represents the engine switching policy This policy along with the site list determines when navigations are handled by the browser and when they are sent to the host to handle. +[EXIT_REGION_TYPE](#exit_region_type) | Represents the reason a region exit is occurring. +[FULLSCREENACTION](#fullscreenaction) | Represents a change in full screen state. +[KEYACTION](#keyaction) | Represents a type of key event. +[MOUSEACTION](#mouseaction) | Represents a type of mouse event. +[NAVIGATION_COMMAND](#navigation_command) | Represents a type of Navigation command. +[NAVIGATIONFAILEDREASON](#navigationfailedreason) | Represents a reason that a navigation failed. +[NAVIGATIONFLAGS](#navigationflags) | Flags that indicate the type of navigation that occurred. +[SECURELOCKICON](#securelockicon) | Represents the current page content's security state. +[SITE_PERMISSION_FEATURE_MODE](#site_permission_feature_mode) | Represents the state of a site permission request. +[SITE_PERMISSION_KIND](#site_permission_kind) | Represents the type of site permission being requested. +[SITE_PERMISSION_RESPONSE](#site_permission_response) | Represents a user's response to a site permission request. +[VisibleEntryUpdateOperation](#visibleentryupdateoperation) | Indicates the type of operation of the [VisibleListUpdateEntry](visiblelistupdateentry.md). +[DualEngineInitialize](#dualengineinitialize) | Initializes the DualEngine. +[DualEngineReady](#dualengineready) | Called after Internet Explorer has finished all of its initial setup and the API is ready to use. + +## Members + +#### ACCELERATOREVENTTYPE + +Specifies the type of accelerator event. + +> enum [ACCELERATOREVENTTYPE](#acceleratoreventtype) + + Values | Descriptions +--------------------------------|--------------------------------------------- +ACCELERATOREVENTTYPE_KEYDOWN | The keydown event. +ACCELERATOREVENTTYPE_CHAR | The char event. +ACCELERATOREVENTTYPE_KEYUP | The key up event. + +#### ACCELERATORFLAGS + +Specifies the virtual key modifiers present in the accelerator keystroke. + +> enum [ACCELERATORFLAGS](#acceleratorflags) + + Values | Descriptions +--------------------------------|--------------------------------------------- +ACCELERATORFLAGS_NONE | No virtual key modifier. +ACCELERATORFLAGS_CTRL | The Ctrl virtual key. +ACCELERATORFLAGS_ALT | The Alt virtual key. +ACCELERATORFLAGS_SHIFT | The Shift virtual key. + +#### ATTENTIONSTATE + +Represents the reason attention is being requested. + +> enum [ATTENTIONSTATE](#attentionstate) + + Values | Descriptions +--------------------------------|--------------------------------------------- +ATTENTIONSTATE_DIALOG | Attention is being requested because of a modal dialog. +ATTENTIONSTATE_FRAMETARGET | Attention is being requested because the browser was navigated by frame targeting. + +#### BROWSERVISIBILITY + +Represents a browser visibility state. + +> enum [BROWSERVISIBILITY](#browservisibility) + + Values | Descriptions +--------------------------------|--------------------------------------------- +VISIBILITY_INACTIVE | The Browser is inactive. +VISIBILITY_MINIMIZED | The Browser is minimized. +VISIBILITY_VISIBLE | The Browser is visible. + +#### CERTERRORFLAG + +Represents a certificate error. + +> enum [CERTERRORFLAG](#certerrorflag) + + Values | Descriptions +--------------------------------|--------------------------------------------- +CERTERRORFLAG_NONE | No certificate error. +CERTERRORFLAG_INVALID_CA | Certificate authority is invalid. +CERTERRORFLAG_SEC_CERT_CN_INVALID | Common name does not match the URL of the page. +CERTERRORFLAG_SEC_CERT_DATE_INVALID | Date is invalid. +CERTERRORFLAG_WEAK_SIGNATURE | Signed by a weak digital signature. +CERTERRORFLAG_INSECURE_FALLBACK | The connection has been downgraded to a less secure protocol. +CERTERRORFLAG_SEC_CERT_REV_FAILED | The revocation check for the certificate has failed. + +#### DUALENGINE_FOCUSDIRECTION + +Represents the direction of a focus change. + +> enum [DUALENGINE_FOCUSDIRECTION](#dualengine_focusdirection) + + Values | Descriptions +--------------------------------|--------------------------------------------- +FOCUSDIRECTION_NONE | The constant for specifying no focus direction. +FOCUSDIRECTION_FORWARD | The constant for specifying the forward focus direction. +FOCUSDIRECTION_BACKWARD | The constant for specifying the back focus direction. + +#### DualEngineConfigurableSitesFlags + +Flags to control special engine switching headers and behaviors for configurable sites. + +> enum [DualEngineConfigurableSitesFlags](#dualengineconfigurablesitesflags) + + Values | Descriptions +--------------------------------|--------------------------------------------- +DualEngineConfigurableSitesFlags_Disabled | Disables the configurable sites feature. +DualEngineConfigurableSitesFlags_EnableConfigurableSuccessResponse | Allow configurable site switching on a successful navigation. +DualEngineConfigurableSitesFlags_EnableConfigurableRedirectResponse | Allow configurable site switching on a redirected navigation. +DualEngineConfigurableSitesFlags_IntranetIsConfigurable | Treat all Intranet sites as configurable by default. +DualEngineConfigurableSitesFlags_AllowConfigurableRedirectToImplicitNeutral | Allow configurable site switching when redirecting to neutral sites regardless of site list if the navigation is sticky. + +#### DUALENGINECONFIGURATION + +Configuration options to define desired behavior for the hosted browser window. + +> enum [DUALENGINECONFIGURATION](#dualengineconfiguration) + + Values | Descriptions +--------------------------------|--------------------------------------------- +DUALENGINECONFIGURATION_NORMAL | The default behavior of a hosted browser. +DUALENGINECONFIGURATION_DISABLE_ENGINE_SWITCHING | Disables the engine switching behavior. +DUALENGINECONFIGURATION_POPUP_WINDOW | Indicates that the hosted window should be treated as a pop-up window. +DUALENGINECONFIGURATION_HYBRID_ENTERPRISE_MODE | Indicates that the browser is running in Hybrid Enterprise mode. +DUALENGINECONFIGURATION_ALWAYS_WAIT_FOR_UNLOAD | Indicates that the browser should defer signaling that it closed until it is about to unload. + +#### DualEngineCookieIntegrity + +Represents the Process Integrity Context Level of a cookie. + +> enum [DualEngineCookieIntegrity](#dualenginecookieintegrity) + + Values | Descriptions +--------------------------------|--------------------------------------------- +DualEngineCookieIntegrity_Auto | Automatically determine integrity level based on the cookie's domain. +DualEngineCookieIntegrity_Low | Cookie is Low IL. +DualEngineCookieIntegrity_Medium | Cookie is Medium IL. +DualEngineCookieIntegrity_Both | Cookie is both Medium and Low IL. + +#### DualEngineWindowOpenDisposition + +Represents the disposition of a new window. + +> enum [DualEngineWindowOpenDisposition](#dualenginewindowopendisposition) + + Values | Descriptions +--------------------------------|--------------------------------------------- +DualEngineWindowOpenDisposition_NewForegroundTab | Window is a new foreground tab. +DualEngineWindowOpenDisposition_NewBackgroundTab | Window is a new background tab. +DualEngineWindowOpenDisposition_NewPopup | Window is a new popup window. +DualEngineWindowOpenDisposition_NewWindow | Window is a new window. + +#### EngineSwitchingPolicyFlags + +Represents the engine switching policy This policy along with the site list determines when navigations are handled by the browser and when they are sent to the host to handle. + +> enum [EngineSwitchingPolicyFlags](#engineswitchingpolicyflags) + + Values | Descriptions +--------------------------------|--------------------------------------------- +EngineSwitchingPolicyFlags_None | Default Edge Switching Policy. +EngineSwitchingPolicyFlags_ServerRedirectsSticky | Server redirects to sites not in the site list stay in the browser. +EngineSwitchingPolicyFlags_ClientRedirectsSticky | Client redirects to sites not in the site list stay in the browser. +EngineSwitchingPolicyFlags_FormSubmitsSticky | Form submissions to sites not in the site list stay in the browser. +EngineSwitchingPolicyFlags_UserInitiatedHyperlinkClicksSticky | User initiated hyperlink navigations to sites not in the site list stay in the browser. +EngineSwitchingPolicyFlags_OtherNavigationsSticky | All other types of navigation to sites not in the site list stay in the browser. +EngineSwitchingPolicyFlags_RespectAllowRedirectAttribute | Whether the navigation stays in the browser is respective of the site list entry's `allow-redirect` attribute. +EngineSwitchingPolicyFlags_Max | For internal use only; do not use. +EngineSwitchingPolicyFlags_Mask | For internal use only; do not use. + +#### EXIT_REGION_TYPE + +Represents the reason a region exit is occurring. + +> enum [EXIT_REGION_TYPE](#exit_region_type) + + Values | Descriptions +--------------------------------|--------------------------------------------- +EXIT_REGION_TYPE_NONE | For internal use only; do not use. +EXIT_REGION_TYPE_FOR_CLOSE | The region is exiting due to the browser closing. +EXIT_REGION_TYPE_FOR_HISTORY_NAVIGATION | The region is exiting due to a history navigation. +EXIT_REGION_TYPE_FOR_NEW_NAVIGATION | The region is exiting due to a new navigation. + +#### FULLSCREENACTION + +Represents a change in full screen state. + +> enum [FULLSCREENACTION](#fullscreenaction) + + Values | Descriptions +--------------------------------|--------------------------------------------- +ENTER_FULLSCREEN | Represents media entering full screen. +EXIT_FULLSCREEN | Represents media exiting full screen. +ENTER_THEATER_FULLSCREEN | Represents entering theater mode full screen. +EXIT_THEATER_FULLSCREEN | Represents exiting theater mode full screen. + +#### KEYACTION + +Represents a type of key event. + +> enum [KEYACTION](#keyaction) + + Values | Descriptions +--------------------------------|--------------------------------------------- +KEYACTION_NONE | The constant for specifying no key event. +KEYACTION_DOWN | The constant for specifying a key down event. +KEYACTION_UP | The constant for specifying a key up event. + +#### MOUSEACTION + +Represents a type of mouse event. + +> enum [MOUSEACTION](#mouseaction) + + Values | Descriptions +--------------------------------|--------------------------------------------- +MOUSEACTION_NONE | The constant for specifying no mouse event. +MOUSEACTION_LEFT_CLICK | The constant for specifying a left click mouse event. + +#### NAVIGATION_COMMAND + +Represents a type of Navigation command. + +> enum [NAVIGATION_COMMAND](#navigation_command) + + Values | Descriptions +--------------------------------|--------------------------------------------- +NAVIGATION_COMMAND_NONE | The constant for specifying no navigation command. +NAVIGATION_COMMAND_GO_BACK | The constant for specifying a go back navigation command. +NAVIGATION_COMMAND_GO_FORWARD | The constant for specifying a go forward navigation command. +NAVIGATION_COMMAND_RELOAD | The constant for specifying a reload navigation command, may use a copy of the page that has been cached. +NAVIGATION_COMMAND_RELOAD_COMPLETELY | The constant for specifying a reload navigation command, requests the latest version of the current page. +NAVIGATION_COMMAND_STOP | The constant for specifying a stop navigation command. + +#### NAVIGATIONFAILEDREASON + +Represents a reason that a navigation failed. + +> enum [NAVIGATIONFAILEDREASON](#navigationfailedreason) + + Values | Descriptions +--------------------------------|--------------------------------------------- +NAVIGATIONFAILEDREASON_DEFAULT | Navigation was aborted, may not necessarily be for a failure. +NAVIGATIONFAILEDREASON_BAD_NETPATH | Navigation failed because the path could not be found. +NAVIGATIONFAILEDREASON_FAILED | Navigation failed for some other unspecified reason. + +#### NAVIGATIONFLAGS + +Flags that indicate the type of navigation that occurred. + +> enum [NAVIGATIONFLAGS](#navigationflags) + + Values | Descriptions +--------------------------------|--------------------------------------------- +NAVIGATIONFLAGS_NONE | +NAVIGATIONFLAGS_MAINFRAME | Indicates that the top level page navigated, e.g. +NAVIGATIONFLAGS_SAMEDOCUMENT | Indicates that the navigation is within the same document, e.g. local anchor navigations. +NAVIGATIONFLAGS_NEWPAGE | Indicates that the navigation was to a new page, e.g. +NAVIGATIONFLAGS_LOCATIONREPLACE | Indicates that the current page navigated because of location.replace. +NAVIGATIONFLAGS_ERRORPAGE | Indicates that the page navigated to was an internal error page. + +#### SECURELOCKICON + +Represents the current page content's security state. + +> enum [SECURELOCKICON](#securelockicon) + + Values | Descriptions +--------------------------------|--------------------------------------------- +SECURELOCKICON_UNSECURE | The current page is not secure. +SECURELOCKICON_MIXED | The current page is displaying mixed content. +SECURELOCKICON_SECURE | The current page is secure. + +#### SITE_PERMISSION_FEATURE_MODE + +Represents the state of a site permission request. + +> enum [SITE_PERMISSION_FEATURE_MODE](#site_permission_feature_mode) + + Values | Descriptions +--------------------------------|--------------------------------------------- +SITE_PERMISSION_FEATURE_MODE_BLOCKED | Access to the feature was blocked. +SITE_PERMISSION_FEATURE_MODE_ALLOWED | Access to the feature was allowed. + +#### SITE_PERMISSION_KIND + +Represents the type of site permission being requested. + +> enum [SITE_PERMISSION_KIND](#site_permission_kind) + + Values | Descriptions +--------------------------------|--------------------------------------------- +SITE_PERMISSION_KIND_POPUP_BLOCKER | Requesting to set popup blocker permissions. +SITE_PERMISSION_KIND_GEOLOCATION | Requesting to set geolocation permissions. + +#### SITE_PERMISSION_RESPONSE + +Represents a user's response to a site permission request. + +> enum [SITE_PERMISSION_RESPONSE](#site_permission_response) + + Values | Descriptions +--------------------------------|--------------------------------------------- +SITE_PERMISSION_REQUEST_DENIED | Request for the permission was denied. +SITE_PERMISSION_REQUEST_ALLOWED | Request for the permission was granted. +SITE_PERMISSION_REQUEST_DISMISSED | Request for the permission was dismissed without a response. + +#### VisibleEntryUpdateOperation + +Indicates the type of operation of the [VisibleListUpdateEntry](visiblelistupdateentry.md). + +> enum [VisibleEntryUpdateOperation](#visibleentryupdateoperation) + + Values | Descriptions +--------------------------------|--------------------------------------------- +VisibleEntry_Add | The entry is an addition. +VisibleEntry_Delete | The entry has been deleted. +VisibleEntry_Update | The entry has been updated. +VisibleEntry_Done | For internal use only; do not use. + +#### DualEngineInitialize + +Initializes the DualEngine. + +> public HRESULT APIENTRY [DualEngineInitialize](#dualengineinitialize)(const [DualEngineSessionFactory](dualenginesessionfactory.md) * pSessionFactory, PCWSTR pipeName) + +A function that you export. This function is called immediately after Internet Explorer successfully loads the DLL. This is your first chance to set up anything necessary for your application. See [DualEngineInitialize](../concepts/adapter-dll.md#dualengineinitialize) in _Creating a DualEngine adapter plugin DLL_. +#### DualEngineReady + +Called after Internet Explorer has finished all of its initial setup and the API is ready to use. + +> public HRESULT APIENTRY [DualEngineReady](#dualengineready)() + +A function that you export. At this point, it's now possible to call `GetVersionedBrowserSession` and get the Session object, assuming a successful call to `TryUnlockFeature` has been made. See [DualEngineReady](../concepts/adapter-dll.md#dualengineready) in _Creating a DualEngine adapter plugin DLL_. + diff --git a/microsoft-edge/dualengine/reference/dualenginecookie.md b/microsoft-edge/dualengine/reference/dualenginecookie.md new file mode 100644 index 0000000000..ae64bb1210 --- /dev/null +++ b/microsoft-edge/dualengine/reference/dualenginecookie.md @@ -0,0 +1,104 @@ +--- +title: DualEngine Win32 C++ DualEngineCookie +description: Represents the constituent parts of a cookie. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/09/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, DualEngineCookie +topic_type: +- APIRef +api_name: +- DualEngineCookie +- DualEngineCookie.domain +- DualEngineCookie.expiry +- DualEngineCookie.flags +- DualEngineCookie.forceSync +- DualEngineCookie.integrity +- DualEngineCookie.name +- DualEngineCookie.path +- DualEngineCookie.value +api_type: +- COM +api_location: +- ieframe.dll +--- + +# struct DualEngineCookie + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +Represents the constituent parts of a cookie. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[domain](#domain) | The cookie domain. +[expiry](#expiry) | Expiry time for persistent cookies. +[flags](#flags) | Flags for additional cookie details. +[forceSync](#forcesync) | Indicates that when setting the cookie whether to wait for a process of the appropriate integrity level to be created and ready to receive the cookie before returning. +[integrity](#integrity) | The Integrity Level of the cookie. +[name](#name) | The name of the cookie. +[path](#path) | The cookie path. May be NULL. +[value](#value) | The cookie value. + +## Members + +#### domain + +The cookie domain. + +> public LPCWSTR [domain](#domain) + +#### expiry + +Expiry time for persistent cookies. + +> public FILETIME [expiry](#expiry) + +Should only be used if INTERNET_COOKIE_IS_SESSION is *not* set in flags, or if this is a delete (an expiry set to a past date). + +#### flags + +Flags for additional cookie details. + +> public DWORD [flags](#flags) + +See [INTERNET_COOKIE2](/windows/win32/api/wininet/ns-wininet-internet_cookie2) for available flags. + +#### forceSync + +Indicates that when setting the cookie whether to wait for a process of the appropriate integrity level to be created and ready to receive the cookie before returning. + +> public BOOL [forceSync](#forcesync) + +This only affects persistent cookies when protected mode is enabled. + +#### integrity + +The Integrity Level of the cookie. + +> public DualEngineCookieIntegrity [integrity](#integrity) + +#### name + +The name of the cookie. + +> public LPCWSTR [name](#name) + +#### path + +The cookie path. May be NULL. + +> public LPCWSTR [path](#path) + +#### value + +The cookie value. + +> public LPCWSTR [value](#value) + diff --git a/microsoft-edge/dualengine/reference/dualenginenewwindowoptions.md b/microsoft-edge/dualengine/reference/dualenginenewwindowoptions.md new file mode 100644 index 0000000000..01a7b24b79 --- /dev/null +++ b/microsoft-edge/dualengine/reference/dualenginenewwindowoptions.md @@ -0,0 +1,138 @@ +--- +title: DualEngine Win32 C++ DualEngineNewWindowOptions +description: Represents the requested state of a new window. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/09/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, DualEngineNewWindowOptions +topic_type: +- APIRef +api_name: +- DualEngineNewWindowOptions +- DualEngineNewWindowOptions.disposition +- DualEngineNewWindowOptions.height +- DualEngineNewWindowOptions.heightSpecified +- DualEngineNewWindowOptions.left +- DualEngineNewWindowOptions.leftSpecified +- DualEngineNewWindowOptions.menuBarVisible +- DualEngineNewWindowOptions.scrollbarsVisible +- DualEngineNewWindowOptions.statusBarVisible +- DualEngineNewWindowOptions.toolbarVisible +- DualEngineNewWindowOptions.top +- DualEngineNewWindowOptions.topSpecified +- DualEngineNewWindowOptions.width +- DualEngineNewWindowOptions.widthSpecified +api_type: +- COM +api_location: +- ieframe.dll +--- + +# struct DualEngineNewWindowOptions + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +Represents the requested state of a new window. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[disposition](#disposition) | Type of tab or window that the host should create to host the window. +[height](#height) | Specifies the requested height of the window. +[heightSpecified](#heightspecified) | Indicates whether a `DualEngineNewWindowOptions.height` value was specified. +[left](#left) | Specifies the requested x-coordinate of the upper-left corner of the window. +[leftSpecified](#leftspecified) | Indicates whether a `DualEngineNewWindowOptions.left` value was specified. +[menuBarVisible](#menubarvisible) | Indicates whether the window should should have a visible menu bar. +[scrollbarsVisible](#scrollbarsvisible) | Indicates whether the window should should have visible scroll bars. +[statusBarVisible](#statusbarvisible) | Indicates whether the window should should have a visible status bar. +[toolbarVisible](#toolbarvisible) | Indicates whether the window should should have a visible toolbar. +[top](#top) | Specifies the requested y-coordinate of the upper-left corner of the window. +[topSpecified](#topspecified) | Indicates whether a `DualEngineNewWindowOptions.top` value was specified. +[width](#width) | Specifies the requested width of the window. +[widthSpecified](#widthspecified) | Indicates whether a `DualEngineNewWindowOptions.width` value was specified. + +## Members + +#### disposition + +Type of tab or window that the host should create to host the window. + +> public DualEngineWindowOpenDisposition [disposition](#disposition) + +#### height + +Specifies the requested height of the window. + +> public FLOAT [height](#height) + +#### heightSpecified + +Indicates whether a `DualEngineNewWindowOptions.height` value was specified. + +> public BOOL [heightSpecified](#heightspecified) + +#### left + +Specifies the requested x-coordinate of the upper-left corner of the window. + +> public FLOAT [left](#left) + +#### leftSpecified + +Indicates whether a `DualEngineNewWindowOptions.left` value was specified. + +> public BOOL [leftSpecified](#leftspecified) + +#### menuBarVisible + +Indicates whether the window should should have a visible menu bar. + +> public BOOL [menuBarVisible](#menubarvisible) + +#### scrollbarsVisible + +Indicates whether the window should should have visible scroll bars. + +> public BOOL [scrollbarsVisible](#scrollbarsvisible) + +#### statusBarVisible + +Indicates whether the window should should have a visible status bar. + +> public BOOL [statusBarVisible](#statusbarvisible) + +#### toolbarVisible + +Indicates whether the window should should have a visible toolbar. + +> public BOOL [toolbarVisible](#toolbarvisible) + +#### top + +Specifies the requested y-coordinate of the upper-left corner of the window. + +> public FLOAT [top](#top) + +#### topSpecified + +Indicates whether a `DualEngineNewWindowOptions.top` value was specified. + +> public BOOL [topSpecified](#topspecified) + +#### width + +Specifies the requested width of the window. + +> public FLOAT [width](#width) + +#### widthSpecified + +Indicates whether a `DualEngineNewWindowOptions.width` value was specified. + +> public BOOL [widthSpecified](#widthspecified) + diff --git a/microsoft-edge/dualengine/reference/dualenginesessionfactory.md b/microsoft-edge/dualengine/reference/dualenginesessionfactory.md new file mode 100644 index 0000000000..f72cd50ad2 --- /dev/null +++ b/microsoft-edge/dualengine/reference/dualenginesessionfactory.md @@ -0,0 +1,83 @@ +--- +title: DualEngine Win32 C++ DualEngineSessionFactory +description: Factory object for DualEngine interfaces. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/27/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, DualEngineSessionFactory +topic_type: +- APIRef +api_name: +- DualEngineSessionFactory +- DualEngineSessionFactory.GetSpecifiedVersion +- DualEngineSessionFactory.GetVersionedBrowserSession +- DualEngineSessionFactory.TryUnlockFeature +api_type: +- COM +api_location: +- ieframe.dll +--- + +# interface DualEngineSessionFactory + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +Factory object for DualEngine interfaces. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[GetSpecifiedVersion](#getspecifiedversion) | Returns the known DualEngine interface version, if there is one. +[GetVersionedBrowserSession](#getversionedbrowsersession) | Gets a DualEngine Session object of the requested version. +[TryUnlockFeature](#tryunlockfeature) | Called to unlock the DualEngine interface. + +## Members + +#### GetSpecifiedVersion + +Returns the known DualEngine interface version, if there is one. + +> public STDMETHOD([GetSpecifiedVersion](#getspecifiedversion))(__out UINT * version) const + +###### Parameters +* `version` A pointer to a UINT where the version will be stored if there is one. + +###### Returns +S_OK if a known version was found, E_FAIL if it was not. + +#### GetVersionedBrowserSession + +Gets a DualEngine Session object of the requested version. + +> public STDMETHOD([GetVersionedBrowserSession](#getversionedbrowsersession))(__in UINT version, __out IUnknown ** ppSession) + +> [!IMPORTANT] +> This method must be called after Internet Explorer calls the export on DualEngineReady. See [Creating a DualEngine adapter plugin DLL](../concepts/adapter-dll.md). +###### Parameters +* `version` The version of the Session object to get. + +* `ppSession` The Session object, if the version requested is supported. + +###### Returns +An HRESULT that indicates whether session creation was successful. + +#### TryUnlockFeature + +Called to unlock the DualEngine interface. + +> public STDMETHOD([TryUnlockFeature](#tryunlockfeature))(PCWSTR token, PCWSTR attestation) + +> [!IMPORTANT] +> This MUST be called successfully before any other methods on this interface can be called. Equivalent to `Windows::ApplicationModel::LimitedAccessFeatures::TryUnlockFeature` except it checks the adapter dll for the identity resource instead of the process .exe. +###### Parameters +* `token` The LAF token provided by Microsoft. + +* `attestation` The attestation string provided by Microsoft. + +###### Returns +An HRESULT that indicates whether unlocking was successful. diff --git a/microsoft-edge/dualengine/reference/idualengine20browser.md b/microsoft-edge/dualengine/reference/idualengine20browser.md new file mode 100644 index 0000000000..10ef062376 --- /dev/null +++ b/microsoft-edge/dualengine/reference/idualengine20browser.md @@ -0,0 +1,495 @@ +--- +title: DualEngine Win32 C++ IDualEngine20Browser +description: Represents an Internet Explorer tab. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/27/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, IDualEngine20Browser +topic_type: +- APIRef +api_name: +- IDualEngine20Browser +- IDualEngine20Browser.DualEngineBrowserCommitted +- IDualEngine20Browser.DualEngineClose +- IDualEngine20Browser.DualEngineDeleteTabRecoveryData +- IDualEngine20Browser.DualEngineDoOnBeforeUnloadAndStop +- IDualEngine20Browser.DualEngineDPIChanged +- IDualEngine20Browser.DualEngineEnableCaretMode +- IDualEngine20Browser.DualEngineExecNavigationCommand +- IDualEngine20Browser.DualEngineFindOnPage +- IDualEngine20Browser.DualEngineForceClose +- IDualEngine20Browser.DualEngineGeolocationPermissionResponse +- IDualEngine20Browser.DualEngineGoToEntry +- IDualEngine20Browser.DualEngineInitialize +- IDualEngine20Browser.DualEngineInitialize2 +- IDualEngine20Browser.DualEngineInitializeWithRecoveryData +- IDualEngine20Browser.DualEngineLostFocus +- IDualEngine20Browser.DualEngineNavigate +- IDualEngine20Browser.DualEngineNavigate2 +- IDualEngine20Browser.DualEngineNotifyNavigationEntriesDeleted +- IDualEngine20Browser.DualEnginePrepareToExitRegion +- IDualEngine20Browser.DualEnginePrint +- IDualEngine20Browser.DualEngineProtectFocus +- IDualEngine20Browser.DualEngineSavePageAs +- IDualEngine20Browser.DualEngineSetEngineSwitchingPolicyFlags +- IDualEngine20Browser.DualEngineSetFocus +- IDualEngine20Browser.DualEngineSetMediaFullscreen +- IDualEngine20Browser.DualEngineSetPosition +- IDualEngine20Browser.DualEngineSetTheaterFullscreen +- IDualEngine20Browser.DualEngineSetTheaterMargins +- IDualEngine20Browser.DualEngineSetVisible +- IDualEngine20Browser.DualEngineSetWindowStyle +- IDualEngine20Browser.DualEngineSetZoom +- IDualEngine20Browser.DualEngineSimulateKeyInput +- IDualEngine20Browser.DualEngineSimulateMouseInput +- IDualEngine20Browser.DualEngineStopFindOnPage +- IDualEngine20Browser.DualEngineTranslateAccelerator +api_type: +- COM +api_location: +- ieframe.dll +--- + +# interface IDualEngine20Browser + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +```cpp +interface IDualEngine20Browser + : public IUnknown +``` + +Represents an Internet Explorer tab. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[DualEngineBrowserCommitted](#dualenginebrowsercommitted) | Notifies the browser that it has been committed and is no longer speculative. +[DualEngineClose](#dualengineclose) | Closes the browser instance. +[DualEngineDeleteTabRecoveryData](#dualenginedeletetabrecoverydata) | Deletes tab recovery data. +[DualEngineDoOnBeforeUnloadAndStop](#dualenginedoonbeforeunloadandstop) | Stops any navigations that are in progress and runs the `onBeforeUnload` handlers. +[DualEngineDPIChanged](#dualenginedpichanged) | Notifies that DPI has changed and page layout should be recalculated. +[DualEngineEnableCaretMode](#dualengineenablecaretmode) | Enables or disables Caret Browsing mode. +[DualEngineExecNavigationCommand](#dualengineexecnavigationcommand) | Executes a navigation command. +[DualEngineFindOnPage](#dualenginefindonpage) | Finds an instance of text on the page. +[DualEngineForceClose](#dualengineforceclose) | Force-closes the browser instance. +[DualEngineGeolocationPermissionResponse](#dualenginegeolocationpermissionresponse) | Provides a response to a geolocation permission request. +[DualEngineGoToEntry](#dualenginegotoentry) | Navigates to a specific travel log entry. +[DualEngineInitialize](#dualengineinitialize) | Initializes the browser object with an URL. +[DualEngineInitialize2](#dualengineinitialize2) | Initializes the browser object with an URL; this version allows for additional information about the initial navigation to be passed in. +[DualEngineInitializeWithRecoveryData](#dualengineinitializewithrecoverydata) | Initializes the browser object using tab recovery data. +[DualEngineLostFocus](#dualenginelostfocus) | Notifies the browser that it has lost focus. +[DualEngineNavigate](#dualenginenavigate) | Navigates to a URL. +[DualEngineNavigate2](#dualenginenavigate2) | Navigates to a URL, with additional information about the navigation. +[DualEngineNotifyNavigationEntriesDeleted](#dualenginenotifynavigationentriesdeleted) | Notifies that navigation entries have been deleted. +[DualEnginePrepareToExitRegion](#dualenginepreparetoexitregion) | Notifies the browser that a navigation is occurring to a page that will be handled by the host. +[DualEnginePrint](#dualengineprint) | Invokes the Print dialog for the current page. +[DualEngineProtectFocus](#dualengineprotectfocus) | Controls whether the browser tries to change focus to itself. +[DualEngineSavePageAs](#dualenginesavepageas) | Invokes the **Save Webpage** dialog for the current page. +[DualEngineSetEngineSwitchingPolicyFlags](#dualenginesetengineswitchingpolicyflags) | Sets flags that determine how the browser handles engine switching. +[DualEngineSetFocus](#dualenginesetfocus) | Sets focus inside the hosted browser. +[DualEngineSetMediaFullscreen](#dualenginesetmediafullscreen) | Changes the full-screen state of the media playing in the browser. +[DualEngineSetPosition](#dualenginesetposition) | Sets the size and position of the browser window. +[DualEngineSetTheaterFullscreen](#dualenginesettheaterfullscreen) | Changes the Theater mode state of the browser. +[DualEngineSetTheaterMargins](#dualenginesettheatermargins) | Adjusts the top margin of the browser window when it is being displayed in theater mode. +[DualEngineSetVisible](#dualenginesetvisible) | Notifies the browser of a visibility change. +[DualEngineSetWindowStyle](#dualenginesetwindowstyle) | Changes the style of the browser window. +[DualEngineSetZoom](#dualenginesetzoom) | Changes the zoom value of the browser. +[DualEngineSimulateKeyInput](#dualenginesimulatekeyinput) | Sends a simulated key input. +[DualEngineSimulateMouseInput](#dualenginesimulatemouseinput) | Sends a simulated mouse input. +[DualEngineStopFindOnPage](#dualenginestopfindonpage) | Stops the find operation. +[DualEngineTranslateAccelerator](#dualenginetranslateaccelerator) | Processes an accelerator message. + +## Applies to + +Product |Introduced +--------- | --------- +Windows 10, Version 20H1 |KB5032278 +Windows 11, Version 22H2 |KB5032288 + +## Members + +#### DualEngineBrowserCommitted + +Notifies the browser that it has been committed and is no longer speculative. + +> public HRESULT [DualEngineBrowserCommitted](#dualenginebrowsercommitted)() + +#### DualEngineClose + +Closes the browser instance. + +> public HRESULT [DualEngineClose](#dualengineclose)() + +#### DualEngineDeleteTabRecoveryData + +Deletes tab recovery data. + +> public HRESULT [DualEngineDeleteTabRecoveryData](#dualenginedeletetabrecoverydata)(REFGUID guidTabId) + +###### Parameters +* `guidTabId` The GUID for the source recovery data file to delete. + +#### DualEngineDoOnBeforeUnloadAndStop + +Stops any navigations that are in progress and runs the `onBeforeUnload` handlers. + +> public HRESULT [DualEngineDoOnBeforeUnloadAndStop](#dualenginedoonbeforeunloadandstop)() + +#### DualEngineDPIChanged + +Notifies that DPI has changed and page layout should be recalculated. + +> public HRESULT [DualEngineDPIChanged](#dualenginedpichanged)() + +#### DualEngineEnableCaretMode + +Enables or disables Caret Browsing mode. + +> public HRESULT [DualEngineEnableCaretMode](#dualengineenablecaretmode)(BOOL fEnable) + +###### Parameters +* `fEnable` Specifies whether caret browsing should be enabled. + +#### DualEngineExecNavigationCommand + +Executes a navigation command. + +> public HRESULT [DualEngineExecNavigationCommand](#dualengineexecnavigationcommand)(NAVIGATION_COMMAND command) + +###### Parameters +* `command` The navigation command to execute. + +#### DualEngineFindOnPage + +Finds an instance of text on the page. + +> public HRESULT [DualEngineFindOnPage](#dualenginefindonpage)(int iRequestID, LPCWSTR pszFindText, BOOL fFindNext, BOOL fForward) + +###### Parameters +* `iRequestID` An ID to use correlate find on page requests and events. + +* `pszFindText` The text to find on the page. + +* `fFindNext` Indicates whether the selection should move to the next instance the find text, true advances the selection and false does not. + +* `fForward` Indicates the direction the selection should me, true moves forward and false moves backwards. + +#### DualEngineForceClose + +Force-closes the browser instance. + +> public HRESULT [DualEngineForceClose](#dualengineforceclose)() + +#### DualEngineGeolocationPermissionResponse + +Provides a response to a geolocation permission request. + +> public HRESULT [DualEngineGeolocationPermissionResponse](#dualenginegeolocationpermissionresponse)(LPCWSTR pszUri, SITE_PERMISSION_RESPONSE response) + +###### Parameters +* `pszUri` The URI the geolocation request was from. + +* `response` The response to the request. + +#### DualEngineGoToEntry + +Navigates to a specific travel log entry. + +> public HRESULT [DualEngineGoToEntry](#dualenginegotoentry)(ULONG ulEntryId) + +###### Parameters +* `ulEntryId` The travel log entry ID to navigate to. + +#### DualEngineInitialize + +Initializes the browser object with an URL. + +> public HRESULT [DualEngineInitialize](#dualengineinitialize)([IDualEngine20BrowserObserver](idualengine20browserobserver.md) * pDualEngineObserver, DUALENGINECONFIGURATION config, EngineSwitchingPolicyFlags engineSwitchingPolicyFlags, [SentinelEntryInfo](tagsentinelentryinfo.md) sentinelEntryInfo, LPCWSTR pszUrl, HWND hwndHost, HWND * phwnd) + +###### Parameters +* `pDualEngineObserver` A pointer to the observer for this browser. + +* `config` Configuration flags for the desired browser behavior. + +* `engineSwitchingPolicyFlags` Flags that determine how engine switching is handled. + +* `sentinelEntryInfo` The number of history items before and after the initial navigation for this instance. + +* `pszUrl` The inital URL to navigate to. + +* `hwndHost` The HWND of the host window that the browser window will be parented to. + +* `phwnd` The HWND of the browser window. + +#### DualEngineInitialize2 + +Initializes the browser object with an URL; this version allows for additional information about the initial navigation to be passed in. + +> public HRESULT [DualEngineInitialize2](#dualengineinitialize2)([IDualEngine20BrowserObserver](idualengine20browserobserver.md) * pDualEngineObserver, DUALENGINECONFIGURATION config, EngineSwitchingPolicyFlags engineSwitchingPolicyFlags, [SentinelEntryInfo](tagsentinelentryinfo.md) sentinelEntryInfo, LPCWSTR pszUrl, HWND hwndHost, HWND * phwnd, LPCWSTR pszReferrer, LPCWSTR pszHeaders, VARIANT * postData) + +###### Parameters +* `pDualEngineObserver` A pointer to the observer for this browser. + +* `config` Configuration flags for the desired browser behavior. + +* `engineSwitchingPolicyFlags` Flags that determine how engine switching is handled. + +* `sentinelEntryInfo` The number of history items before and after the initial navigation for this instance. + +* `pszUrl` The inital URL to navigate to. + +* `hwndHost` The HWND of the host window that the browser window will be parented to. + +* `phwnd` The HWND of the browser window. + +* `pszReferrer` The HTTP Referer request header for the initial navigation. + +* `pszHeaders` Additional headers to send to the server for the initial navigation. + +* `postData` Data to be sent to the server as part of a HTTP POST transaction for the initial navigation. + +#### DualEngineInitializeWithRecoveryData + +Initializes the browser object using tab recovery data. + +> public HRESULT [DualEngineInitializeWithRecoveryData](#dualengineinitializewithrecoverydata)(REFGUID guidTabId, ULONG ulEntryId, [IDualEngine20BrowserObserver](idualengine20browserobserver.md) * pDualEngineObserver, DUALENGINECONFIGURATION config, EngineSwitchingPolicyFlags engineSwitchingPolicyFlags, [SentinelEntryInfo](tagsentinelentryinfo.md) sentinelEntryInfo, LPCWSTR pszUrl, HWND hwndHost, HWND * phwnd) + +###### Parameters +* `guidTabId` The GUID for the source recovery data file to initialize this instance with. + +* `ulEntryId` The ID of the entry in the travel log to navigate to after recovery. + +* `pDualEngineObserver` A pointer to the observer for this browser. + +* `config` Configuration flags for the desired browser behavior. + +* `engineSwitchingPolicyFlags` Flags that determine how engine switching is handled. + +* `sentinelEntryInfo` The number of history items before and after the initial navigation for this instance. + +* `pszUrl` The inital URL to navigate to. + +* `hwndHost` The HWND of the host window that the browser window will be parented to. + +* `phwnd` The HWND of the browser window. + +#### DualEngineLostFocus + +Notifies the browser that it has lost focus. + +> public HRESULT [DualEngineLostFocus](#dualenginelostfocus)(HWND hwndLostFocus) + +###### Parameters +* `hwndLostFocus` The window that focus is moving to. + +#### DualEngineNavigate + +Navigates to a URL. + +> public HRESULT [DualEngineNavigate](#dualenginenavigate)(LPCWSTR pszUrl, BOOL fSkipOnBeforeUnload) + +###### Parameters +* `pszUrl` The URL to navigate to. + +* `fSkipOnBeforeUnload` Whether to skip the `onBeforeUnload` handling. + +#### DualEngineNavigate2 + +Navigates to a URL, with additional information about the navigation. + +> public HRESULT [DualEngineNavigate2](#dualenginenavigate2)(LPCWSTR pszUrl, BOOL fSkipOnBeforeUnload, LPCWSTR pszReferrer, LPCWSTR pszHeaders, VARIANT * postData) + +###### Parameters +* `pszUrl` The URL to navigate to. + +* `fSkipOnBeforeUnload` Whether to skip the `onBeforeUnload` handling. + +* `pszReferrer` The HTTP Referer request header for this navigation. + +* `pszHeaders` Additional headers to send to the server for this navigation. + +* `postData` Data to be sent to the server as part of a HTTP POST transaction for this navigation. + +#### DualEngineNotifyNavigationEntriesDeleted + +Notifies that navigation entries have been deleted. + +> public HRESULT [DualEngineNotifyNavigationEntriesDeleted](#dualenginenotifynavigationentriesdeleted)(BOOL fShouldDeleteEntries, [SentinelEntryInfo](tagsentinelentryinfo.md) sentinelEntryInfo) + +###### Parameters +* `fShouldDeleteEntries` Indicates whether the browser should delete all the entries in it's list. + +* `sentinelEntryInfo` The number of history items before and after the initial navigation for this instance. + +#### DualEnginePrepareToExitRegion + +Notifies the browser that a navigation is occurring to a page that will be handled by the host. + +> public HRESULT [DualEnginePrepareToExitRegion](#dualenginepreparetoexitregion)(EXIT_REGION_TYPE type) + +###### Parameters +* `type` The type of navigation that is causing this exit. + +#### DualEnginePrint + +Invokes the Print dialog for the current page. + +> public HRESULT [DualEnginePrint](#dualengineprint)() + +#### DualEngineProtectFocus + +Controls whether the browser tries to change focus to itself. + +> public HRESULT [DualEngineProtectFocus](#dualengineprotectfocus)(BOOL fProtectFocus) + +###### Parameters +* `fProtectFocus` If `true`, the browser will not try to steal focus; if `false`, stealing focus is allowed. + +#### DualEngineSavePageAs + +Invokes the **Save Webpage** dialog for the current page. + +> public HRESULT [DualEngineSavePageAs](#dualenginesavepageas)() + +#### DualEngineSetEngineSwitchingPolicyFlags + +Sets flags that determine how the browser handles engine switching. + +> public HRESULT [DualEngineSetEngineSwitchingPolicyFlags](#dualenginesetengineswitchingpolicyflags)(EngineSwitchingPolicyFlags engineSwitchingPolicyFlags) + +###### Parameters +* `engineSwitchingPolicyFlags` Flags representing the desired engine switching behavior. + +#### DualEngineSetFocus + +Sets focus inside the hosted browser. + +> public HRESULT [DualEngineSetFocus](#dualenginesetfocus)(DUALENGINE_FOCUSDIRECTION focusDirection) + +###### Parameters +* `focusDirection` The direction that focus is moving within the browser. + +#### DualEngineSetMediaFullscreen + +Changes the full-screen state of the media playing in the browser. + +> public HRESULT [DualEngineSetMediaFullscreen](#dualenginesetmediafullscreen)(BOOL fFullscreen) + +> [!WARNING] +> Despite its name, this function only exits fullscreen and will do nothing if no media is fullscreen. +> Passing `true` into the function is always a no-op. +###### Parameters +* `fFullscreen` If `false`, fullscreen will be exited if media is fullscreen; if `true`, nothing happens. + +#### DualEngineSetPosition + +Sets the size and position of the browser window. + +> public HRESULT [DualEngineSetPosition](#dualenginesetposition)(int x, int y, int iWidth, int iHeight) + +###### Parameters +* `x` The new position of the left side of the window, in client coordinates. + +* `y` The new position of the top of the window, in client coordinates. + +* `iWidth` The new width of the window, in pixels. + +* `iHeight` The new height of the window, in pixels. + +#### DualEngineSetTheaterFullscreen + +Changes the Theater mode state of the browser. + +> public HRESULT [DualEngineSetTheaterFullscreen](#dualenginesettheaterfullscreen)(BOOL fFullscreen) + +In theater mode, the browsers window fills the entire screen and displays a toolbar that has a minimal set of navigation buttons. A status bar is also provided in the upper-right corner of the screen. Explorer bars, such as History and Favorites, are displayed as an autohide pane on the left edge of the screen in theater mode. +###### Parameters +* `fFullscreen` If `true` and not currently in theater mode, the browser will enter theater mode; if `false` and currently in theater mode, the browser will exit theater mode. + +#### DualEngineSetTheaterMargins + +Adjusts the top margin of the browser window when it is being displayed in theater mode. + +> public HRESULT [DualEngineSetTheaterMargins](#dualenginesettheatermargins)(BOOL fTheaterShowing, int yTheaterThreshold) + +###### Parameters +* `fTheaterShowing` Indicates whether the host is currently in theater mode. + +* `yTheaterThreshold` The size in pixels of the margin between the top of the screen and the fullscreen browser window. + +#### DualEngineSetVisible + +Notifies the browser of a visibility change. + +> public HRESULT [DualEngineSetVisible](#dualenginesetvisible)(BROWSERVISIBILITY visibility) + +###### Parameters +* `visibility` The visibility state we are entering. + +#### DualEngineSetWindowStyle + +Changes the style of the browser window. + +> public HRESULT [DualEngineSetWindowStyle](#dualenginesetwindowstyle)(int wlStyle, int wlExStyle) + +###### Parameters +* `wlStyle` The Window Style value to set. + +* `wlExStyle` The Extended Windows Style value to set. + +#### DualEngineSetZoom + +Changes the zoom value of the browser. + +> public HRESULT [DualEngineSetZoom](#dualenginesetzoom)(int iZoomPercent) + +###### Parameters +* `iZoomPercent` The zoom percentage to set the browser to. + +#### DualEngineSimulateKeyInput + +Sends a simulated key input. + +> public HRESULT [DualEngineSimulateKeyInput](#dualenginesimulatekeyinput)(DWORD vKey, KEYACTION keyAction) + +###### Parameters +* `vKey` The virtual keycode to simulate. + +* `keyAction` The key action to simulate. + +#### DualEngineSimulateMouseInput + +Sends a simulated mouse input. + +> public HRESULT [DualEngineSimulateMouseInput](#dualenginesimulatemouseinput)(DWORD x, DWORD y, MOUSEACTION mouseAction) + +###### Parameters +* `x` The x coordinate. + +* `y` The y coordinate. + +* `mouseAction` The mouse action to simulate. + +#### DualEngineStopFindOnPage + +Stops the find operation. + +> public HRESULT [DualEngineStopFindOnPage](#dualenginestopfindonpage)(BOOL fClean) + +###### Parameters +* `fClean` If `true`, the highlighted results and current selected result will be cleared; if `false`, the current selected result will remain selected. + +#### DualEngineTranslateAccelerator + +Processes an accelerator message. + +> public HRESULT [DualEngineTranslateAccelerator](#dualenginetranslateaccelerator)(LPMSG lpMsg) + +###### Parameters +* `lpMsg` A pointer to a MSG structure that specifies the message to be translated. diff --git a/microsoft-edge/dualengine/reference/idualengine20browserobserver.md b/microsoft-edge/dualengine/reference/idualengine20browserobserver.md new file mode 100644 index 0000000000..7db0cd9abd --- /dev/null +++ b/microsoft-edge/dualengine/reference/idualengine20browserobserver.md @@ -0,0 +1,666 @@ +--- +title: DualEngine Win32 C++ IDualEngine20BrowserObserver +description: Receives events from the Browser. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/27/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, IDualEngine20BrowserObserver +topic_type: +- APIRef +api_name: +- IDualEngine20BrowserObserver +- IDualEngine20BrowserObserver.ContinueNavigationInEdge +- IDualEngine20BrowserObserver.ContinueNavigationInEdge2 +- IDualEngine20BrowserObserver.NavigateToOffsetInEdge +- IDualEngine20BrowserObserver.OnAllButCurrentEntryDeleted +- IDualEngine20BrowserObserver.OnAsyncHungCheckReply +- IDualEngine20BrowserObserver.OnAttentionState +- IDualEngine20BrowserObserver.OnBeforeUnloadAndStopComplete +- IDualEngine20BrowserObserver.OnCloseCompleted +- IDualEngine20BrowserObserver.OnCloseRequested +- IDualEngine20BrowserObserver.OnDialogShown +- IDualEngine20BrowserObserver.OnDocumentComplete +- IDualEngine20BrowserObserver.OnDocumentModeSet +- IDualEngine20BrowserObserver.OnEnterpriseIDSet +- IDualEngine20BrowserObserver.OnFindOnPageResult +- IDualEngine20BrowserObserver.OnFinishedSetFocus +- IDualEngine20BrowserObserver.OnGeolocationFeatureInUse +- IDualEngine20BrowserObserver.OnGeolocationPermissionRequested +- IDualEngine20BrowserObserver.OnHasBeforeUnloadChanged +- IDualEngine20BrowserObserver.OnIndicatorItemsSet +- IDualEngine20BrowserObserver.OnInputAttempted +- IDualEngine20BrowserObserver.OnLoadingActivityChanged +- IDualEngine20BrowserObserver.OnMixedContentBlocked +- IDualEngine20BrowserObserver.OnNavigationComplete +- IDualEngine20BrowserObserver.OnNavigationFailed +- IDualEngine20BrowserObserver.OnNavigationToDownload +- IDualEngine20BrowserObserver.OnNewWindow +- IDualEngine20BrowserObserver.OnPopupBlocked +- IDualEngine20BrowserObserver.OnPrepareToExitRegionFailed +- IDualEngine20BrowserObserver.OnReadyToExitRegion +- IDualEngine20BrowserObserver.OnTabCrashed +- IDualEngine20BrowserObserver.OnTabHangReported +- IDualEngine20BrowserObserver.OnUnexpectedRundown +- IDualEngine20BrowserObserver.OnUnhandledKeyboardAccelerator +- IDualEngine20BrowserObserver.OnUnhandledKeyboardAcceleratorAsync +- IDualEngine20BrowserObserver.OnVisibleComplete +- IDualEngine20BrowserObserver.OnZoomChanged +- IDualEngine20BrowserObserver.OpenURLInEdge +- IDualEngine20BrowserObserver.OpenURLInEdge2 +- IDualEngine20BrowserObserver.RequestHostAddFavorite +- IDualEngine20BrowserObserver.RequestHostCreateUrlTip +- IDualEngine20BrowserObserver.RequestHostFocus +- IDualEngine20BrowserObserver.RequestHostFullscreen +- IDualEngine20BrowserObserver.RequestHostHideUrlTip +- IDualEngine20BrowserObserver.RequestHostPositionChanged +- IDualEngine20BrowserObserver.RequestHostShowTheater +- IDualEngine20BrowserObserver.RequestHostWindowFocus +- IDualEngine20BrowserObserver.RequestHostWindowFocusSync +- IDualEngine20BrowserObserver.UpdateHostFavicon +- IDualEngine20BrowserObserver.UpdateHostTitle +- IDualEngine20BrowserObserver.UpdateSecureLockIcon +api_type: +- COM +api_location: +- ieframe.dll +--- + +# interface IDualEngine20BrowserObserver + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +```cpp +interface IDualEngine20BrowserObserver + : public IUnknown +``` + +Receives events from the Browser. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[ContinueNavigationInEdge](#continuenavigationinedge) | Raised when the browser wants to stop hosting content and have the navigation to the URL continue in the hosting process. +[ContinueNavigationInEdge2](#continuenavigationinedge2) | Raised when the browser wants to stop hosting content and have the navigation to the URL continue in the hosting process; this version provides extra information about the navigation. +[NavigateToOffsetInEdge](#navigatetooffsetinedge) | Raised when the browser requests to navigate to a travel log entry offset. +[OnAllButCurrentEntryDeleted](#onallbutcurrententrydeleted) | Raised when the browser has deleted all entries in its travel log except for the current entry. +[OnAsyncHungCheckReply](#onasynchungcheckreply) | Raised when the browser processes an async hang check message, see [IDualEngine20BrowserSession::SetHangDetectionMessages()](idualengine20browsersession.md#sethangdetectionmessages). +[OnAttentionState](#onattentionstate) | Raised when requesting user attention. +[OnBeforeUnloadAndStopComplete](#onbeforeunloadandstopcomplete) | Raised when the beforeUnload event has finished being processed. +[OnCloseCompleted](#onclosecompleted) | Raised when the browser has closed. +[OnCloseRequested](#oncloserequested) | Raised when the browser has requested to close. +[OnDialogShown](#ondialogshown) | Raised when a the browser shows or hides a modal dialog. +[OnDocumentComplete](#ondocumentcomplete) | Raised when a document is completely loaded and initialized. +[OnDocumentModeSet](#ondocumentmodeset) | Raised when the document mode has changed. +[OnEnterpriseIDSet](#onenterpriseidset) | Raised when a navigation has been completed; provides information about the enterprise ID. +[OnFindOnPageResult](#onfindonpageresult) | Raised when find on page results change. +[OnFinishedSetFocus](#onfinishedsetfocus) | Raised when a [IDualEngine20Browser::DualEngineSetFocus()](idualengine20browser.md#dualenginesetfocus) request has finished being processed. +[OnGeolocationFeatureInUse](#ongeolocationfeatureinuse) | Raised when geolocation data is accessed. +[OnGeolocationPermissionRequested](#ongeolocationpermissionrequested) | Raised when user permission is needed to enable geolocation. +[OnHasBeforeUnloadChanged](#onhasbeforeunloadchanged) | Raised when an `OnBeforeUnload` handler has been registered or removed. +[OnIndicatorItemsSet](#onindicatoritemsset) | Raised when a navigation has been completed; provides status information about the current state of the browser page. +[OnInputAttempted](#oninputattempted) | Raised when user input is received. +[OnLoadingActivityChanged](#onloadingactivitychanged) | Raised when the page's loading state changes. +[OnMixedContentBlocked](#onmixedcontentblocked) | Raised when Mixed Content has been blocked. +[OnNavigationComplete](#onnavigationcomplete) | Raised when a navigation has been completed. +[OnNavigationFailed](#onnavigationfailed) | Raised when a navigation fails. +[OnNavigationToDownload](#onnavigationtodownload) | Raised when a navigation has ended in a download. +[OnNewWindow](#onnewwindow) | Raised when a new window has been created. +[OnPopupBlocked](#onpopupblocked) | Raised when a popup window was blocked. +[OnPrepareToExitRegionFailed](#onpreparetoexitregionfailed) | Raised when the browser has failed to a handle a previous [IDualEngine20Browser::DualEnginePrepareToExitRegion()](idualengine20browser.md#dualenginepreparetoexitregion) call. +[OnReadyToExitRegion](#onreadytoexitregion) | Raised when the browser has successfully handled a previous [IDualEngine20Browser::DualEnginePrepareToExitRegion()](idualengine20browser.md#dualenginepreparetoexitregion) call. +[OnTabCrashed](#ontabcrashed) | Raised when the tab has crashed. +[OnTabHangReported](#ontabhangreported) | Raised when the browser is hung. +[OnUnexpectedRundown](#onunexpectedrundown) | Raised when the browser has closed unexpectedly. +[OnUnhandledKeyboardAccelerator](#onunhandledkeyboardaccelerator) | Raised when processing a keyboard accelerator and it is determined that the browser does not, or should not based on `rgHostPriorityAccels`, handle that accelerator. +[OnUnhandledKeyboardAcceleratorAsync](#onunhandledkeyboardacceleratorasync) | Raised when processing a keyboard accelerator and it is determined that browser does not, or should not based on `rgHostPriorityAccels`, handle that accelerator. +[OnVisibleComplete](#onvisiblecomplete) | Raised when the content of the page is being made visible. +[OnZoomChanged](#onzoomchanged) | Raised when the zoom has changed. +[OpenURLInEdge](#openurlinedge) | Raised when the browser is requesting the host to navigate to a URL in a new window. +[OpenURLInEdge2](#openurlinedge2) | Raised when the browser is requesting the host to navigate to a URL in a new window; this version provides extra information about the navigation. +[RequestHostAddFavorite](#requesthostaddfavorite) | Raised when a page has been requested to be added to favorites. +[RequestHostCreateUrlTip](#requesthostcreateurltip) | Raised when requesting to show a tooltip containing a URL. +[RequestHostFocus](#requesthostfocus) | Raised when focus is being requested to move to the host window. +[RequestHostFullscreen](#requesthostfullscreen) | Raised when the page is requesting that the host display content in fullscreen. +[RequestHostHideUrlTip](#requesthosthideurltip) | Raised when requesting to hide a tooltip containing a URL. +[RequestHostPositionChanged](#requesthostpositionchanged) | Raised when the browser requests that the host change its size or position. +[RequestHostShowTheater](#requesthostshowtheater) | Raised when the browser is requesting the host to enter or leave theater mode. +[RequestHostWindowFocus](#requesthostwindowfocus) | Raised when the host is requested to take or give up focus. +[RequestHostWindowFocusSync](#requesthostwindowfocussync) | Raised when the host is requested to take or give up focus. +[UpdateHostFavicon](#updatehostfavicon) | Raised when the favicon has changed. +[UpdateHostTitle](#updatehosttitle) | Raised when the title of the page has been updated. +[UpdateSecureLockIcon](#updatesecurelockicon) | Raised when security information of the page has changed. + +## Applies to + +Product |Introduced +--------- | --------- +Windows 10, Version 20H1 |KB5032278 +Windows 11, Version 22H2 |KB5032288 + +## Members + +#### ContinueNavigationInEdge + +Raised when the browser wants to stop hosting content and have the navigation to the URL continue in the hosting process. + +> public HRESULT [ContinueNavigationInEdge](#continuenavigationinedge)(LPCWSTR pszUrl, ULONG ulCookieSyncVersion) + +###### Parameters +* `pszUrl` The URL that should be navigated to. + +* `ulCookieSyncVersion` A number that can be used to correlate a navigation with a specific cookie state. + +#### ContinueNavigationInEdge2 + +Raised when the browser wants to stop hosting content and have the navigation to the URL continue in the hosting process; this version provides extra information about the navigation. + +> public HRESULT [ContinueNavigationInEdge2](#continuenavigationinedge2)(LPCWSTR pszUrl, ULONG ulCookieSyncVersion, LPCWSTR pszReferrer, LPCWSTR pszHeaders, VARIANT * postData) + +###### Parameters +* `pszUrl` The URL that should be navigated to. + +* `ulCookieSyncVersion` A number that can be used to correlate a navigation with a specific cookie state. + +* `pszReferrer` The HTTP Referer request header. + +* `pszHeaders` Additional HTTP headers. + +* `postData` HTTP POST data, such as form data. + +#### NavigateToOffsetInEdge + +Raised when the browser requests to navigate to a travel log entry offset. + +> public HRESULT [NavigateToOffsetInEdge](#navigatetooffsetinedge)(int iOffset) + +###### Parameters +* `iOffset` The offset to navigate to. + +#### OnAllButCurrentEntryDeleted + +Raised when the browser has deleted all entries in its travel log except for the current entry. + +> public HRESULT [OnAllButCurrentEntryDeleted](#onallbutcurrententrydeleted)([VisibleListUpdateEntry](visiblelistupdateentry.md) * pVisibleListEntries, int cVisibleListEntries) + +###### Parameters +* `pVisibleListEntries` A list containing the new travel log entries since the last update. In this case it will only have the current active entry. + +* `cVisibleListEntries` The number of items in `pVisibleListEntries` + +#### OnAsyncHungCheckReply + +Raised when the browser processes an async hang check message, see [IDualEngine20BrowserSession::SetHangDetectionMessages()](idualengine20browsersession.md#sethangdetectionmessages). + +> public HRESULT [OnAsyncHungCheckReply](#onasynchungcheckreply)(ULONG correlationId) + +###### Parameters +* `correlationId` Id to correlate the reply with the sent message. + +#### OnAttentionState + +Raised when requesting user attention. + +> public HRESULT [OnAttentionState](#onattentionstate)(ATTENTIONSTATE attentionState) + +###### Parameters +* `attentionState` The reason that user attention is being requested. + +#### OnBeforeUnloadAndStopComplete + +Raised when the beforeUnload event has finished being processed. + +> public HRESULT [OnBeforeUnloadAndStopComplete](#onbeforeunloadandstopcomplete)(BOOL agreeToClose) + +###### Parameters +* `agreeToClose` Indicates whether the user has agreed to leave the page. + +#### OnCloseCompleted + +Raised when the browser has closed. + +> public HRESULT [OnCloseCompleted](#onclosecompleted)() + +#### OnCloseRequested + +Raised when the browser has requested to close. + +> public HRESULT [OnCloseRequested](#oncloserequested)() + +#### OnDialogShown + +Raised when a the browser shows or hides a modal dialog. + +> public HRESULT [OnDialogShown](#ondialogshown)(BOOL fShown) + +###### Parameters +* `fShown` Indicates whether the dialog was shown or hidden. + +#### OnDocumentComplete + +Raised when a document is completely loaded and initialized. + +> public HRESULT [OnDocumentComplete](#ondocumentcomplete)(ULONG ulCurrentEntryId, [VisibleListUpdateEntry](visiblelistupdateentry.md) * pVisibleListEntries, int cVisibleListEntries) + +###### Parameters +* `ulCurrentEntryId` The travel log entry ID for the page that raised this event. + +* `pVisibleListEntries` A list containing the new travel log entries since the last update. + +* `cVisibleListEntries` The number of items in `pVisibleListEntries` + +#### OnDocumentModeSet + +Raised when the document mode has changed. + +> public HRESULT [OnDocumentModeSet](#ondocumentmodeset)(ULONG documentMode) + +###### Parameters +* `documentMode` The new document mode version. + +#### OnEnterpriseIDSet + +Raised when a navigation has been completed; provides information about the enterprise ID. + +> public HRESULT [OnEnterpriseIDSet](#onenterpriseidset)(BOOL fEnterpriseID) + +###### Parameters +* `fEnterpriseID` Indicates whether the browser has an enterprise ID set. + +#### OnFindOnPageResult + +Raised when find on page results change. + +> public HRESULT [OnFindOnPageResult](#onfindonpageresult)(int iRequestID, int cMatches, int iActiveMatch) + +###### Parameters +* `iRequestID` An ID to correlate results with [IDualEngine20Browser::DualEngineFindOnPage()](idualengine20browser.md#dualenginefindonpage) requests. + +* `cMatches` The count of matches. + +* `iActiveMatch` The index of the selected match. + +#### OnFinishedSetFocus + +Raised when a [IDualEngine20Browser::DualEngineSetFocus()](idualengine20browser.md#dualenginesetfocus) request has finished being processed. + +> public HRESULT [OnFinishedSetFocus](#onfinishedsetfocus)() + +#### OnGeolocationFeatureInUse + +Raised when geolocation data is accessed. + +> public HRESULT [OnGeolocationFeatureInUse](#ongeolocationfeatureinuse)(LPCWSTR pszContextUrl, SITE_PERMISSION_FEATURE_MODE featureMode) + +###### Parameters +* `pszContextUrl` The URL of the page accessing geolocation data. + +* `featureMode` Indicates whether the access was blocked or allowed. + +#### OnGeolocationPermissionRequested + +Raised when user permission is needed to enable geolocation. + +> public HRESULT [OnGeolocationPermissionRequested](#ongeolocationpermissionrequested)(LPCWSTR pszContextUrl) + +###### Parameters +* `pszContextUrl` The URL of the page requesting geolocation permission. + +#### OnHasBeforeUnloadChanged + +Raised when an `OnBeforeUnload` handler has been registered or removed. + +> public HRESULT [OnHasBeforeUnloadChanged](#onhasbeforeunloadchanged)(BOOL fBeforeUnload) + +###### Parameters +* `fBeforeUnload` `true` indicates that an `OnBeforeUnload` handler was registered; `false` indicates it was removed. + +#### OnIndicatorItemsSet + +Raised when a navigation has been completed; provides status information about the current state of the browser page. + +> public HRESULT [OnIndicatorItemsSet](#onindicatoritemsset)(BOOL fProtectedMode, BOOL fEnhancedProtectedMode, DWORD dwUrlZone, BOOL fEnterpriseMode) + +###### Parameters +* `fProtectedMode` Indicates whether the browser is in Protected Mode. + +* `fEnhancedProtectedMode` Indicates whether the browser is in Enhanced Protected Mode. + +* `dwUrlZone` The zone of the current URL. + +* `fEnterpriseMode` Indicates whether the browser is in Enterprise Mode. + +#### OnInputAttempted + +Raised when user input is received. + +> public HRESULT [OnInputAttempted](#oninputattempted)() + +#### OnLoadingActivityChanged + +Raised when the page's loading state changes. + +> public HRESULT [OnLoadingActivityChanged](#onloadingactivitychanged)(BOOL fLoading) + +###### Parameters +* `fLoading` Indicates whether the page is loading or not. + +#### OnMixedContentBlocked + +Raised when Mixed Content has been blocked. + +> public HRESULT [OnMixedContentBlocked](#onmixedcontentblocked)() + +#### OnNavigationComplete + +Raised when a navigation has been completed. + +> public HRESULT [OnNavigationComplete](#onnavigationcomplete)(REFGUID guidTabId, ULONG ulCurrentEntryId, [VisibleListUpdateEntry](visiblelistupdateentry.md) * pVisibleListEntries, int cVisibleListEntries, DWORD dwNavFlags, SECURELOCKICON secureLockIcon, DWORD dwSecurityFlags, [CryptDataBlob](cryptdatablob.md) * pDualEngineCertificates, int cCertificateChainBlobs) + +###### Parameters +* `guidTabId` The recovery GUID for tab. + +* `ulCurrentEntryId` The ID representing this navigation in the visible-entries list. + +* `pVisibleListEntries` A list containing the new travel log entries since the last update. + +* `cVisibleListEntries` The number of items in `pVisibleListEntries`. + +* `dwNavFlags` Flags indicating the type of navigation that occurred. + +* `secureLockIcon` The security state of the page. + +* `dwSecurityFlags` Flags indicating any certificate errors for the page. + +* `pDualEngineCertificates` A list containing the certificate chain for the current entry's page. + +* `cCertificateChainBlobs` The number of items in `pDualEngineCertificates`. + +#### OnNavigationFailed + +Raised when a navigation fails. + +> public HRESULT [OnNavigationFailed](#onnavigationfailed)(NAVIGATIONFAILEDREASON failureReason) + +###### Parameters +* `failureReason` The reason the navigation failed. + +#### OnNavigationToDownload + +Raised when a navigation has ended in a download. + +> public HRESULT [OnNavigationToDownload](#onnavigationtodownload)() + +#### OnNewWindow + +Raised when a new window has been created. + +> public HRESULT [OnNewWindow](#onnewwindow)([IDualEngine20Browser](idualengine20browser.md) * pNewBrowser, HWND hwnd, const [DualEngineNewWindowOptions](dualenginenewwindowoptions.md) * options, [IDualEngine20BrowserObserver](idualengine20browserobserver.md) ** ppObserver) + +###### Parameters +* `pNewBrowser` The browser object for the new window. + +* `hwnd` The handle for the new window. + +* `options` The options that the new window was created with. + +* `ppObserver` The observer object for the new window. + +#### OnPopupBlocked + +Raised when a popup window was blocked. + +> public HRESULT [OnPopupBlocked](#onpopupblocked)(LPCWSTR pszContextUrl, LPCWSTR pszPopupUrl) + +###### Parameters +* `pszContextUrl` The URL of the page that issued the command to open the popup. + +* `pszPopupUrl` The URL of the popup page. + +#### OnPrepareToExitRegionFailed + +Raised when the browser has failed to a handle a previous [IDualEngine20Browser::DualEnginePrepareToExitRegion()](idualengine20browser.md#dualenginepreparetoexitregion) call. + +> public HRESULT [OnPrepareToExitRegionFailed](#onpreparetoexitregionfailed)() + +#### OnReadyToExitRegion + +Raised when the browser has successfully handled a previous [IDualEngine20Browser::DualEnginePrepareToExitRegion()](idualengine20browser.md#dualenginepreparetoexitregion) call. + +> public HRESULT [OnReadyToExitRegion](#onreadytoexitregion)(REFGUID guidClonedTabId, ULONG ulCurrentEntryId, [VisibleListUpdateEntry](visiblelistupdateentry.md) * pVisibleListEntriesComplete, int cVisibleListEntriesComplete) + +###### Parameters +* `guidClonedTabId` The GUID of the tab recovery data file backing the exited region. + +* `ulCurrentEntryId` The travel log entry ID for the page that raised this event. + +* `pVisibleListEntriesComplete` A list containing the new travel log entries since the last update. + +* `cVisibleListEntriesComplete` The number of items in `pVisibleListEntriesComplete` + +#### OnTabCrashed + +Raised when the tab has crashed. + +> public HRESULT [OnTabCrashed](#ontabcrashed)(BOOL fUnrecoverable) + +###### Parameters +* `fUnrecoverable` Indicates whether the tab is recoverable. + +#### OnTabHangReported + +Raised when the browser is hung. + +> public HRESULT [OnTabHangReported](#ontabhangreported)() + +#### OnUnexpectedRundown + +Raised when the browser has closed unexpectedly. + +> public HRESULT [OnUnexpectedRundown](#onunexpectedrundown)() + +#### OnUnhandledKeyboardAccelerator + +Raised when processing a keyboard accelerator and it is determined that the browser does not, or should not based on `rgHostPriorityAccels`, handle that accelerator. + +> public HRESULT [OnUnhandledKeyboardAccelerator](#onunhandledkeyboardaccelerator)(LPMSG lpMsg) + +###### Parameters +* `lpMsg` The win32 message for the unhandled keyboard accelerator. + +#### OnUnhandledKeyboardAcceleratorAsync + +Raised when processing a keyboard accelerator and it is determined that browser does not, or should not based on `rgHostPriorityAccels`, handle that accelerator. + +> public HRESULT [OnUnhandledKeyboardAcceleratorAsync](#onunhandledkeyboardacceleratorasync)(LPMSG pMsg, BOOL isShiftDown, BOOL isCtrlDown, BOOL isAltDown) + +In this version of the method, the event is raised asynchronously and keyboard state may have changed since it was processed, so the state of the modifier keys is provided. +###### Parameters +* `pMsg` The win32 message for the unhandled keyboard accelerator. + +* `isShiftDown` Indicates whether the **Shift** key was pressed. + +* `isCtrlDown` Indicates whether the **Ctrl** key was pressed. + +* `isAltDown` Indicates whether the **Alt** key was pressed. + +#### OnVisibleComplete + +Raised when the content of the page is being made visible. + +> public HRESULT [OnVisibleComplete](#onvisiblecomplete)() + +#### OnZoomChanged + +Raised when the zoom has changed. + +> public HRESULT [OnZoomChanged](#onzoomchanged)(ULONG ulZoomPercent) + +###### Parameters +* `ulZoomPercent` The new zoom percentage. + +#### OpenURLInEdge + +Raised when the browser is requesting the host to navigate to a URL in a new window. + +> public HRESULT [OpenURLInEdge](#openurlinedge)(LPCWSTR pszUrl, const [DualEngineNewWindowOptions](dualenginenewwindowoptions.md) * options, ULONG ulCookieSyncVersion) + +###### Parameters +* `pszUrl` The URL to navigate to. + +* `options` Options to apply to the new window. + +* `ulCookieSyncVersion` A number that can be used to correlate a navigation with a specific cookie state. + +#### OpenURLInEdge2 + +Raised when the browser is requesting the host to navigate to a URL in a new window; this version provides extra information about the navigation. + +> public HRESULT [OpenURLInEdge2](#openurlinedge2)(LPCWSTR pszUrl, const [DualEngineNewWindowOptions](dualenginenewwindowoptions.md) * options, ULONG ulCookieSyncVersion, LPCWSTR pszReferrer, LPCWSTR pszHeaders, VARIANT * postData) + +###### Parameters +* `pszUrl` The URL to navigate to. + +* `options` Options to apply to the navigation. + +* `ulCookieSyncVersion` A number that can be used to correlate a navigation with a specific cookie state. + +* `pszReferrer` The HTTP Referer request header. + +* `pszHeaders` Additional HTTP headers. + +* `postData` HTTP POST data, such as form data. + +#### RequestHostAddFavorite + +Raised when a page has been requested to be added to favorites. + +> public HRESULT [RequestHostAddFavorite](#requesthostaddfavorite)(LPCWSTR pszTitle, LPCWSTR pszUrl) + +###### Parameters +* `pszTitle` The title of the page. + +* `pszUrl` The URL of the page. + +#### RequestHostCreateUrlTip + +Raised when requesting to show a tooltip containing a URL. + +> public HRESULT [RequestHostCreateUrlTip](#requesthostcreateurltip)(LPCWSTR pszUrl) + +###### Parameters +* `pszUrl` The URL to display in the tooltip. + +#### RequestHostFocus + +Raised when focus is being requested to move to the host window. + +> public HRESULT [RequestHostFocus](#requesthostfocus)(DUALENGINE_FOCUSDIRECTION focusDirection, const MSG * msg) + +###### Parameters +* `focusDirection` The direction that focus is moving. + +* `msg` A pointer to the message that caused the focus change. + +#### RequestHostFullscreen + +Raised when the page is requesting that the host display content in fullscreen. + +> public HRESULT [RequestHostFullscreen](#requesthostfullscreen)(FULLSCREENACTION fullScreenAction) + +###### Parameters +* `fullScreenAction` The fullscreen action that is being requested. + +#### RequestHostHideUrlTip + +Raised when requesting to hide a tooltip containing a URL. + +> public HRESULT [RequestHostHideUrlTip](#requesthosthideurltip)() + +#### RequestHostPositionChanged + +Raised when the browser requests that the host change its size or position. + +> public HRESULT [RequestHostPositionChanged](#requesthostpositionchanged)(LONG nX, LONG nY, LONG nWidth, LONG nHeight, ULONGLONG hSyncEvent) + +###### Parameters +* `nX` The requested window X position. + +* `nY` The requested window Y position. + +* `nWidth` The requested window width. + +* `nHeight` The requested window height. + +* `hSyncEvent` A handle to the event object that should be signaled when the change is complete. + +#### RequestHostShowTheater + +Raised when the browser is requesting the host to enter or leave theater mode. + +> public HRESULT [RequestHostShowTheater](#requesthostshowtheater)(BOOL fShow) + +###### Parameters +* `fShow` If `true`, the host is being requested to enter theater mode; if `false`, it is being requested to leave theater mode. + +#### RequestHostWindowFocus + +Raised when the host is requested to take or give up focus. + +> public HRESULT [RequestHostWindowFocus](#requesthostwindowfocus)(BOOL fFocus) + +###### Parameters +* `fFocus` Indicates what should be done with focus. If `true`, focus should be taken; otherwise it should be relinquished. + +#### RequestHostWindowFocusSync + +Raised when the host is requested to take or give up focus. + +> public HRESULT [RequestHostWindowFocusSync](#requesthostwindowfocussync)(BOOL fFocus, ULONGLONG hSyncEvent) + +In this version of the method, the browser will wait until the provided event is signaled. +###### Parameters +* `fFocus` Indicates what should be done with focus. If `true`, focus should be taken; otherwise it should be relinquished. + +* `hSyncEvent` A handle to the event object that should be signaled when the change is complete. + +#### UpdateHostFavicon + +Raised when the favicon has changed. + +> public HRESULT [UpdateHostFavicon](#updatehostfavicon)(ULONG ulCurrentEntryId, LPCWSTR spszCurrentUrl, LPCWSTR * pIconUrls, int cIconUrls) + +###### Parameters +* `ulCurrentEntryId` The travel log entry ID for the page that raised this event. + +* `spszCurrentUrl` The URL of the page. + +* `pIconUrls` A list of favicon URLs. + +* `cIconUrls` The number of items in `pIconUrls`. + +#### UpdateHostTitle + +Raised when the title of the page has been updated. + +> public HRESULT [UpdateHostTitle](#updatehosttitle)(ULONG ulCurrentEntryId, LPCWSTR pszTitle) + +###### Parameters +* `ulCurrentEntryId` The ID of the page in the visible-entries list that raised this event. + +* `pszTitle` The new title. + +#### UpdateSecureLockIcon + +Raised when security information of the page has changed. + +> public HRESULT [UpdateSecureLockIcon](#updatesecurelockicon)(ULONG ulCurrentEntryId, SECURELOCKICON secureLockIcon) + +###### Parameters +* `ulCurrentEntryId` The travel log entry for this change. + +* `secureLockIcon` The state of the security information. diff --git a/microsoft-edge/dualengine/reference/idualengine20browsersession.md b/microsoft-edge/dualengine/reference/idualengine20browsersession.md new file mode 100644 index 0000000000..c057f14dd2 --- /dev/null +++ b/microsoft-edge/dualengine/reference/idualengine20browsersession.md @@ -0,0 +1,303 @@ +--- +title: DualEngine Win32 C++ IDualEngine20BrowserSession +description: Represents an Internet Explorer process session. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/27/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, IDualEngine20BrowserSession +topic_type: +- APIRef +api_name: +- IDualEngine20BrowserSession +- IDualEngine20BrowserSession.CloneActiveTabRecoveryData +- IDualEngine20BrowserSession.CloneInactiveTabRecoveryData +- IDualEngine20BrowserSession.CreateDualEngineBrowser +- IDualEngine20BrowserSession.DeleteAllButRecoverableRecoveryFiles +- IDualEngine20BrowserSession.DeleteInactiveRegionRecoveryData +- IDualEngine20BrowserSession.GetRequestedHostForwardedAccelerators +- IDualEngine20BrowserSession.Initialize +- IDualEngine20BrowserSession.ParseEmieSitelist +- IDualEngine20BrowserSession.SetConfigurableSitesFlags +- IDualEngine20BrowserSession.SetHangDetectionMessages +- IDualEngine20BrowserSession.SetHostIntranetInInternetExplorer +- IDualEngine20BrowserSession.SetHybridMode +- IDualEngine20BrowserSession.SetReverseCookieSync +- IDualEngine20BrowserSession.SetSitePermissions +- IDualEngine20BrowserSession.SetUseAdditionalHangDetection +- IDualEngine20BrowserSession.ShowDownloadWindow +- IDualEngine20BrowserSession.SyncCookies +api_type: +- COM +api_location: +- ieframe.dll +--- + +# interface IDualEngine20BrowserSession + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +```cpp +interface IDualEngine20BrowserSession + : public IUnknown +``` + +Represents an Internet Explorer process session. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[CloneActiveTabRecoveryData](#cloneactivetabrecoverydata) | Duplicates an active tab's recovery data. +[CloneInactiveTabRecoveryData](#cloneinactivetabrecoverydata) | Duplicates an inactive tab's recovery data. +[CreateDualEngineBrowser](#createdualenginebrowser) | Creates a Browser object in this session. +[DeleteAllButRecoverableRecoveryFiles](#deleteallbutrecoverablerecoveryfiles) | Deletes all but the provided tab recovery data files. +[DeleteInactiveRegionRecoveryData](#deleteinactiveregionrecoverydata) | Deletes an inactive region's tab recovery data. +[GetRequestedHostForwardedAccelerators](#getrequestedhostforwardedaccelerators) | Returns a list of keyboard accelerators that should be forwarded from the Host. +[Initialize](#initialize) | Initializes the session. +[ParseEmieSitelist](#parseemiesitelist) | Parses the sitelist XML at the provided path. +[SetConfigurableSitesFlags](#setconfigurablesitesflags) | Sets flags that determine how configurable sites are handled. +[SetHangDetectionMessages](#sethangdetectionmessages) | Sets hang detection messages that will be sent to the session by the host to detect hangs. +[SetHostIntranetInInternetExplorer](#sethostintranetininternetexplorer) | Sets whether to open all Intranet sites in the session. +[SetHybridMode](#sethybridmode) | Sets whether to enable Hybrid Mode site list handling. +[SetReverseCookieSync](#setreversecookiesync) | Sets whether cookie changes are synced back to the host. +[SetSitePermissions](#setsitepermissions) | Sets site permissions for the session. +[SetUseAdditionalHangDetection](#setuseadditionalhangdetection) | Sets whether to enable additional hang detections. +[ShowDownloadWindow](#showdownloadwindow) | Shows the Internet Explorer download window. +[SyncCookies](#synccookies) | Sends cookie data to the session process. + +## Applies to + +Product |Introduced +--------- | --------- +Windows 10, Version 20H1 |KB5032278 +Windows 11, Version 22H2 |KB5032288 + +## Members + +#### CloneActiveTabRecoveryData + +Duplicates an active tab's recovery data. + +> public HRESULT [CloneActiveTabRecoveryData](#cloneactivetabrecoverydata)(HWND hwndBrowser, REFGUID guidSrcFile, REFGUID guidDestFile) + +###### Parameters +* `hwndBrowser` The HWND of the hosted browser window. + +* `guidSrcFile` The GUID for the source recovery data file to copy. + +* `guidDestFile` The GUID to associate with the new tab recovery data file. + +#### CloneInactiveTabRecoveryData + +Duplicates an inactive tab's recovery data. + +> public HRESULT [CloneInactiveTabRecoveryData](#cloneinactivetabrecoverydata)(REFGUID guidSrcFile, REFGUID guidDestFile) + +###### Parameters +* `guidSrcFile` The GUID for the source recovery data file to copy. + +* `guidDestFile` The GUID to associate with the new tab recovery data file. + +#### CreateDualEngineBrowser + +Creates a Browser object in this session. + +> public HRESULT [CreateDualEngineBrowser](#createdualenginebrowser)([IDualEngine20Browser](idualengine20browser.md) ** ppDualEngineBrowser) + +###### Parameters +* `ppDualEngineBrowser` The new Browser object. + +#### DeleteAllButRecoverableRecoveryFiles + +Deletes all but the provided tab recovery data files. + +> public HRESULT [DeleteAllButRecoverableRecoveryFiles](#deleteallbutrecoverablerecoveryfiles)(int cRecoverableGUIDs, LPCWSTR * rgpszRecoverableGUIDs) + +###### Parameters +* `cRecoverableGUIDs` The number of GUIDs in `rgpszRecoverableGUIDs`. + +* `rgpszRecoverableGUIDs` An array of GUIDs representing tab recovery data files that are not to be deleted. + +#### DeleteInactiveRegionRecoveryData + +Deletes an inactive region's tab recovery data. + +> public HRESULT [DeleteInactiveRegionRecoveryData](#deleteinactiveregionrecoverydata)(REFGUID guidTabId) + +###### Parameters +* `guidTabId` The GUID of the recovery data to delete. + +#### GetRequestedHostForwardedAccelerators + +Returns a list of keyboard accelerators that should be forwarded from the Host. + +> public HRESULT [GetRequestedHostForwardedAccelerators](#getrequestedhostforwardedaccelerators)(DWORD * pcAccels, [ACCELERATOR](accelerator.md) ** prgAccels) + +###### Parameters +* `pcAccels` The number of accelerators in `prgAccels`. + +* `prgAccels` A list of keyboard accelerators that should be forwarded. When finished the caller must free the memory allocated for the list with `CoTaskMemFree`. + +#### Initialize + +Initializes the session. + +> public HRESULT [Initialize](#initialize)(DWORD cAccels, [ACCELERATOR](accelerator.md) * rgHostPriorityAccels, [IDualEngine20BrowserSessionObserver](idualengine20browsersessionobserver.md) * pSessionObserver, LPCWSTR pszProfilePath, LPCWSTR pszProfileId) + +###### Parameters +* `cAccels` The number of accelerators in `rgHostPriorityAccels`. + +* `rgHostPriorityAccels` A list of keyboard accelerators to have the session forward to the host. + +* `pSessionObserver` An observer for events from this session. + +* `pszProfilePath` The path to host's profile path where the session will store relevant files. + +* `pszProfileId` The host's profile ID to associate with this session. + +#### ParseEmieSitelist + +Parses the sitelist XML at the provided path. + +> public HRESULT [ParseEmieSitelist](#parseemiesitelist)(LPCWSTR emieXmlPath) + +###### Parameters +* `emieXmlPath` Path to the sitelist XML to parse. + +#### SetConfigurableSitesFlags + +Sets flags that determine how configurable sites are handled. + +> public HRESULT [SetConfigurableSitesFlags](#setconfigurablesitesflags)(DualEngineConfigurableSitesFlags flags) + +###### Parameters +* `flags` The flags indicating how configurable sites are handled. + +#### SetHangDetectionMessages + +Sets hang detection messages that will be sent to the session by the host to detect hangs. + +> public HRESULT [SetHangDetectionMessages](#sethangdetectionmessages)(UINT uiSyncHungCheckMsg, UINT uiAsyncHungCheckMsg) + +###### Parameters +* `uiSyncHungCheckMsg` The window message ID of the message that the host will synchronously wait on to be handled. + +* `uiAsyncHungCheckMsg` The window message ID of the message that the host will asynchronously wait on. Browsers signal the host by calling [IDualEngine20BrowserObserver::OnAsyncHungCheckReply()](idualengine20browserobserver.md#onasynchungcheckreply). + +#### SetHostIntranetInInternetExplorer + +Sets whether to open all Intranet sites in the session. + +> public HRESULT [SetHostIntranetInInternetExplorer](#sethostintranetininternetexplorer)(BOOL fEnable) + +###### Parameters +* `fEnable` If `true`, navigation to Intranet sites will stay in the session; otherwise, whether a navigation will stay in the session or not follows default determination logic. + +#### SetHybridMode + +Sets whether to enable Hybrid Mode site list handling. + +> public HRESULT [SetHybridMode](#sethybridmode)(BOOL fEnable) + +###### Parameters +* `fEnable` If `true`, Hybrid Mode behavior is enabled when handling site list URLs; otherwise, normal navigation behavior occurs. + +#### SetReverseCookieSync + +Sets whether cookie changes are synced back to the host. + +> public HRESULT [SetReverseCookieSync](#setreversecookiesync)(BOOL fEnable) + +###### Parameters +* `fEnable` If `true`, the host will be notified of cookie changes by the [IDualEngine20BrowserSessionObserver::ReverseSyncCookies()](idualengine20browsersessionobserver.md#reversesynccookies) event; otherwise, it is not. + +#### SetSitePermissions + +Sets site permissions for the session. + +> public HRESULT [SetSitePermissions](#setsitepermissions)(SITE_PERMISSION_KIND sitePermissionKind, LPCWSTR pszPermissionData) + +###### Parameters +* `sitePermissionKind` The type of site permission that is being set. + +* `pszPermissionData` A serialized string of the permission data to set. + +`pszPermissionData` is a string in the following BNF format: +``` +permission-data = default-action CRLF site-permissions + +; Indicates the default action to take if there is no specific rule for the URI. +; DefaultAllow - Allow permission requests. +; DefaultAsk - Prompt the user for how they want to respond to the request. +; DefaultBlock - Block permission requests. +default-action = "DefaultAllow" | "DefaultAsk" | "DefaultBlock" + +; A list of sites and the action to take when permission is requested. +site-permissions = *(permission SP wildcard SP scheme-part SP host-part SP + port-part SP path-part CRLF) + +; Indicates the action to take on a request. +; A - Allow permission requests. +; Q - Prompt the user for how they want to respond to the request. +; B - Block permission requests. +permission = "A" | "Q" | "B" + +; Indicates if the host contains a domain wildcard. +wildcard = BIT + +; Can be either a specific scheme, a wildcard to match all schemes, or "!" to indicate no scheme. +scheme-part = "*" | "!" | scheme + +; Can be either a specific hostname or a wildcard to match all hostnames. +host-part = "*" | host + +; Represents a mostly typical URI host. +; The exception is that the host may start with a domain wildcard (e.g [*.]) which matches the host +; and any subdomains. +host = ([ subdomain-wildcard ] reg-name) | IPv4address | IP-literal +subdomain-wildcard = "[*.]" + +; Can be either a specific path or a wildcard to match all paths. +path-part = "*" | path + +; Can be either a specific port or a wildcard to match all ports. +port-part = "*" | port +port = *DIGIT + +; For definitions of the following rules, see RFC 3986 Appendix A (https://www.rfc-editor.org/rfc/rfc3986#appendix-A): +; scheme, reg-name, IPv4address, IP-literal, path +``` + +See also: + +* [Appendix A. Collected ABNF for URI](https://www.rfc-editor.org/rfc/rfc3986#appendix-A) in _RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax_. + +#### SetUseAdditionalHangDetection + +Sets whether to enable additional hang detections. + +> public HRESULT [SetUseAdditionalHangDetection](#setuseadditionalhangdetection)(BOOL fEnable) + +###### Parameters +* `fEnable` If `true`, additional hang detections will be enabled; otherwise, they will not. + +#### ShowDownloadWindow + +Shows the Internet Explorer download window. + +> public HRESULT [ShowDownloadWindow](#showdownloadwindow)() + +#### SyncCookies + +Sends cookie data to the session process. + +> public HRESULT [SyncCookies](#synccookies)(const [DualEngineCookie](dualenginecookie.md) * pCookies, DWORD cCookies) + +###### Parameters +* `pCookies` An array of cookies to be sent to the session. + +* `cCookies` The number of items in `pCookies`. diff --git a/microsoft-edge/dualengine/reference/idualengine20browsersessionobserver.md b/microsoft-edge/dualengine/reference/idualengine20browsersessionobserver.md new file mode 100644 index 0000000000..49b8cb4c28 --- /dev/null +++ b/microsoft-edge/dualengine/reference/idualengine20browsersessionobserver.md @@ -0,0 +1,86 @@ +--- +title: DualEngine Win32 C++ IDualEngine20BrowserSessionObserver +description: Receives events from the session. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/27/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, IDualEngine20BrowserSessionObserver +topic_type: +- APIRef +api_name: +- IDualEngine20BrowserSessionObserver +- IDualEngine20BrowserSessionObserver.NavigateDownloadLink +- IDualEngine20BrowserSessionObserver.ReverseSyncCookies +- IDualEngine20BrowserSessionObserver.UpdateDownloadState +api_type: +- COM +api_location: +- ieframe.dll +--- + +# interface IDualEngine20BrowserSessionObserver + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +```cpp +interface IDualEngine20BrowserSessionObserver + : public IUnknown +``` + +Receives events from the session. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[NavigateDownloadLink](#navigatedownloadlink) | Raised when the session Download window is requesting to navigate to a URL. +[ReverseSyncCookies](#reversesynccookies) | Raised when a cookie is set in the session, if reverse cookie sync is enabled. +[UpdateDownloadState](#updatedownloadstate) | Raised when downloads are stopped or started. + +## Applies to + +Product |Introduced +--------- | --------- +Windows 10, Version 20H1 |KB5032278 +Windows 11, Version 22H2 |KB5032288 + +## Members + +#### NavigateDownloadLink + +Raised when the session Download window is requesting to navigate to a URL. + +> public HRESULT [NavigateDownloadLink](#navigatedownloadlink)(BSTR url, VARIANT * PostData) + +###### Parameters +* `url` The URL that should be navigated to. + +* `PostData` HTTP POST data, such as form data. + +#### ReverseSyncCookies + +Raised when a cookie is set in the session, if reverse cookie sync is enabled. + +> public HRESULT [ReverseSyncCookies](#reversesynccookies)(const [DualEngineCookie](dualenginecookie.md) * pCookies, DWORD cCookies, ULONG ulCookieSyncVersion) + +See [IDualEngine20BrowserSession::SetReverseCookieSync](idualengine20browsersession.md#setreversecookiesync). + +###### Parameters +* `pCookies` The cookies that were set. + +* `cCookies` The number of cookies in `pCookies`. + +* `ulCookieSyncVersion` A number that can be used to correlate the specific cookie state with a navigation. + +#### UpdateDownloadState + +Raised when downloads are stopped or started. + +> public HRESULT [UpdateDownloadState](#updatedownloadstate)(BOOL fOnGoingDownloads) + +###### Parameters +* `fOnGoingDownloads` If `true`, the session has ongoing downloads; `false` if it does not. diff --git a/microsoft-edge/dualengine/reference/index.md b/microsoft-edge/dualengine/reference/index.md new file mode 100644 index 0000000000..859463fdf6 --- /dev/null +++ b/microsoft-edge/dualengine/reference/index.md @@ -0,0 +1,38 @@ +--- +title: DualEngine Win32 C++ Reference +description: DualEngine Win32 C++ Reference. The Microsoft DualEngine API enables you to host and control an Internet Explorer in your application. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode +ms.date: 12/27/2023 +--- +# DualEngine Win32 C++ Reference + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +The Microsoft DualEngine API enables you to host and control an Internet Explorer instance within your app. For more information, see [Introduction to the Microsoft DualEngine API](../intro.md) and [Getting started with the DualEngine API](../get-started.md). + +## Globals + +* [Globals](dualengine-idl.md) + +## Interfaces + +* [DualEngineSessionFactory](dualenginesessionfactory.md) +* [IDualEngine20BrowserSessionObserver](idualengine20browsersessionobserver.md) +* [IDualEngine20BrowserSession](idualengine20browsersession.md) +* [IDualEngine20BrowserObserver](idualengine20browserobserver.md) +* [IDualEngine20Browser](idualengine20browser.md) + +## Structs + +* [ACCELERATOR](accelerator.md) +* [CryptDataBlob](cryptdatablob.md) +* [DualEngineCookie](dualenginecookie.md) +* [DualEngineNewWindowOptions](dualenginenewwindowoptions.md) +* [tagSentinelEntryInfo](tagsentinelentryinfo.md) +* [VisibleListUpdateEntry](visiblelistupdateentry.md) diff --git a/microsoft-edge/dualengine/reference/tagsentinelentryinfo.md b/microsoft-edge/dualengine/reference/tagsentinelentryinfo.md new file mode 100644 index 0000000000..f9098bb459 --- /dev/null +++ b/microsoft-edge/dualengine/reference/tagsentinelentryinfo.md @@ -0,0 +1,50 @@ +--- +title: DualEngine Win32 C++ tagSentinelEntryInfo +description: Represents the position of the current region in the travel log. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/09/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, tagSentinelEntryInfo +topic_type: +- APIRef +api_name: +- tagSentinelEntryInfo +- tagSentinelEntryInfo.uiEntryCountAfterCurrentRegion +- tagSentinelEntryInfo.uiEntryCountBeforeCurrentRegion +api_type: +- COM +api_location: +- ieframe.dll +--- + +# struct tagSentinelEntryInfo + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +Represents the position of the current region in the travel log. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[uiEntryCountAfterCurrentRegion](#uientrycountaftercurrentregion) | The number of travel log entries after the region. +[uiEntryCountBeforeCurrentRegion](#uientrycountbeforecurrentregion) | The number of travel log entries before the region. + +## Members + +#### uiEntryCountAfterCurrentRegion + +The number of travel log entries after the region. + +> public UINT [uiEntryCountAfterCurrentRegion](#uientrycountaftercurrentregion) + +#### uiEntryCountBeforeCurrentRegion + +The number of travel log entries before the region. + +> public UINT [uiEntryCountBeforeCurrentRegion](#uientrycountbeforecurrentregion) + diff --git a/microsoft-edge/dualengine/reference/toc.yml b/microsoft-edge/dualengine/reference/toc.yml new file mode 100644 index 0000000000..a9de28bbb3 --- /dev/null +++ b/microsoft-edge/dualengine/reference/toc.yml @@ -0,0 +1,29 @@ +- name: DualEngine Win32 C++ Reference + href: index.md + items: + - name: DualEngineSessionFactory + href: dualenginesessionfactory.md + - name: IDualEngine20BrowserSessionObserver + href: idualengine20browsersessionobserver.md + - name: IDualEngine20BrowserSession + href: idualengine20browsersession.md + - name: IDualEngine20BrowserObserver + href: idualengine20browserobserver.md + - name: IDualEngine20Browser + href: idualengine20browser.md + - name: Structs + items: + - name: ACCELERATOR + href: accelerator.md + - name: CryptDataBlob + href: cryptdatablob.md + - name: Globals + href: dualengine-idl.md + - name: DualEngineCookie + href: dualenginecookie.md + - name: DualEngineNewWindowOptions + href: dualenginenewwindowoptions.md + - name: tagSentinelEntryInfo + href: tagsentinelentryinfo.md + - name: VisibleListUpdateEntry + href: visiblelistupdateentry.md diff --git a/microsoft-edge/dualengine/reference/visiblelistupdateentry.md b/microsoft-edge/dualengine/reference/visiblelistupdateentry.md new file mode 100644 index 0000000000..8bb8f1c538 --- /dev/null +++ b/microsoft-edge/dualengine/reference/visiblelistupdateentry.md @@ -0,0 +1,74 @@ +--- +title: DualEngine Win32 C++ VisibleListUpdateEntry +description: Represents a change to a travel log entry. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: windows-integration +ms.date: 12/09/2023 +keywords: dual engine, dualengine, iemode, win32 apps, win32, edge, ie mode, edge html, VisibleListUpdateEntry +topic_type: +- APIRef +api_name: +- VisibleListUpdateEntry +- VisibleListUpdateEntry.fIsFrameEntry +- VisibleListUpdateEntry.operation +- VisibleListUpdateEntry.pszTitle +- VisibleListUpdateEntry.pszUrl +- VisibleListUpdateEntry.ulEntryId +api_type: +- COM +api_location: +- ieframe.dll +--- + +# struct VisibleListUpdateEntry + +> [!IMPORTANT] +> The DualEngine API is a limited access feature. Contact dualengineapiaccess@microsoft.com for more information. + +Represents a change to a travel log entry. + +## Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +[fIsFrameEntry](#fisframeentry) | Indicates whether the entry was for a subframe. +[operation](#operation) | The type of change. +[pszTitle](#psztitle) | The page title of the entry. +[pszUrl](#pszurl) | The URL of the entry. +[ulEntryId](#ulentryid) | The ID of the entry. + +## Members + +#### fIsFrameEntry + +Indicates whether the entry was for a subframe. + +> public BOOL [fIsFrameEntry](#fisframeentry) + +#### operation + +The type of change. + +> public VisibleEntryUpdateOperation [operation](#operation) + +#### pszTitle + +The page title of the entry. + +> public LPWSTR [pszTitle](#psztitle) + +#### pszUrl + +The URL of the entry. + +> public LPWSTR [pszUrl](#pszurl) + +#### ulEntryId + +The ID of the entry. + +> public ULONG [ulEntryId](#ulentryid) + diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index e6059cb067..1caa26e7de 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -1149,7 +1149,7 @@ # if top-of-page title is longer, add it to displayName comma-delimited list of lookup keywords - name: WebView2 items: - - name: Introduction to Microsoft Edge WebView2 # existing firstchild article + - name: Introduction to Microsoft Edge WebView2 href: webview2/index.md displayName: @@ -1677,6 +1677,30 @@ href: accessibility/test.md displayName: +#============================================================================== +# DualEngine + - name: DualEngine + items: + - name: Introduction to the Microsoft DualEngine API + href: dualengine/intro.md + displayName: Internet Explorer + + - name: Getting started with the DualEngine API + href: dualengine/get-started.md + displayName: + + - name: Creating a DualEngine adapter plugin DLL + href: dualengine/concepts/adapter-dll.md + displayName: + + - name: Launching Internet Explorer + href: dualengine/concepts/launching-internet-explorer.md + displayName: + + - name: DualEngine Win32 C++ Reference + href: dualengine/reference/index.md + displayName: functions, methods + # ============================================================================= # bottom leaf nodes - name: Videos about web development with Microsoft Edge