Presentations of browsers



Developing a new experience enabled desktop browserMarch 14, 2014AbstractWindows 8.1 introduces a new programming paradigm. Windows Store apps offer a clean, polished user experience that push app experiences to the forefront, and immerse the user in a full screen environment that’s tailored to the user’s hardware and context. Windows 8.1 continues to offer desktop app experiences as found in previous versions of Windows. In Windows 8.1, the browser that the user sets as the default for handling webpages and associated protocols may be designed to access both new experiences as well as the traditional desktop experience. This type of browser is the new experience enabled desktop browser. This guide describes how to create such a browser. The information in this document applies specifically to browsers that will be made available to end-users as the default viewer for the http:// protocol and associated web pages and protocols on the x86/64 architecture.This information applies to the following operating systems:Windows 8.1Disclaimer: This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet website references, may change without notice. Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. You bear the risk of using it.This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes. ? 2014 Microsoft. All rights reserved.Contents TOC \o "1-3" \h \z \u Presentations of browsers PAGEREF _Toc382572560 \h 4User experience framing PAGEREF _Toc382572561 \h 4Implementation PAGEREF _Toc382572562 \h 5Installation PAGEREF _Toc382572563 \h 5Sample VisualElementsManifest.xml file PAGEREF _Toc382572564 \h 6Manifest schema PAGEREF _Toc382572565 \h 7Register an application user model ID (AppUserModelID) PAGEREF _Toc382572566 \h 9Declare a square tile for the Start screen PAGEREF _Toc382572567 \h 9Declare a splash screen logo PAGEREF _Toc382572568 \h 9Becoming the default browser PAGEREF _Toc382572569 \h 10Tiles PAGEREF _Toc382572570 \h 10Pinning secondary tiles PAGEREF _Toc382572571 \h 11Activation (launch) PAGEREF _Toc382572572 \h 11Contextual launch PAGEREF _Toc382572573 \h 12Launching vs. switching PAGEREF _Toc382572574 \h 13Activating the new experience enabled desktop browser for file and protocol contracts PAGEREF _Toc382572575 \h 14Invocation into desktop presentation PAGEREF _Toc382572576 \h 14Launching other apps via protocols PAGEREF _Toc382572577 \h 15Handling system activation on background session close PAGEREF _Toc382572578 \h 16Boot to desktop preferences PAGEREF _Toc382572579 \h 16View size preference PAGEREF _Toc382572580 \h 17Monitor preference PAGEREF _Toc382572581 \h 20Store app identification PAGEREF _Toc382572582 \h 22Search PAGEREF _Toc382572583 \h 22Windowing PAGEREF _Toc382572584 \h 23UI framework guidance PAGEREF _Toc382572585 \h 24Guidance for multi-process browsers PAGEREF _Toc382572586 \h 24Touch keyboard PAGEREF _Toc382572587 \h 25App contracts PAGEREF _Toc382572588 \h 25Search contract PAGEREF _Toc382572589 \h 26Share contract PAGEREF _Toc382572590 \h 26Play To contract PAGEREF _Toc382572591 \h 26Print contract PAGEREF _Toc382572592 \h 27Process lifetime management PAGEREF _Toc382572593 \h 27Close gesture PAGEREF _Toc382572594 \h 27Closing background sessions and cleaning up private browsing data PAGEREF _Toc382572595 \h 28Completing downloads and uploads prior to suspend PAGEREF _Toc382572596 \h 28Roaming browser application data PAGEREF _Toc382572597 \h 29Register for roaming PAGEREF _Toc382572598 \h 30Sync behavior PAGEREF _Toc382572599 \h 30PC setting for web browser syncing PAGEREF _Toc382572600 \h 30Receiving window messages PAGEREF _Toc382572601 \h 31Syncing favorites / Internet shortcuts PAGEREF _Toc382572602 \h 31Syncing typed URLs PAGEREF _Toc382572603 \h 32Syncing browser history PAGEREF _Toc382572604 \h 33Syncing tabs PAGEREF _Toc382572605 \h 35Roaming other registry settings PAGEREF _Toc382572606 \h 36Windows Runtime API reference PAGEREF _Toc382572607 \h 37Presentations of browsersThe desktop browser ecosystem is well established. Users expect popular Windows 7 desktop browsers to continue to work on Windows 8.1, and they do. Beyond the desktop, Windows 8.1 introduces a new app programming model, which enables development of touch optimized apps. With this new model, apps have maximized battery life, better reliability, improved privacy and security for devices like GPS, and they handle system start up and shutdown without changing state or impacting other apps. These apps take on the enhanced new look and feel of Windows 8.1, and integrate with the richness of the PC via contracts. In Windows, a web browser can be built as a Windows Store app, a desktop app, or a new experience enabled desktop browser. Windows Store app. A Windows Store app adheres to the principles of the new app model– it runs in an App Container, uses APIs found in the Windows Software Development Kit (SDK) for Windows Store apps, is packaged as an .appx file, and is made available via the Windows Store.Desktop browsers. Same model as Windows 7.New experience enabled desktop browser. A desktop browser that participates in the new experience when the user wants the browser to do so. Such a browser can provide HTML5 rendering for webpages and service HTTP / HTTPS requests. By definition, such a browser has full access to Win32 APIs for rendering HTML5, including the ability to use multiple background processes, JIT compiling, and other distinctly browser-related functionality (like background downloading of files). Desktop browsers typically run at medium or low integrity level.This guide focuses on developing a new experience enabled desktop browser.User experience framingThese design and user experience principles give an outline for thinking about web browsers in Windows 8.1:The user is in control of browser preference. Browser choice is a personal preference, and Windows 8.1 continues to honor user selection. Users can select the default via a “new app installed” system notification, and they can also configure via other means, such as Set Your Default Programs (SYDP). There is only one default browser on the system. Any and all browsers can register their intent to be considered as the default http:// protocol and the other consolidated attributes, which define a browser in SYDP. The user can select one browser as the default. This is the same model as Windows 7. A new experience enabled desktop browser can participate in the new user experience only if it’s the default browser. Desktop apps (typically packaged as .MSI, medium integrity level) run in the desktop. Windows Store apps (.appx packaged, run in App Containers, API set restricted to the Windows SDK for Windows Store apps, acquired via the Windows Store) run in the new experience. You can think of a new experience enabled desktop browser as a desktop browser that can also participate in the new experience. The restriction to limit new user experience participation to the user’s default browser is rooted in preserving the new user experience. Note that this limitation applies to all browsers, including Internet Explorer.ImplementationThe following sections detail the design and code required to build a new experience enabled desktop browser.TechnologyDescription InstallationUpdate installation code to create correctly formatted tiles, splash screen, and other associated content that tells the system the browser is a new experience enabled desktop browser.Becoming the default browserUnderstand the changes to how users select file and protocol handlers for apps in Windows.TilesProvide a square tile for the Start screen and implement execute commands for secondary tile invocation.Activation (launch)Implement the app activation contract to launch the browser in the new user experience.WindowingUnderstand the rules governing window creation in the new user experience.App contractsImplement and participate in app contracts: Search, Share, Play To, and Print.Process lifetime managementSave and restore state in the new user experience.Roaming browser application dataKeep browser app data (e.g. settings) synchronized between multiple Windows 8.1 devices.Windows Runtime API referenceA subset of Windows Runtime APIs are available to use by new experience enabled desktop browsers.Note: For some of the new experience enabled desktop browser integration points, you might need to write browser code that calls into Windows Runtime objects. This is particularly true for the new presentation of the browser and app contract integration. For the new experience portions of the browser, you need a developer tool with C++11 support to provide support for the async pattern, which is prevalent in Windows Runtime use. Microsoft Visual Studio 11 Express has this level of support. You can download it from the Windows Store apps Dev Center. InstallationNo change is required to browser discovery and acquisition mechanisms: New experience enabled desktop browsers may be distributed via existing channels, for example, web download, network share, OEM pre-install, or systems management software.New experience enabled desktop browsers may be deployed via existing desktop app deployment methods, for example, MSI packaged, Click-Once installer, or .zip archive extraction with file copy.Note: We strongly recommend that you digitally sign all the installation executables. This includes those that might be used as “bootstrap files” during a Click-Once installation, with an Authenticode Certificate issued by a Certificate Authority (CA) that is a member of the Windows Root Certificate Program. For more info about this best practice and the role of Windows SmartScreen in Windows 8.1, see Protecting you from malware.However, Windows must be able to identify that a browser is a new experience enabled desktop browser, otherwise the operating system assumes the browser is desktop-capable only and treats it accordingly. This means no interaction with the new user experience. A new experience enabled desktop browser must perform the following:Author a “VisualElementsManifest.xml” file that adheres to the schema and example included in this document.Include the .xml file as part of the new experience enabled desktop browser’s installation contents.Include the supporting files as referenced by the .xml file (e.g. tile logo, splash screen images, Resources.PRI file) as part of the new experience enabled desktop browser’s installation contents.During installation, copy the .xml file to the same directory as the browser executable.C:\Program Files\YourBrowser\browser.exeC:\Program Files\YourBrowser\VisualElementsManifest.xmlDuring installation, copy the supporting files to the same directory as the browser executable (or relative to it). C:\Program Files\YourBrowser\browser.exeC:\Program Files\YourBrowser\VisualElementsManifest.xmlC:\Program Files\YourBrowser\logo.jpgC:\Program Files\YourBrowser\logosmall.jpgC:\Program Files\YourBrowser\imagefile.jpgC:\Program Files\YourBrowser\Resources.PRINote: If you want to update the resources associated with the browser after the initial install (for example: during an update), you must also update the app’s shortcut timestamp. This signals Windows to reread and reload the visual elements.During installation, create a Start shortcut to your app populated with the following properties:PKEY_AppUserModel_IsDualMode set as TRUE (VT_BOOL)PKEY_AppUserModel_ID set as the browser’s AppUserModelID (VT_LPWSTR). For additional info relevant to this specific property, see Register an Application User Model ID (AppUserModelID), later in this document.Sample VisualElementsManifest.xml file<Application xmlns:xsi=""> <VisualElements DisplayName="displayname" Logo="logo.jpg" SmallLogo="logosmall.jpg" ForegroundText="light" BackgroundColor="blue"> <DefaultTile ShortName="shortname" ShowName="allLogos" /> <SplashScreen Image="imagefile.jpg" /> </VisualElements></Application>Note: Windows uses the DisplayName attribute under /Application/VisualElements for the tile and splash screen. The BackgroundColor value under /Application/VisualElements is also used as the background color of the SplashScreen.For more info about the property values, see Default Tile.Manifest schemaThe following XSD is used to validate your VisualElementsManifest.xml file:<?xml version="1.0" encoding="utf-8"?> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs=""> <xs:simpleType name="st_nonemptystring"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="32767"/> <xs:pattern value="[^\s]|([^\s].*[^\s])"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="st_shortdisplayname"> <xs:restriction base="st_nonemptystring"> <xs:pattern value="ms-resource:.{1,256}"/> <xs:pattern value=".{1,13}"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="st_displayname"> <xs:restriction base="st_nonemptystring"> <xs:pattern value="ms-resource:.{1,256}"/> <xs:pattern value=".{1,256}"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="st_filenamecharset"> <xs:restriction base="st_nonemptystring"> <xs:pattern value=&quot;[^&lt;&gt;&quot;:%\|\?\*]+&quot;/> </xs:restriction> </xs:simpleType> <xs:simpleType name="st_filename"> <xs:restriction base="st_filenamecharset"> <xs:pattern value="([^/\\]*[^./\\]+)(\\[^/\\]*[^./\\]+)*"/> <xs:pattern value="([^/\\]*[^./\\]+)(/[^/\\]*[^./\\]+)*"/> <xs:maxLength value="256"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="st_imagefile"> <xs:restriction base="st_filename"> <xs:pattern value=".+\.((jpg)|(png)|(jpeg))"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="st_color"> <xs:restriction base="xs:string"> <xs:pattern value="#[\da-fA-F]{6}"/> <xs:pattern value="black|silver|gray|white|maroon|red|purple|fuchsia|green|lime|olive|yellow|navy|blue|teal|aqua"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="st_foregroundtext"> <xs:restriction base="xs:string"> <xs:enumeration value="light"/> <xs:enumeration value="dark"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="st_showname"> <xs:restriction base="xs:string"> <xs:enumeration value="allLogos"/> <xs:enumeration value="noLogos"/> <xs:enumeration value="logoOnly"/> <xs:enumeration value="wideLogoOnly"/> </xs:restriction> </xs:simpleType> <xs:complexType name="ct_defaulttile"> <xs:attribute name="ShortName" type="st_shortdisplayname" use="optional"/> </xs:complexType> <xs:complexType name="ct_splashscreen"> <xs:attribute name="Image" type="st_imagefile" use="required"/> </xs:complexType> <xs:complexType name="ct_visualelements"> <xs:all> <xs:element name="DefaultTile" type="ct_defaulttile" minOccurs="0"/> <xs:element name="SplashScreen" type="ct_splashscreen"/> </xs:all> <xs:attribute name="DisplayName" type="st_displayname" use="required"/> <xs:attribute name="Logo" type="st_imagefile" use="required"/> <xs:attribute name="SmallLogo" type="st_imagefile" use="required"/> <xs:attribute name="ForegroundText" type="st_foregroundtext" use="required"/> <xs:attribute name="BackgroundColor" type="st_color" use="required"/> </xs:complexType> <xs:complexType name="ct_application"> <xs:all> <xs:element name="VisualElements" type="ct_visualelements" /> </xs:all> </xs:complexType> <xs:element name="Application" type="ct_application" /> </xs:schema> Register an application user model ID (AppUserModelID)A new experience enabled desktop browser must register an explicit Application User Model ID (AppUserModelID) for itself. This ID must be provided under the progID registered with SYDP. The AppUserModelID cannot be longer than 64 characters. When running in the new experience, this AppUserModelID is immutable by the running browser process.The AppUserModelID should be specified in the shortcut properties for the app as created during installation. For more info about assigning an AppUserModeID, see Where to Assign an AppUserModelID in Application User Model IDs. Note: New experience enabled desktop browsers should not set an AppUserModelID at runtime when participating in the new user experience (browsers may continue to do so when activating in the desktop). This is not supported in the new experience and can lead to unpredictable behavior.Declare a square tile for the Start screen During installation, a new experience enabled desktop browser must communicate the details of its app tile. Include these tile assets:Square tile logoAt 1x (.75x and 1.4x plateaus are optional but highly recommended)Small logoBackground colorForeground text valueShort name (optional – use only if the display name is too long to fit on a the tile on the Start screen) Declare a splash screen logoDuring installation, a new experience enabled desktop browser must communicate the details of its splash screen logo. This is a png, jpg, or jpeg and must be specified at .75x, 1x, and 1.4x plateaus. These images must occur within a Package Resource Index (PRI). The PRI may be created using free tools included with the Windows Software Development Kit (SDK) for Windows Store apps.For more info about PRI, review the documentation for the ResourceManager Class. Becoming the default browserBrowser registration must follow the best practices outlined on MSDN. For more information, see Default Programs. Upon installation, Windows presents the user with a system notification that enables selection of the browser as the system default. This notification appears when these conditions are met:The browser installer calls SHChangeNotify with the SHCNE_ASSOCCHANGED flag to tell Windows that new protocol handlers have been registered. Windows detects that one or more new apps have registered to handle both http:// and https:// protocols and the user has not been notified yet. In other words, none of the following have been shown to the user: system notification advertising the app, OpenWith flyout containing the app, Set Your Default Programs (SYDP) Control Panel page for the app.SAMPLE: Recommended code for registration// Recommended registration code to run after the registry keys were written by the installation program:void NotifySystemOfNewRegistration(){ // Notify the system that my new association choices are available SHChangeNotify(SHCNE_ASSOCCHANGED, SHCNF_DWORD | SHCNF_FLUSH, nullptr, nullptr); // Wait for system processes to handle the notification Sleep(1000);}NOTE: The SHChangeNotify message (along with allowing time for system processes to handle the notification) is required to ensure proper functioning of system defaults.Dismissing or ignoring the notification and/or dismissing the flyout without making a selection results in the default browser remaining unchanged. The user may also change the default browser via other operating system mechanisms, including SYDP.TilesIn Windows, the start menu has been replaced by a Start screen of tiles.If the default browser supports the new user experience, the browser’s app tile (and secondary tiles, if they exist) show up in the Start screen in a manner similar to Windows Store apps (as defined by properties that were specified in the .XML manifest that was copied during browser installation). Otherwise, the tile appears as a desktop app. Verbs appropriate to the new user experience and desktop mode of the app appear on the tile. The tile appears in search results like any other tile. Other tile actions (re-arrange, pin/unpin, etc.) are no different for browsers than they are for other app tiles.The default new experience enabled desktop browser always appears as a square tile. Any secondary tiles belonging to the default new experience enabled desktop browser also appear with new user experience tile visuals.Pinning secondary tilesSecondary tiles enable users to promote interesting content and deep links – for example, a reference to a specific location inside of the pinning app – from Windows Store apps onto the Start screen. A typical use of secondary tiles by a new experience enabled desktop browser might involve surfacing the ability to create a tile that represents a link to a particular website important to the user, e.g. a “favorite”. For more info about using secondary tiles, see Secondary tiles overview. A new experience enabled desktop browser can pin secondary tiles while running in the new user experience. These tiles are associated with the app that created them (the new experience enabled desktop browser), the same as any other secondary tile.While the secondary tiles’ parent new experience enabled desktop browser app is the current default browser, those secondary tiles launch in the new user experience and have new visuals. If their parent app is no longer the default browser, those secondary tiles are treated the same as any desktop tile.The system examines the Application User Model ID of the app to verify the calling app is the current default browser. The app supplied arguments are stored in the shortcut and supplied in the Arguments field of the LaunchActivatedEvent.All attempts to call the secondary tiles APIs from any browser running in desktop mode fail.Activation (launch)New experience enabled desktop browsers are capable of activating in both the desktop and the new user experience (the latter only when configured as the default browser). To support desktop activation, no changes are necessary. To support new user experience activation, changes are required.These rules govern app activation:Desktop shortcuts, pinned taskbar icons, and other “desktop artifacts” activate the new experience enabled desktop browser in the desktop.Tiles in the Start screen activate the browser in the new user experience when the browser is the default. When the browser is not the default, tiles activate the browser in the desktop. This same behavior also applies to a browser’s secondary tiles.Browsers that want to activate in the new user experience for file and protocol contracts must call IApplicationActivationManager::ActivateForFile or IApplicationActivationManager::ActivateForProtocol in the implementation of their verb handler. Verb handlers must be implemented as a DelegateExecute handler. For more info about verb handling, see the FileActivatedEventArgs.Verb property.We recommend that browsers implement “contextual launching.” This means taking the calling app’s presentation (desktop or new user experience) into account when determining the browser’s presentation (desktop or new user experience) for activations originating from other apps, such as when a user clicks an http:// link in their mail app.Search contract activations always activate in the new user experience. These activations can only occur if the browser is the user’s default. For more info, please see the Search contract section of this document.Contextual launchUsers expect a seamless experience when activating a browser via a link; for example, launching a browser by clicking on an http:// link in a mail or messaging app. When following a link within a Windows Store app, most users expect a new experience presentation of the linked content. Conversely, when following a link from a desktop app, most users expect a desktop style presentation of the linked content.When the browser is activated, use the IExecuteCommandHost::GetUIMode() method to obtain the current UI context of the app or system component where the browser’s activation originated. In other words, this indicates the UI context of the caller of the launching API. The context is provided by the site chain, service ID SID_ExecuteCommandHost and IExecuteCommandHost::GetUIMode(). Use this information to provide the best browser presentation. // site is the site pointer provided to the shell verb implementation// via IObjectWithSite::SetSite().bool IsImmersiveLauncher(IUnknown *site){ ComPtr<IExecuteCommandHost> commandHost; EC_HOST_UI_MODE hostUIMode; return SUCCEEDED(IUnknown_QueryService(site, SID_ExecuteCommandHost, IID_PPV_ARGS(&commandHost))) && SUCCEEDED(commandHost->GetUIMode(&hostUIMode)) && (hostUIMode != ECHUIM_DESKTOP);}The enumeration has three values:ECHUIM_DESKTOP – Desktop app launchECHUIM_IMMERSIVE – New experience app launchECHUIM_SYSTEM_LAUNCHER – Start menu launch (includes Tile activation, typing a URL into the search box in the Start screen, etc.)We recommend that browsers provide a configurable setting to give users control over their preferred presentation experience. For example, a setting named “Choose how you open links”, with options a) Always launch the new experience, b) Always launch in the desktop, c) Let the browser decide, aka contextual (suggested default). Follow these steps to implement contextual launch:Author a DelegateExecute verb handler that implements IExecuteCommand, IObjectWithSite, IInitializeCommand, IObjectWithSelection, and IExecuteCommandApplicationHostEnvironment.Register the handler in the registry under HKCR\{browser desktop AppID}\.exeAny shortcut that contains a PKEY_AppUserModel_ID value causes Windows to first look for a verb handler registered for the shortcut’s target’s type registered under the AppUserModelID. Browser shortcuts point at the browser’s executable file and thus must be registered for the ‘.exe’ type under the AppUserModelID. When the verb is invoked, it’s provided with the shortcut’s target and any arguments stored in the link (this includes arguments specified in secondary tiles). During launch, the implementation of IExecuteCommandApplicationHostEnvironment::GetValue is called. The browser should return which presentation to launch in, but it will likely need more information in order to make this determination.Use IUnknown_QueryService(_pSite, SID_ExecuteCommandHost, …) to obtain the IExecuteCommandHost implementation.Call IExecuteCommandHost::GetUIMode to discover the launch context. Use this information, along with the user configurable preference and information such as that provided to IInitializeCommand and IObjectWithSelection, to determine the presentation, either desktop or new experience. Return the value from the IExecuteCommandApplicationHostEnvironment::GetValue call. Return AHE_IMMERSIVE from the implementation of GetValue only if the browser is configured as the user’s default.In all launch cases except those initiated from a tile on the Start screen, the browser’s IExecuteCommand::Execute handler gets called and the browser must fully handle activation. In the case of the tile on the Start screen, if IExecuteCommandApplicationHostEnvironment::GetValue returns AHE_IMMERSIVE, Windows finishes activation of the browser in order to provide a consistent launch animation. IExecuteCommand::Execute is not called in this case.Register the DelegateExecute handler.The following is an example of the registry entry:HKCR\Example.Browser\.exe\shell\(Default) = “open”open\command(Default) = “”DelegateExecute = “{1e1946d6-5e51-4548-b7e8-033c60abffaf}”In this example, “{1e1946d6-5e51-4548-b7e8-033c60abffaf}” is a handler CLSID that the browser provided.Launching vs. switchingIn the desktop case, it’s a common occurrence for the browser to already be running when a user attempts to activate it via the Start screen tile or file / protocol activation. Rather than creating a separate new instance of the browser for each activation, you should use the DelegateExecute handler to communicate with a running instance of the browser.It’s recommended that browsers support, at a minimum, the “open” verb. Also, when a user chooses Open new window, the browser should open a new tab rather than a new instance of the browser. Browsers are suggested to implement a verb, e.g. “open new window,” corresponding to that common user action.For more info about setting a state or parameter related to a verb or invoking the verb, see IExecuteCommand interface. Activating the new experience enabled desktop browser for file and protocol contractsBrowsers should implement their file and protocol associations as Execute Command verbs (see the Execute Command Verb Sample for an example) in a manner similar to tile launch. When directing the verb invocation into the new user experience, browsers call a method on IApplicationActivationManager to activate in the new user experience for the File or Protocol contract. The Application Activation Manager is a COM component identified by CLSID_ApplicationActivationManager. interface IApplicationActivationManager : IUnknown{ …HRESULT ActivateForFile( [in] LPCWSTR appUserModelId, [in] IShellItemArray *itemArray, [in, unique] LPCWSTR verb, [out] DWORD *processId);HRESULT ActivateForProtocol( [in] LPCWSTR appUserModelId, [in] IShellItemArray *itemArray, [out] DWORD *processId); }The ActivateApplicationForFile and ActivateApplicationForProtocol methods accept an IShellItemArray, which is the input to DelegateExecute verb implementations via IObjectWithSelection::SetSelection. Note that IAplicationActivationManager API only works from medium integrity level processes (High IL will not work). Therefore, it is recommended that this object is created along with CLSCTX_LOCAL_SERVER as this object is registered to run in the DLLHOST surrogate at Medium IL.Invocation into desktop presentation New experience enabled desktop browsers must set an AppUserModelID at runtime when running in desktop mode by calling SetCurrentProcessExplicitAppUserModelId and providing the value specified under PKEY_AppUserModel_ID in the browser’s primary tile. This ensures that the AppUserModelID “link” between tiles and the new experience enabled desktop browser is preserved. Additionally, be aware that because secondary tiles are associated with the AppUserModelID of the browser’s primary tile, the browser must have the same runtime AppUserModelID as its primary tile. When activating into the new experience presentation, SetCurrentProcessExplicitAppUserModelId has no effect and therefore should not be called.Note: If the new experience enabled desktop browser is not currently selected as the user’s default browser, it can only launch in the desktop. Launching other apps via protocolsIt’s common for web browsers to support launching apps through the windows file and URI scheme (sometimes referred to as protocols) association system using the ShellExecuteEx() API. We recommend that browsers use the AssocIsDangerous() API to safely handle activation of other apps on the system. We also recommend that browsers provide a consistent, predictable user experience when users select protocol links that cause the activation of a different Windows app. The AssocIsDangerous() API identifies file types that have potentially dangerous content, including the ability to run code. Browsers should discourage users from launching programs that are identified as dangerous by this API or mitigate the threats using the attachment execution services (AES) API. Here are some best practices: Use ShellExecuteEx() to launch the file types and URI schemes that aren’t natively handled by the browserVerify the source and integrity of files using digital signatures Verify the reputation of the particular file Inform the user about what app will be launched to handle the file or URI Require the user to confirm that the source of the launch is allowed to perform the action ShellExecuteEx() has been extended to report information to the caller about the identity of the app to be activated. The API provides the name of the process or CLSID of the handler to be launched, the name of the app, and the publisher name and icon. Use this information when constructing a user consent dialog, or when evaluating per app policy as managed by browser-specific settings. Consistent with the guidance in the Contextual Launch section of this document, we recommend that browsers provide a configurable setting to give users greater awareness of the presentation experience of the to-be-invoked app. For example, use the information gathered by the extended ShellExecuteEx() API to populate a contextually appropriate dialog. In that dialog, indicate to the user what app will be launched and whether that app uses new experience or desktop presentation. The CLSID can be used to distinguish Windows Store apps from desktop apps. Windows Store apps use CLSID_AppShellVerbHandler.Lastly, for ShellExecuteEx() error cases, browsers must ensure that any resulting error dialogs remain visible to the user. For example, if the browser is participating in the new experience and tries a file launch of a 64-bit executable on a 32-bit capable machine (an error condition), it’s possible that the error dialog from the ShellExecuteEx() call is displayed on the desktop. This is a problem because the browser cannot automatically switch focus to the desktop, which means the error dialog is hidden from the user’s view. New experience enabled desktop browsers must either disable the error UI by specifying SEE_MASK_FLAG_NO_UI (and handle the failure themselves) or specify SHELLEXECUTEINFO.lpClass = “Unknown” and lpVerb = “InvokeDefaultVerbInOtherProcess” in calls to ShellExecuteEx()In-proc vs. Out-of-proc Activation Handling.You can implement the COM components that handle browser launch (the previous sections) either in-proc or out-of-proc. In the in-proc case, a process provided by the system loads the browser’s COM components. In Windows 8.1, this process is openwith.exe. This process isn’t likely to be already running;?therefore, the time it takes for openwith.exe itself to launch adds to the activation time of the browser. NOTE: To debug your code that executes in-proc to this system-provided process, attach a debugger to openwith.exe. In the out-of-proc case, the COM components that handle browser launch are implemented and hosted in the browser’s own binary, most likely the browser’s frame process. In most cases, starting the system-provided process is faster than starting the browser’s binary. But a browser could potentially see a performance benefit with an out-of-proc implementation in launch cases where the browser happens to already be running. For example, if the user opens a desktop window with the browser configured as the default, switches to a Windows Store app, and then selects a link from within that app that redirects to an http:// address, the browser’s binary hosting the COM components is already running (the desktop browser window instance). In this example, choosing an out-of-proc implementation would likely result in a slightly slower initial browser launch case, but the subsequent re-activation would likely be faster than similar in-proc implementations because the small additional overhead is needed to start the system-provided process.Handling system activation on background session closeAs detailed in the section Closing background sessions and cleaning up private browsing data, there are circumstances where the system activates the browser. Browsers must handle this activation mechanism. NOTE: In this activation case, the browser’s executable is directly invoked as a desktop process with –BackgroundSessionClosed added as a command line parameter. As such, handling of this parameter must happen in the browser executable’s startup sequence and not in the IExecuteCommand verb handler.Boot to desktop preferencesBrowsers may (optionally) choose to provide alternate behaviors in the new experience when the system is configured to immediately boot to the desktop when a user logs in. For example, a browser may choose to show the address bar automatically, on the presumption that the user is likely to be using a mouse and keyboard when the system is configured in this way. Browsers may detect this configuration by evaluating the following registry key and value:HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\StartPageWhen the following value is set, the system will boot to the desktop when a user logs in:“OpenAtLogon”=dword:00000000View size preferenceBoth the source app and target app in an app activation sequence may (optionally) specify preferences that help determine how the two apps are arranged on screen. When the browser is the source (meaning the browser wants to activate another app), set the source size preference interface on the site chain before calling Activation Manager to launch an app. When the browser is the target (meaning the browser is being launched by another app), set the target view size preference interface on the site chain before calling activation manager to activate the browser app. The browser can do this because the activation sequence first goes through the browser’s IExecuteCommand handler.// Implemented by browser (source app), which uses// CLSID_ApplicationActivationManager to launch a Window Store app// (target app). The object that implements ILaunchSourceViewSizePreference// must be set on the site chain of CLSID_ApplicationActivationManager before// any method on IApplicationActivationManager is called. The size preference// information is used by Windows in placing the source app window after// the target app is shown on screen.interface ILaunchSourceViewSizePreference : IUnknown{ HRESULT GetSourceViewToPosition([out] HWND *hwnd); HRESULT GetSourceViewSizePreference([out] APPLICATION_VIEW_SIZE_PREFERENCE *sourceSizeAfterLaunch);}// This enum exactly matches the WinRT enum Windows.UI.ViewManagement.ViewSizePreference.typedef [v1_enum] enum APPLICATION_VIEW_SIZE_PREFERENCE{ AVSP_DEFAULT = 0, AVSP_USE_LESS = 1, AVSP_USE_HALF = 2, AVSP_USE_MORE = 3, AVSP_USE_MINIMUM = 4, AVSP_USE_NONE = 5,} APPLICATION_VIEW_SIZE_PREFERENCE;// Implemented by a browser and set on the site chain of// CLSID_ApplicationActivationManager when the browser's IExecuteCommand// handler receives the invocation and is about to call// IApplicationActivationManager to launch itself. Windows // uses the size preference information to decide how the browser window// should be shown after it’s launched.interface ILaunchTargetViewSizePreference : IUnknown{ HRESULT GetTargetViewSizePreference([out] APPLICATION_VIEW_SIZE_PREFERENCE *targetSizeOnLaunch);}Example: The browser launches another app and requests that the browser not remain on screen. class CLaunchSourceViewSizePreference : public Microsoft::WRL::RuntimeClass< Microsoft::WRL::RuntimeClassFlags<Microsoft::WRL::RuntimeClassType::ClassicCom>, IServiceProvider, ILaunchSourceViewSizePreference>{public: CLaunchSourceViewSizePreference() : _hwnd(nullptr), _viewSize(AVSP_DEFAULT) {} HRESULT RuntimeClassInitialize(_In_ HWND hwnd, _In_ APPLICATION_VIEW_SIZE_PREFERENCE viewSize) { _hwnd = hwnd; _viewSize = viewSize; return S_OK; } // IServiceProvider IFACEMETHODIMP QueryService(REFGUID guidService, REFIID riid, _COM_Outptr_ void **ppvObj) { return (guidService == SID_LaunchSourceViewSizePreference) ? QueryInterface(riid, ppvObj) : E_NOINTERFACE; } // ILaunchSourceViewSizePreference IFACEMETHODIMP GetSourceViewToPosition(_Out_ HWND *hwnd) { *hwnd = _hwnd; return S_OK; } IFACEMETHODIMP GetSourceViewSizePreference(_Out_ APPLICATION_VIEW_SIZE_PREFERENCE *sourceSizeAfterLaunch) { *sourceSizeAfterLaunch = _viewSize; return S_OK; }private: HWND _hwnd; APPLICATION_VIEW_SIZE_PREFERENCE _viewSize;};// ......... ComPtr<IApplicationActivationManager> appActivationManager; HRESULT hr = CoCreateInstance(CLSID_ApplicationActivationManager, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&appActivationManager)); if (SUCCEEDED(hr)) { ComPtr<IServiceProvider> sourceView; hr = MakeAndInitialize<CLaunchSourceViewSizePreference>(&sourceView, hwnd, AVSP_USE_NONE); if (SUCCEEDED(hr)) { hr = IUnknown_SetSite(appActivationManager.Get(), sourceView.Get()); if (SUCCEEDED(hr)) { hr = appActivationManager->ActivateApplication( L"Contoso.AppId", activationArguments, AO_NONE, &pid); } } }Example: Another app launches the browser. The browser’s IExecuteCommand handler sets the view size preference object on the site chain when calling activation manager to launch the browser. Assume the browser wants to share the screen (about 50/50) with the source app.class CLaunchTargetViewSizePreference : public Microsoft::WRL::RuntimeClass< Microsoft::WRL::RuntimeClassFlags<Microsoft::WRL::RuntimeClassType::ClassicCom>, IServiceProvider, ILaunchTargetViewSizePreference>{public: CLaunchTargetViewSizePreference() : _viewSize(AVSP_DEFAULT) {} HRESULT RuntimeClassInitialize(_In_ APPLICATION_VIEW_SIZE_PREFERENCE viewSize) { _viewSize = viewSize; return S_OK; } // IServiceProvider IFACEMETHODIMP QueryService(REFGUID guidService, REFIID riid, _COM_Outptr_ void **ppvObj) { return (guidService == SID_LaunchTargetViewSizePreference) ? QueryInterface(riid, ppvObj) : E_NOINTERFACE; } // ILaunchTargetViewSizePreference IFACEMETHODIMP GetTargetViewSizePreference(_Out_ APPLICATION_VIEW_SIZE_PREFERENCE *targetSizeOnLaunch) { *targetSizeOnLaunch = _viewSize; return S_OK; }private: APPLICATION_VIEW_SIZE_PREFERENCE _viewSize;};// ......... ComPtr<IApplicationActivationManager> appActivationManager; HRESULT hr = CoCreateInstance(CLSID_ApplicationActivationManager, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&appActivationManager)); if (SUCCEEDED(hr)) { ComPtr<IServiceProvider> targetView; hr = MakeAndInitialize<CLaunchTargetViewSizePreference>(&targetView, AVSP_USE_HALF); if (SUCCEEDED(hr)) { hr = IUnknown_SetSite(appActivationManager.Get(), targetView.Get()); if (SUCCEEDED(hr)) { hr = appActivationManager->ActivateApplication( L"Browser.AppId", activationArguments, AO_NONE, &pid); } } }Monitor preferenceUse the IApplicationActivationManager interface to set a preferred monitor on the site chain before calling the interface to activate an app.// Implemented by a browser, which uses CLSID_ApplicationActivationManager to // launch a Windows Store app. The object that implements // ILaunchTargetMonitor must be set on the site chain of // CLSID_ApplicationActivationManager before any method on // IApplicationActivationManager is called. The monitor specified by the// ILaunchTargetMonitor interface tells Windows which monitor the launched// app should be shown on.interface ILaunchTargetMonitor : IUnknown{ HRESULT GetMonitor([out] HMONITOR *monitor);}// This enum exactly matches the Windows Runtime enum Windows.UI.ViewManagement.ViewSizePreference.typedef [v1_enum] enum APPLICATION_VIEW_SIZE_PREFERENCE{ AVSP_DEFAULT = 0, AVSP_USE_LESS = 1, AVSP_USE_HALF = 2, AVSP_USE_MORE = 3, AVSP_USE_MINIMUM = 4, AVSP_USE_NONE = 5,} APPLICATION_VIEW_SIZE_PREFERENCE;Example: The browser launches a Windows Store app to a specific monitor. class CLaunchTargetMonitor : public Microsoft::WRL::RuntimeClass< Microsoft::WRL::RuntimeClassFlags<Microsoft::WRL::RuntimeClassType::ClassicCom>, IServiceProvider, ILaunchTargetMonitor>{public: CLaunchTargetMonitor() : _hMonitor(nullptr) {} HRESULT RuntimeClassInitialize(_In_ HMONITOR hMonitor) { _hMonitor = hMonitor; return S_OK; } // IServiceProvider IFACEMETHODIMP QueryService(REFGUID guidService, REFIID riid, _COM_Outptr_ void **ppvObj) { return (guidService == SID_LaunchTargetMonitor) ? QueryInterface(riid, ppvObj) : E_NOINTERFACE; } // ILaunchTargetMonitor IFACEMETHODIMP GetMonitor(_Out_ HMONITOR *phMonitor) { *phMonitor = _hMonitor; return S_OK; }private: HMONITOR _hMonitor;};// ......... ComPtr<IApplicationActivationManager> appActivationManager; HRESULT hr = CoCreateInstance(CLSID_ApplicationActivationManager, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&appActivationManager)); if (SUCCEEDED(hr)) { ComPtr<IServiceProvider> targetMonitor; hr = MakeAndInitialize<CLaunchTargetMonitor>(&targetMonitor, hMonitor); if (SUCCEEDED(hr)) { hr = IUnknown_SetSite(appActivationManager.Get(), targetMonitor.Get()); if (SUCCEEDED(hr)) { hr = appActivationManager->ActivateApplication( L"Contoso.AppId", activationArguments, AO_NONE, &pid); } } }Store app identificationWhen a Windows Store app calls the Windows Runtime Launcher API (to launch another app), the activation manager makes the AppUserModelId of the source app available on the site chain of the target application’s CoreApplication object. One example use of such information is tab glomming, meaning websites launched from AppA get grouped to a particular tab, AppB get grouped to a second tab, and so on.// Implemented by Windows. When a Windows Store app launches // a browser via association launch, an object implementing the// ILaunchSourceAppUserModelId interface is set on the site chain of// the CoreApplication object of the browser. The browser may call// QueryService(SID_LaunchSourceAppUserModelId, ...) on the site pointer// to retrieve the interface from which the AppUserModelId of the app that// launches the browser is available.interface ILaunchSourceAppUserModelId : IUnknown{ HRESULT GetAppUserModelId([out, string] LPWSTR *launchingApp);}void GetSourceAppId(_In_ IUnknown *site){ ComPtr<ILaunchSourceAppUserModelId> launchSourceAppId; HRESULT hr = IUnknown_QueryService(site, SID_LaunchSourceAppUserModelId, IID_PPV_ARGS(&launchSourceAppId)); if (SUCCEEDED(hr)) { PWSTR launchingApp; hr = launchSourceAppId->GetAppUserModelId(&launchingApp); } // ....This resource is later freed using CoTaskMemFree()}SearchWhen a user follows web links from the Search experience, it’s a best practice for browsers to re-use tabs. This provides the most consistent and predictable user experience. Additionally, referral strings are available in the URL execution context property store. Browsers should extract these identifiers and pass them on to the target website when issuing the HTTP request.DEFINE_GUID(SID_URLExecutionContext, 0xFB5F8EBC, 0xBBB6, 0x4D10, 0xA4, 0x61, 0x77, 0x72, 0x91, 0xA0, 0x90, 0x30);#define STR_TAB_REUSE_IDENTIFIER L"Tab Reuse Identifier"#define STR_REFERRER_IDENTIFIER L"Referrer Identifier"... ComPtr<INamedPropertyStore> spPropStoreContext; HRESULT hr = IUnknown_QueryService(punkSite, SID_URLExecutionContext, IID_PPV_ARGS(&spPropStoreContext)); if (SUCCEEDED(hr)) { PROPVARIANT value; PropVariantInit(&value); PCWSTR pszKey = STR_TAB_REUSE_IDENTIFIER; // or STR_REFERRER_IDENTIFIER hr = spPropStoreContext->GetNamedValue(pszKey, &value); if (SUCCEEDED(hr) && (value.vt == VT_LPWSTR) && (value.pwszVal != nullptr)) { // use value.pwszVal as identifier PropVariantClear(&value); } }WindowingThe Windows 8.1 new user experience is designed around a number of principles related to immersion and consumption:Windows Store apps run only in the new user experience. Using the new windowing APIs, they cannot create windows in the desktop experience. The new user experience is focused on a single app at a time, with multitasking, app switching, and notifications provided by the new experience. Windows Store apps are sized to fill available space in the new user experience environment, with a static number of supported “views” (e.g. portrait, landscape, full screen).Ongoing activities in the desktop remain in the desktop environment.A new experience enabled desktop browser, configured as the user’s default, can choose to participate either in the new user experience or the desktop, but not both from the same running process. The browser must first activate itself as a Windows Store app; after this has been done and it’s the user’s default browser, the browser is identified as such by the system:A new experience enabled desktop browser, when identified and activated as a new experience enabled desktop browser, can create and manage windows in the new user experience.Attempting to create a window in the new user experience when not identified as a new experience enabled desktop browser fails.Attempting to create a desktop window when identified as a new experience enabled desktop browser succeeds, but the new experience enabled desktop browser won’t be able to change focus (bring to foreground) nor manage any desktop windows. Any calls to SetForegroundWindow() or SetActiveWindow() fail under these conditions. There is no automatic switching between the new experience and the desktop.A new experience enabled desktop browser may not call LockSetForegroundWindow(); any calls to the API fail.Any calls to AllowSetForegroundWindow() may succeed if the new experience enabled desktop browser is in the foreground, however this call will not facilitate any attempt to allow a desktop app or another Windows Store app to move to the foreground. Any calls to EnableWindow() from a new experience enabled desktop browser fails if the target hWnd is not a new user experience window.A new experience enabled desktop browser may not attach input threads with any desktop app and vice-versa. Any calls to AttachThreadInput(idAttach, idAttachTo) where the idAttach and IdAttachTo parameters are neither both viewable in the new user experience nor both desktop fail. A new experience enabled desktop browser may not change the foreground (even to a new user experience window) when a desktop app, accessibility app or system component is in the foreground. Any calls to SetForegroundWindow() or SetActiveWindow() fail under these conditions. Before activating as a Windows Store app, it’s advised that the browser destroy any visible desktop windows as these will be unmanageable once identified as a new experience enabled desktop browser.Should a new experience enabled desktop browser try to launch a desktop app and have that app come to the foreground (for example, downloading and launching a file such as a PDF reader), it may do so by using ShellExecuteEx() and specifying the SEE_MASK_FLAG_LOG_USAGE flag in the fMask field. If this flag is not specified, the desktop app launches, but won’t be able to come to the foreground. There is no automatic switching between the new experience and the desktop.UI framework guidanceNew experience enabled desktop browsers can use the primary UI technology of their choosing for both the new experience and the desktop, provided that technology is defined in the Windows 8.1 Platform (Desktop) SDK. More specifically, we recommend that browsers use DirectX as their primary rendering technology and framework. New experience enabled desktop browsers can’t use UI technologies intended for Windows Store app use as defined in the Windows SDK for Windows Store apps (for example, the new XAML and HTML5 / JavaScript UI frameworks introduced in Windows 8.1). Additionally, for the best text input experience, we recommend using the Win32 Edit Control for user input in your new experience browser.Guidance for multi-process browsersFor browsers that have adopted a multi-process architecture – typically, a separation of the frame process from the tabs that display webpage content – create a single ICoreWindow managed by the frame process. We don’t recommend that you host each tab in its own separate top level ICoreWindow. Adopting such an architecture may lead to flickering of windows on tab switches, brief display of the Start background on tab creation / switching, and incompatibility with Narrator and other accessibility tools. If the browser presents multiple views, follow the MSDN guidance on app view switching.Touch keyboardThe touch keyboard is a system component that enables users of touch devices to input text. The touch keyboard is displayed when users need to input text, and it is out of the way when they don’t. The touch keyboard reacts to UI accessibility properties to determine whether a focused UI element is meant to receive text input. This approach allows the touch keyboard to define a specific set of rules for invocation and dismissal that are rooted in the UI elements that users interact with. New experience enabled desktop browsers must ensure text controls are marked with the correct accessibility properties (e.g. UI Automation TextPattern) to receive the correct touch keyboard behavior. This accessibility property requirement applies both to UI that displays in the new experience and to UI that displays on the desktop. Additionally, for desktop UI (such as the address bar when the browser is displaying on the desktop), you must also call the EnableFocusTracking method. For more info, see The touch keyboard white paper.NOTE: Don’t use the Windows 7 model of keyboard invocation, which relied on conventional APIs (e.g. ITextInputPanel) to display / hide the keyboard. That model is not compatible with new presentations of browsers. App contractsContracts are like agreements between Windows and Windows Store apps, including new experience enabled desktop browsers. They support some kind of user interaction and help users complete scenarios. New experience enabled desktop browsers are encouraged to participate in app contracts, particularly Search, Sharing, PlayTo, and Print. Some browser-specific examples of the utility of contracts include playing music originating from a website on a connected (to the PC) stereo and/or sharing article content as viewed on a website with another Windows Store app. For more info, see Windows application contracts. Search contractSearch is unchanged from Windows 8 in terms of defaults. New experience enabled desktop browsers that are set as the user’s default may choose to (and are encouraged to) participate in the Search contract of the new user experience. When a new experience enabled desktop browser is not set as the user’s default browser, a tile entry for the browser doesn’t appear in the search pane. For more info, see Quickstart: Adding search to an app.Share contractNew experience enabled desktop browsers are encouraged to help users share website content with other Windows Store apps on the system. A typical flow starts with the user selecting some content displayed in the browser – a video, a block of text, an image – and choosing the Share charm to share the content with another app. When the user has selected an object and chosen to share, the browser should share that selection. In the absence of a currently selected object, the browser should share the URL to the webpage along with metadata such as the page title and description. Browsers should also consider implementing and sharing custom formats. For example, a differentiating feature (that would also enhance the user experience) might be to add extra entities to a user selection, such as a movie, and share that data as a custom format. For more info, see Quickstart: Sharing content.Play To contractThe Play To contract provides the ability to stream HTML audio, video and images from websites to certified Play To devices. The typical scenarios are streaming a single video from a website, or streaming a playlist of audio/video elements. It’s up to the browser to identify and specify/update the media element that should be set as the Play To source. The algorithm to set the Play To source is up to the browser and could rely on a combination of user input/selection, site developer specifying the source using a media element attribute, and/or other disambiguation heuristic when multiple media elements are present on the same page. For example, Internet Explorer 10 enables webpage developers to use the x-ms-xPlayToPrimary attribute to indicate an audio, video, or image is the default media source. Also, because Play To is enabled by default in Internet Explorer 10, the x-ms-xPlayToDisabled attribute can be used by a webpage developer to disable the functionality on the page. Other browser vendors may choose to provide similar vendor-specific attributes.The typical flow starts with the user swiping the charms and selecting Devices. At this point the browser is asked to provide a Play To source. If a source is specified, available Play To target devices are shown in the Device charm. To synchronize device events with the media elements, the browser must register for device events from the Play To Manager. For more info, see Streaming media to devices using Play To and the related Quickstart: Using Play To in apps. Print contractBrowsers are encouraged to implement the print contract, to support simple and predictable printing experiences within the new user experience. Integration with the system contact cardNew experience enabled desktop browsers can use the ShowContactCardforWindow API to display the Windows contact card experience. For example, a browser that supports entity recognition for phone numbers in webpages can provide a more consistent user experience by displaying the Windows contact card rather than attempting a protocol launch (e.g. for tel://). The contact card presents the user with the most common communication actions based on the contact data, for instance offering call, video call, and SMS options for a phone number. This often has the effect of giving the user more control and choice than a simple protocol launch. In addition, the contact card experience is lightweight and contextual, allowing users to complete a communication action without shifting focus away from their current browsing experience. For more info, see IContactManagerInterop interface.interface IContactManagerInterop : IUnknown{ // Default browser uses this method to launch contact card from its tab window, specified // by the appWindow parameter. HRESULT ShowContactCardForWindow( [in] HWND appWindow, // Must be a Windows::ApplicationModel::Contacts::IContact object. // Use IUnknown here because classic COM IDL cannot use WinRT types. [in] IUnknown *contact, [in] RECT const *selection, [in] FLYOUT_PLACEMENT preferredPlacement);Process lifetime managementNew experience enabled desktop browsers are subject to the same Process Lifetime Management (PLM) rules as other Windows Store apps. When drawing desktop windows and managing background downloads, browsers are subject to the process lifetime standards of desktop apps. Close gestureUsers may choose to close a new experience enabled desktop browser via operating system features such as the close gesture. Users invoke the close gesture by “dragging” a representation of the window from the top of the app to the bottom of the screen, holding until the thumbnail rotates, and then dragging the thumbnail off screen. When the new experience enabled desktop browser is active (not suspended, not in the background), painting via ICoreWindow, it’s sent a registered window message with the string “DefaultBrowserClosing” as it moves off screen during window close. The browser should use this message as a signal to prepare for termination after suspension is complete. For example, a browser may send events to the active webpage, such as BeforeUnload and Unload when the DefaultBrowserClosing message is received. Some websites rely on events such as these to trigger specific behaviors, like sending data back to a server to mark the end of a user session. Note: Open browser dialogs, such as those originating from webpages, should not prevent the user from closing the browser. For instance, confirmation dialogs that sometimes show when a page handles the BeforeUnload event should be suppressed and not allowed to interfere with closing the browser. For more info, see Managing the Application Lifecycle.Closing background sessions and cleaning up private browsing dataThere are a few ways a user can close a new experience browsing session without first bringing the browser window to the foreground. Pulling the thumbnail of the browser from the switch list to the bottom of the screen, holding until the thumbnail rotates, and dragging the thumbnail off screen.Pulling the browser from the back stack using the left edge, dragging the window to the bottom of the screen, holding until the thumbnail rotates, and dragging the thumbnail off screen.In such instances, the browser can’t run code before the app is closed. The browser’s window isn’t sent a “DefaultBrowserClosing” message. Instead, Process Lifetime Management closes the browser and immediately reactivates it as a desktop process with the -BackgroundSessionClosed command-line argument, e.g. “examplebrowser.exe -BackgroundSessionClosed”. Use this opportunity to clean up data from the previous browsing session, particularly sensitive user data that may have been persisted to disk during a private browsing session. Don’t present a window or run other tasks. Exit as soon as the cleanup is complete. If no data cleanup tasks are required (for instance, if the browser doesn’t offer the private browsing feature), handle the activation argument and exit. Completing downloads and uploads prior to suspendNew experience enabled desktop browsers suspend when the user switches away from the browser and resume when the user switches back to it. There are a limited number of cases where the browser may postpone the act of suspension in order to complete a long running user task:Completing file uploads, such as an active upload via POST with a file attached or via XMLHttpRequestCompleting file downloadsBrowsers are strongly encouraged to leverage the background APIs in a manner consistent with Windows Store apps. Doing so improves battery life by more efficiently consuming system resources. For more info, see Quickstart: Downloading a file and Quickstart: Uploading a file. Alternatively, new experience enabled desktop browsers may use the PowerCreateRequest, PowerSetRequest, and PowerClearRequest functions as documented in the Power Availability Requests whitepaper. Note that these APIs are only callable from medium integrity level (or higher) processes. For more info, see Guidelines to app suspend and resume.Marking processes as eligible for suspension by WindowsA new experience enabled desktop browser can lower its memory footprint by allowing the Windows Process Lifetime Manager (PLM) to suspend and terminate child processes separately from the parent process of the app. Use this behavior to allow Windows to suspend tabs, which often run in their own processes independent of the “frame,” when tab content is not visible to the user.Use the SuspensionDependencyManager APIs to create and mark each process created by the app. Create each child process by passing the CREATE_BREAKAWAY_FROM_JOB flag into the call to CreateProcess(). After the process is created, the new experience enabled desktop browser calls RegisterAsChild() on the new process. Processes created in this manner can be individually suspended and terminated (by PLM), independent from the parent process.A new experience enabled desktop browser can optionally use the GroupChildWithParent() and UngroupChildFromParent() calls in SuspensionDependencyManager to mark a child process as being grouped or ungrouped with the parent process. If GroupChildWithParent() is used to group the child process with the parent process, the child process is only suspended when the parent process is suspended.GroupChildWithParent() is intended for use in situations where the system isn’t aware that the child process is user-visible, but is aware that the parent process is user-visible. ?For example, if a child process hosts a visible top-level window, PLM ensures that the process is not suspended and GroupChildWithParent() is not needed.? However, if the child process hosts a child window (implying the parent process hosts the top-level window), PLM is not aware of the child process’ visibility; therefore, GroupChildWithParent() may be necessary to ensure that the child process is not suspended.? A further example: if the child process is printing, PLM ensures that it’s not suspended and GroupChildWithParent() isn’t necessary.Roaming browser application dataUsers can easily keep their browser’s application data in sync across multiple devices when you support roaming. Doing so benefits the user by:Reducing the amount of setup work that the user needs to do for your browser on their second device. Enabling users to continue a task, such as composing a list, right where they left off, even on a different device. Windows replicates roaming data to the cloud and synchronizes the data to other devices where the user has installed the browser.Windows limits the size of the application data that each app may roam. For this reason, it’s a best practice to use roaming data only for user preferences such as favorites, browser history, settings, and currently open URLs. For more info, see Guidelines for roaming app data. New experience enabled desktop browsers can sync the following:Favorites / ShortcutsTyped URLsHistoryTabs (currently open URLs)Up to 20 other registry based settingsRegister for roamingThe following registrations are required in order to roam data:HTTP and HTTPS protocol registration.A registry key HKLM\Software\RegisteredApplications with the browser name and the path to Capabilities Registry Key (of type REG_SZ For example: Software\Example Company\Example Browser\Capabilities). A Start shortcut with PKEY_AppUserModel_IsDualMode set to TRUE (VT_BOOL).A registry key under HKLM\Software\Microsoft\Windows\CurrentVersion\SettingsSync\BrowserSettings. The key name should be the same as the browser name. No subkeys and values are needed under this.The Capabilities Registry Key should contain a subkey named “Roaming.” This is the location where data stores are registered.Sync behaviorUnder normal circumstances, application data is uploaded within a few minutes of receiving a change notification. For performance reasons, however, the sync framework may delay upload of new history entries, in some cases up to 24 hours. When a sync causes a conflict in a setting value, the “last writer wins.”PC setting for web browser syncingA browser can query the value of the toggle in PC Settings, which controls whether browser syncing is on or off. The value of this toggle determines whether the roaming platform runs the browser’s sync handlers, and the browser can read the setting’s value in order to deliver the right experience for the user’s setting choice. The following example uses a Windows API to get the web browser sync setting:bool IsBrowserSettingSyncEnabled(){??? bool browserSyncEnabled = false;??? IDefaultBrowserSyncSettings *defaultBrowserSyncSettings;??? if (SUCCEEDED(CoCreateInstance(CLSID_DefaultBrowserSyncSettings, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&defaultBrowserSyncSettings))))??? {??????? browserSyncEnabled = BOOLIFY(defaultBrowserSyncSettings->IsEnabled());??????? defaultBrowserSyncSettings->Release();??? }???? return browserSyncEnabled;}Note that this is a read-only API; the browser cannot change the value of the setting itself.Receiving window messagesIn order to have window messages be sent to a suspended (non-running) process, register for a window message with the following GUID: FAE1E238-AAA7-4EAF-A7E3-C378378ADFE9.Doing this causes window messages to be sent to a suspended process, whereas previously, WM_SETTINGCHANGE only worked for running instances of the browser. In Windows 8, if your sync provider contained a “WindowClassesToNotify” value, for example:??????????????? HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Capabilities\Roaming\WinInet!WindowClassesToNotify = "IEFrame,ImmersiveWorkerWindowClass"after your sync provider makes a change (via SettingSyncHost.exe), SettingSyncHost.exe sends a WM_SETTINGCHANGE window message to windows with the specified class name. Now, in Windows 8.1, if you also specify an “lParamValue” value, for example:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Capabilities\Roaming\WinInet!lParamValue = (DWORD) 1instead of sending WM_SETTINGCHANGE, SettingSyncHost sends the window message that gets returned by the call toRegisterWindowMessage(L"FAE1E238-AAA7-4EAF-A7E3-C378378ADFE9");SettingSyncHost.exe performs this function call before sending the message, and a browser needs to perform this call in order to know what message to watch for.Syncing favorites / Internet shortcutsIn order to roam favorites, create a registry key with the name “FavoriteUrls” under the browser’s roaming capabilities registry key. For example: HKLM\Software\Example Company\Example Browser\Capabilities\Roaming\FavoriteUrls. Then, create a registry value with name “KnownFolderID” of type REG_SZ that specifies the Known Folder ID as a GUID (e.g. '{F1B32785-6FBA-4FCF-9D55-7B8E7F157091} '). Internet shortcuts within this folder and subfolder are roamed. The shortcuts must be created using the APIs as explained in Internet Shortcuts.Optionally, you can register to roam the order of shortcuts. To accomplish this, create a registry value under “FavoriteUrls” capabilities with name “OrderRegPath” that specifies the root registry key under HKCU containing the order information for the top level “Favorites” folder and all sub folders. For example: Software\Example Company\Example Browser\FavoritesOrder. For the order of shortcuts in the top level “Favorites” folder, the above registry key can contain a registry value with the name “Order” and type REG_BINARY with a value of the browser’s choosing. For the order of shortcuts in any subfolders, this registry key must contain corresponding sub keys mirroring the folder hierarchy (again, with the name “Order” and type REG_BINARY). For example, if the favorites folder is %LOCALAPPDATA%\Example Company\Example Browser\Favorites\Sub Folder1\Sub Folder2, the order information for the root favorites folder must be in a registry value under HKCU\Software\Example Company\Example Browser\FavoritesOrder, the order information for the first sub-folder (…\Favorites\Sub Folder1) must be in a registry value under HKCU\Software\Example Company\Example Browser\FavoritesOrder\Sub Folder1, and so on.Watch for changes to the favorite’s folder before refreshing the browser UI representation of the user’s favorites. When a shortcut is roamed for the first time, an additional property {FMTID_Intshcut, PID_IS_ROAMED } of type VT_BOOL and value VARIANT_TRUE is added. Set the value to VARIANT_FALSE after the browser has processed the update. Additionally, Windows sends an extended shell change notification SHCNE_EXTENDED_EVENT of type SHCNEE_ORDERCHANGED and the PIDL of the folder in which the shortcut was changed. Browsers can listen for this notification to refresh the favorites order following roaming.Syncing typed URLsIn order to sync typed URLs, create a registry key with the name “TypedURLs” under the browser’s roaming capabilities registry key. For example: HKLM\Software\Example Company\Example Browser\Capabilities\Roaming\TypedURLs. Then, create a registry value with the name “URLsRegPath” of type REG_SZ that specifies the path (within HKCU) that contains the URLs in key value format. For example: HKCU\Software\Example Company\Example Browser\TypedURLsNameTypeValueurl1REG_SZ…Windows roams 50 of the user’s most recently accessed URLs. If a user has more recent entries, browsers may choose to store the time when each of the URLs was typed; Windows uses this information to ensure that the most recently typed URLs sync first. To do this, create a registry value with the name “URLsTimeRegPath” of type REG_SZ that specifies the path (within HKCU) that contains the URL’s typed time. For example: HKCU\Software\Example Company\Example Browser\TypedURLsTimeNameTypeValueurl1REG_BINARYFILETIME, in UTC, of the time when the URL was typed in the browserurl2REG_BINARYFILETIME, in UTC, of the time when the URL was typed in the browser…Each time a typed URL is roamed, running instances of the browser receive a registered message, returned by calling RegisterWindowMessage(L"FAE1E238-AAA7-4EAF-A7E3-C378378ADFE9"), with a wParam value of “0” and an lParam value “TypedUrlsRoamed”. Specify the window class Windows should send the message to by creating a registry value of name “WindowClassesToNotify” of type REG_SZ and value equal to the name of the window classes, comma separated, in the \Capabilities\Roaming\TypedUrls registry key. Specify “TypedUrlsRoamed” by creating a registry value of name ““TypedUrls” of type REG_DWORD and value equal to a unique number in the \Capabilities\Roaming\TypedUrls registry key.Syncing browser historyThe following registrations are required in order to sync browser history:Implement a shell folder and register it as a KNOWNFOLDER. When the user’s browsing history changes, call SHChangeNotify to indicate that the folder contents have changed. Store URL history in a WinInet cache using a browser-specific prefix ending with a colon. For example, the Contoso browser might use the prefix “Contoso:” when storing URLs in a WinInet cache.In order to sync browser history, create a registry key with the name “WinInet” under the browser’s roaming capabilities registry key. For example: HKLM\Software\Example Company\Example Browser\Capabilities\Roaming\WinInet. Then, create a registry value with the name “KnownFolderID” of type REG_SZ that specifies the Known Folder ID as a GUID (e.g. '{F1B32785-6FBA-4FCF-9D55-7B8E7F157091} '). Also, create a registry key value with the name “WinInetPrefix” of type REG_SZ and value equal to the name of the browser-specific prefix, ending with a colon (:).For more info about using WinInet caching APIs, see Caching.Store the URL in the format “Prefix: username@URL” where “username” is the value returned by the GetUserName() function. For example, Contoso: user@ CommitUrlCacheEntry function allows a browser to store a list of URLs that have been accessed and associate each with a local copy of the data that was last received. It also allows the browser to store header information (in the lpHeaderInfo parameter). In order to roam history data, the lpHeadInfo parameter must contain a serialized property store instead of the header info. You do this by Using PSCreateMemoryPropertyStore to create a store and saving the browser’s properties into it. Next, use IPersistStream::Save to serialize the property store into a byte array in memory. Finally, call CommitUrlCacheEntryA and pass the byte array for the lpHeaderInfo field to store the property store for that URL. Note: A browser can append arbitrary bytes to the end of the lpHeadInfoStream to store local data that should not be altered or roamed by Windows. Retrieve binary history data by performing the inverse: use GetUrlCacheEntryInfoA, remove the prefix and username from the returned URL, and then use PSCreateMemoryPropertyStore and IPersistStream::Load to convert the lpHeaderInfo back into an IPropertyStore. The ANSI versions of other WinINet caching APIs such as FindFirstUrlCacheEntryA and FindNextUrlCacheEntryA can also be used to enumerate the cache in a similar manner. Note: Roaming history requires use of the ANSI WinInet cache APIs to persist binary data. If a URL contains non-ANSI characters, encode the URL using well-known schemes such as percent-encoding.Detect that new URLs have been added to the cache via roaming by checking the {FMTID_InternetSite, PID_INTSITE_ROAMED} property.Value of PID_INTSITE_ROAMEDDescriptionValue not set or PIDISR_UP_TO_DATEThis cache entry has not been modified by roaming.PIDISR_NEEDS_ADDThis cache entry was added to the cache by roaming. Set PIDISR_UP_TO_DATE once processing of the entry is complete.PIDISR_NEEDS_UPDATEThis cache entry already existed on the local machine, but it was updated by roaming. Set PIDISR_UP_TO_DATE once processing of the entry is complete.PIDISR_NEEDS_DELETERoaming detected that this cache entry should be deleted. For example, the user may have cleared his or her browser history. Delete the entry using DeleteUrlCacheEntry.The following rules govern conflict resolution for roaming browser history:The property stores in the lpHeaderInfo stream are merged such that the most recently changed values are preserved.If the property store contains the public “visit count” property {FMTID_InternetSite, PID_INTSITE_VISITCOUNT}, the largest of the values is preserved.If there’s additional data in the local cache entry’s stream after the serialized property store, the local data is preserved.The following rules govern what history entries roam:Roam: URLs with http:// or https:// schemes; Cache entries of type “URLHISTORY_CACHE_ENTRY | NORMAL_CACHE_ENTRY”; The 1000 most recent updated history entries.Not Roam: URLs to images; Cache entries that don’t contain a serialized property store in their lpHeaderInfo; Properties in the serialized property store that would require deserialization (such as VT_UNKNOWN, VT_STREAM, or VT_STORAGE); History entries with more than 2KB in their lpHeaderInfo structure.When the browser has updated or added any history data, use the SHChangeNotifyAPI and send a change notification for the registered known folder. Conversely, when Windows has concluded roaming a user’s history, a timestamp of the most recent operation is written to the registry at HKCU\Software\Microsoft\Windows\CurrentVersion\SettingsSync\Namespace\BrowserSettings\WinInet-browsername!LastRoamed. Compare this value with the last known time that entries were detected to determine if history has changed. Alternatively, each time a registry key is roamed, running instances of the browser receive a registered message, returned by calling RegisterWindowMessage(L"FAE1E238-AAA7-4EAF-A7E3-C378378ADFE9"), with a wParam value of “0” and an lParam value “WinINetRoamed”. Specify the window class Windows should send the message to by creating a registry value of name “WindowClassesToNotify” of type REG_SZ and value equal to the name of the window classes, comma separated, in the \Capabilities\Roaming\WinInet registry key. Specify “WinInet” by creating a registry and value equal to the name of the window classes, comma separated, in the \Capabilities\Roaming\WinInet registry key. Syncing tabsIn order to sync tabs, create a registry key with the name “TabRoaming” under the browser’s roaming capabilities registry key. For example: HKLM\Software\Example Company\Example Browser\Capabilities\Roaming\TabRoaming. Then, create a registry value with the name “KnownFolderID” of type REG_SZ that specifies the Known Folder ID as a GUID (e.g. '{F1B32785-6FBA-4FCF-9D55-7B8E7F157091} ').The following registrations are required in order to sync open tabs:"RelativePath" (REG_SZ, optional) -- folder path relative to the supplied known folder (e.g. "Contoso\BrowserRoamingFiles")"Recursive" (REG_DWORD, optional) -- whether to roam files and folders recursively from the supplied target directory (e.g. "0x00000001")The files and folders under the TabRoaming folder are replicated on other participating machines (modulo behavior when Recursive isn't set to 0x1). Tab syncing and device capabilitiesTabs sync with different frequency, based on the device’s hardware capabilities, and whether it supports connected-standby (e.g. “always on, always connected”) or not. Connected-standby (CS) or non-CS can be determined by using the Windows function CallNtPowerInformation.Connected standby supported: Tab Roaming state is synced at the same time as history, favorites, etc. State is also synced with "best effort" during connected standby entry. Best practice: write state to disk as often as you like.?Connected standby not supported: Tab Roaming state is synced nearly instantly when written to disk. Best practice: Self-throttle writes to about 2 minutes to avoid flooding the system with sync requests. Each time a registry key is roamed, running instances of the browser receive a registered message, returned by calling RegisterWindowMessage(L"FAE1E238-AAA7-4EAF-A7E3-C378378ADFE9"), with a wParam value of “0” and an lParam value “TabRoamingRoamed”. Specify the window class Windows should send the message to by creating a registry value of name “WindowClassesToNotify” of type REG_SZ and value equal to the name of the window classes, comma separated, in the \Capabilities\Roaming\TabRoaming registry key. Specify “TabRoamingRoamed” by creating a registry value of name “TabRoaming” of type REG_DWORD and value equal to a unique number in the \Capabilities\Roaming\TabRoaming registry key.Roaming other registry settingsIn addition to roaming user favorites, typed URLs, and browser history, browsers may also sync up to a maximum of fifteen other registry keys. Create a registry key with the name of your choosing under the browser’s roaming capabilities registry key. For example: HKLM\Software\Example Company\Example Browser\Capabilities\Roaming\NewKey Then, create a registry value named “RegistryRoot” of type REG_SZ that specifies the path to the key under HKCU that should be roamed. Creating a registry value of name “FilterIn” of type REG_SZ and value containing a comma separated list of registry values lets you specify an inclusion list for roaming. Any values not specified that appear under the “RegistryRoot” won’t be roamed. Conversely, creating a registry value of name “FilterOut” type REG_SZ and value containing a comma separated list of registry values to exclude lets you specify an exclusion list for roaming. All values under the “RegistryRoot” are roamed except for those specified in the “FilterOut” value.Each time a registry key is roamed, running instances of the browser receive a registered message, returned by calling RegisterWindowMessage(L"FAE1E238-AAA7-4EAF-A7E3-C378378ADFE9"), with a wParam value of “0” and an lParam value ““<SettingName>Roamed”. Specify the window class Windows should send the message to by creating a registry value of name “WindowClassesToNotify” of type REG_SZ and value equal to the name of the window classes, comma separated, in the \Capabilities\Roaming\<SettingName> registry key. Specify “<SettingName>Roamed” by creating a registry value of name “<SettingName>” of type REG_DWORD and value equal to a unique number in the \Capabilities\Roaming\<SettingName> registry key.For more info, see Accessing app data with the Windows Runtime.Windows Runtime API referenceA subset of Windows Runtime APIs are available for use by new experience enabled desktop browsers. The list of runtime classes as documented in the Windows 8 API reference on MSDN.Additionally:Windows.ApplicationModel.Contacts.Contact.ContactName.FirstNameWindows.ApplicationModel.Contacts.ContactManager.ShowContactCardWindows.ApplicationModel.Contacts.ContactPhone.PhonesWindows.ApplicationModel.Contacts.ContactPhone.NumberWindows.ApplicationModel.SuspendingOperationWindows.Devices.Geolocation.GeolocatorWindows.Devices.Input.PointerDeviceWindows.Foundation.Diagnostics.AsyncCausalityTracerWindows.Graphics.Display.DisplayPropertiesWindows.Graphics.Printing.OptionDetails.PrintCustomItemListOptionDetailsWindows.Graphics.Printing.StandardPrintTaskOptionsWindows.Storage.Streams.InMemoryRandomAccessStreamWindows.Storage.Streams.RandomAccessStreamOverStreamWindows.UI.Core.IdleDispatchedHandlerArgsWindows.UI.Notifications.ScheduledTileNotificationWindows.UI.StartScreen.SecondaryTileVisualElementsWindows.UI.ViewManagement.ApplicationViewSwitcher ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download