Accessing the Windows 10 Runtime

Enabling API Access

Windows 10 hosted web applications can take advantage of the Universal Windows Platform (UWP) allowing script hosted on the server to have direct access to the Windows Runtime APIs. To use the Windows Runtime in a ManifoldJS-generated app, it must first be enabled in the mjs_api_access member of the W3C manifest by specifying the set of pages that require access to the API. This member contains a list of URL-matching rules and the type of runtime access allowed for each rule.

Multiple rules can be added to the mjs_api_access section of the manifest, each one containing a match attribute with an expression that matches the URL of one or more pages where API access needs to be enabled. The expressions may contain wildcards to allow rules to handle a range of pages. Since the mjs_api_access section of the manifest is used for different platforms, it may contain rules that are not compatible across all platforms. Therefore, a rule typically includes a platform attribute listing the platforms for which it applies.

The access attribute specifies the type of API access enabled by a rule. Windows 10 hosted web apps access the Windows Runtime by specifying all or allowForWebOnly access types.

If a rule omits the access attribute, it will grant the most privileged level of API access available in the platforms for which it applies. Similarly, if platform is left unspecified, the rule applies in every platform.

For example, the following W3C manifest enables API access to the pages in the http://bancocontoso.azurewebsites.net/ site.

W3C manifest

...
"mjs_api_access": [
  { "match": "*://bancocontoso.azurewebsites.net/*", "access": "all", "platform": "windows10" }
  { "match": "http://bancocontoso.azurewebsites.net/*", "access": "cordova", "platform": "ios,windows,android" },
]
...

When ManifoldJS processes the W3C manifest, it will update the ApplicationContentUriRules section of the Windows 10 app manifest as follows:

APPX manifest

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
          xmlns:mp="http://schemas.microsoft.com/appx/2014/phone/manifest"
          xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
          xmlns:build="http://schemas.microsoft.com/developer/appx/2015/build"
          IgnorableNamespaces="uap mp build"> 
    ...
			<uap:ApplicationContentUriRules>				
				<uap:Rule Type="include" WindowsRuntimeAccess="all" Match="http://bancocontoso.azurewebsites.net" />
			</uap:ApplicationContentUriRules>
		</Application> 
	</Applications>
  ... 
</Package>

Declaring Application Capabilities

In addition, access to certain APIs and devices is disabled by default and must be explicit enabled in your app. Apps must declare in their manifest any restricted resources that they want to access, such as the user's pictures, videos, or music libraries, their list of contacts, or the camera and microphone. This information is provided to users, even before installing an app, allowing them to decide whether it is safe to proceed.

ManifoldJS supports a custom member named mjs_capabilities that can be used to specify any capabilities required by an app. Currently, this attribute is supported by the Windows 10 platform only. To declare capabilities, add this member to the input W3C manifest and set its value to an array of strings listing the names of every capability needed by the app. For a full list of capabilities, see App capability declarations.

For example, the following specifies that the app requires access to the pictures and videos libraries, the contacts list, and the camera.

W3C manifest

{
    "start_url": "http://bancocontoso.azurewebsites.net",
    ...
    "mjs_capabilities": [
      "picturesLibrary",
      "videosLibrary",
      "contacts",
      "webcam"
    ]
}

Note: The internetClient capability is required by all hosted web apps and is included by default. You don't need to specify it.

When ManifoldJS processes the W3C manifest, it translates any capabilities it finds to corresponding elements in the Windows 10 app manifest file (APPX).

APPX manifest

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
          xmlns:mp="http://schemas.microsoft.com/appx/2014/phone/manifest"
          xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
          xmlns:build="http://schemas.microsoft.com/developer/appx/2015/build"
          IgnorableNamespaces="uap mp build"> 
    ...
    <Capabilities>
      <Capability Name="internetClient" />
      <uap:Capability Name="picturesLibrary" />
      <uap:Capability Name="videosLibrary" />
      <uap:Capability Name="contacts" />
      <DeviceCapability Name="webcam" />
    </Capabilities>
</Package>

Example

The following shows a script fragment that could be included as part of a site's script to access the Windows Runtime API and enumerate the files in the user's pictures library.

Script fragment

// use feature detection to determine whether the app is running in Windows
if (window.Windows) {
  // access the runtime to get the files in the pictures library
  var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;
  picturesLibrary.getFilesAsync().done(function (filesInFolder) {
    filesInFolder.forEach(function (file) {
      // iterate over the results
      console.log(file.name, file.dateCreated);
    });
  });
}

To enable the above script to run, the W3C manifest must be configured to enable runtime access to the page hosting the script and to specify the picturesLibrary capability.

W3C manifest

...
  "start_url": "http://yoursite.com/",
  ...
  "mjs_api_access": [
    { "match": "*://yoursite.com/*", "access": "all", "platform": "windows10" }
  ],
  "mjs_capabilities": [
    "picturesLibrary"
  ]
...

For more information, see Hosted Web Apps.