poniedziałek, 30 kwietnia 2012

Notatki o Windows 8 Consumer Preview - odc. 20

Kontynuacja poniedziałkowego hardcore’u. Zebrałem sobie trochę informacji o wsparciu dostawców mobilnego internetu i operatorów sieci komórkowych w Windows 8 (bez zagłębiania się w sprzętowe czy narzędziowe szczegóły).

W przypadku aplikacji Metro dla dostawców Internetu zasadnicze informacje nie różnią się od tego co można było zobaczyć na konferencji BUILD. Aczkolwiek w wersji Consumer Preview udokumentowano wiele dotychczas nieudokumentowanych zagadnień.

Interesującym z pewnością zagadnieniem jest obsługa SMS-ów w Windows 8. W podstawowej wersji dokumentacji nie jest poświęcone temu za wiele uwagi, nie było też specjalnie eksponowane na BUILD.  A tymczasem można powiedzieć, że API Windows 8 (w dużej mierze PC z modem) oferuje sporo funkcjonalności dla SMS-ów, znacznie więcej niż … API w Windows Phone 7 czy 7.5  (np. odczytywanie i usuwanie wiadomości z urządzenia, odpalanie taska w tle na zdarzenie odebrania nowej wiadomości, odczytanie numeru telefonu i innych informacji urządzenia, dzielenie długich wiadomości na kilka, kodowanie w różnych standardach, wiadomości od operatora itd). Naturalne dla mnie byłoby odnaleźć to API w Windows Phone 8 mającym być podzbiorem Windows 8, ale jak będzie zobaczymy.

Mobile Broadband - Metro style Device Apps

image

Metro style Device Apps for Mobile Network Operators

The Windows mobile broadband network platform has been enhanced in Windows 8 to make use of these companion applications, allowing mobile network operators (MNOs) to write Metro style applications that will be silently deployed to their customers (either via the internet or preinstalled by the original equipment manufacturer). The Mobile Broadband Account API has been tagged as a privileged API.

To be able to call this API, a Metro style application must meet the following criteria:

  • The application must have a device metadata package associated with it, and it must be listed in the <PrivilegedApplications> XML element of the SoftwareInfo.xml file inside the metadata package. The metadata package need not be exclusive to the application; it is possible for any given Metro style application to be listed in the <PrivilegedApplications> element of several metadata packages. That metadata package must be associated with the service provider for a mobile broadband device that has been active at least once on the computer, so that it’s been installed (note that merely copying the metadata package to the device metadata store directory is not enough)
  • The application’s appxmanifest file needs a <DeviceCapability> entry for the Mobile Broadband API. This is done by adding the following XML element as a child of the <Capabilities> element in the application’s appxmanifest file:
    <DeviceCapability Name="BFCD56F7-3943-457F-A312-2E19BB6DC648" />

Non-Metro style applications (for example, win32 services or applications that run on the classic desktop) have unrestricted access to the mobile broadband account API.

A network account ID is a unique identifier for a mobile broadband account, and provides a unified ID that can be used without needing to know whether the ID comes from a GSM, CDMA, or WiMAX network (or other network types that Windows may support in the future). Network account IDs are generated by Windows whenever it sees a hardware-provided network subscription identifier that it has not seen before.

Any Metro style applications that are not in your metadata package’s <PrivilegedApplications> list will get an “access denied” error when trying to use your customer’s network account IDs to create MobileBroadbandAccount objects, and will not get your customers’ network account IDs when they query for them. If you want to allow another company’s Metro style application access to your customers’ mobile broadband accounts, you simply need to add their application’s package ID to your metadata package’s <PrivilegedApplications> list.

The Mobile Broadband Account API

  • Class MobileBroadbandAccount  - This class contains a set of properties and methods that are used to get information about the mobile broadband account and the radio state.
  • Class MobileBroadbandDeviceInformation - This class contains a set of properties that make up a snapshot of the mobile broadband device at the time the TryGetNetworkDeviceInformation method of the MobileBroadbandAccount class was called.
  • Enum CellularClass - This enumeration contains values for the different types of cellular networks that the Windows mobile broadband stack supports.
  • Enum DataClasses - This enumeration contains values for the different types of data classes supported by the Windows mobile broadband stack. It is a flags enumeration, meaning that each member is a bit that can be set or cleared individually.
  • Enum NetworkRegistrationState - This enumeration contains values that describe the possible different registration states that a mobile broadband device can be in. A device that is connected to its home network will have registration state Home, and a roaming device may be in either state Roaming or Partner.
  • Enum NetworkDeviceStatus - This enumeration contains values that describe the status of the mobile broadband device. A device that is operating normally is in state DeviceReady.

Creating a MobileBroadbandAccount Object

Because MobileBroadbandAccount objects represent network accounts, a network account ID is needed to create such an object. When a mobile broadband companion application is launched from the available networks fly-out, it will be given the network account ID to use as a parameter to the tile launch contract.

If the application is activated directly from its tile, then there will be no parameters associated with the tile launch contract, and you will need to call the GetAllNetworkAccountIds static method of the MobileBroadbandAccount class. This will return a read-only collection of strings, each string being a single account ID.

var myNetworkAccountId;

var allNetworkAccountIds =

  Windows.Networking.NetworkOperators.MobileBroadbandAccount.

  getAllNetworkAccountIds();

 

if (allNetworkAccountIds.size == 1) {

  myNetworkAccountId = allNetworkAccountIds[0];

}

If the returned collection has more than one string in it, you will need input from the end user who’s running the application. One possible way would be to iterate through the collection, creating a MobileBroadbandAccount object for each account ID in the collection (see below), and use some property of the object (for example, the telephone number) to populate a list box control. This control is presented to the end user, and once they make a selection, all other MobileBroadbandAccount objects can be released.

var myNetworkAccountId = "{95499FEF-1579-4547-A0BE-FF271ADBBE76}";

var myNetworkAccountObject =

Windows.Networking.NetworkOperators.MobileBroadbandAccount.

createFromNetworkAccountId(myNetworkAccountId);

Creating a MobileBroadbandDeviceInformation Object

A single MobileBroadbandAccount object may be associated with multiple MobileBroadbandDeviceInformation objects, but only one at a time. MobileBroadbandDeviceInformation objects are created by calling the TryGetNetworkDeviceInformation method of a MobileBroadbandAccount object.

Finding Out Whether the Network Device Is Turned Off

If the end user launches the mobile broadband companion application directly from its tile, it is possible that the mobile broadband device is either no longer plugged in or turned off. This can also happen if the end user turned on airplane mode (which disables the network devices) while the companion application was running. If this is the case, calling the TryGetNetworkDeviceInformation method will result in an exception being thrown (always HRESULT_FROM_WIN32(ERROR_DEVICE_NOT_AVAILABLE)).

try {

  var result = myNetworkAccount.TryGetNetworkDeviceInformation();

  if (result.isValid) {

    var info = result.deviceInformation;

    // use info here

  }

} catch(err) {

  // device is probably turned off, check err

}

HKLM\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts\Accounts
HKLM\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts\NetworkInterfaceBindings

The sequence of events that takes place when a mobile broadband device is first plugged in (or a computer with a built-in mobile device is first turned on) is as follows:

  1. The device subsystem in Windows detects the new network device, installs drivers and device metadata for it, and notifies the WWAN Autoconfig service.
  2. The WWAN Autoconfig service takes the network device through the necessary steps to connect to its network.
  3. The WWAN Autoconfig service also creates one or two pseudo-devices, one for the mobile broadband account that’s represented by the ICCID or MIN in the network device, and optionally one to handle SMS capabilities, if the mobile broadband device advertises that capability. The Mobile Broadband Account Binding pseudo-device is given a set of hardware IDs that identify the service provider. These are obtained from the home provider ID for CDMA and WiMAX networks, and from the IMSI for GSM networks.
  4. The Device Software Manager (DSM) detects the creation of the Mobile Broadband Account Binding pseudo-device and looks for a matching device metadata package. As was the case in Windows 7, it first checks the device metadata store directory for OEM-preloaded MNO metadata packages and then the WMIS Device Metadata server.
  5. DSM installs the metadata package for the MNO. This will also set up the correct branding for the MNO in the available networks fly-out, causing the name and icon to appear.
  6. The app store client will now silently install the Windows Metro style application that corresponds with the MNO’s metadata package, either picking it up from the OEM preinstallation location on the local machine or from the Windows app store. When this completes, a “View my Account” link will show up in the available networks fly-out for the mobile network connection; when this link is clicked, the MNO’s application will be launched.

Overview of Mobile Broadband Windows Runtime API

This app is not supposed to provide connection management functionality, but instead provide account experience and branding for your service.

Key Scenarios

Plan Purchase - This will enable users to purchase the subscription when they need the mobile connectivity.

image

Developing a plan purchase experience involves the following:

  • Determination of subscription status. When the app is started, it should intelligently determine whether the device has a currently associated plan and then show the appropriate experience based on that. To determine the current subscription status, the Metro style device app for mobile broadband can get device and subscription information from Windows - for example, International Mobile Subscriber Identity (IMSI), Integrated Circuit Card ID (ICCID), and International Mobile Equipment Identity (IMEI). Also, it can use the connectivity status of mobile broadband connection to determine whether the user has a plan.
  • Purchase or top-up experience. The purchase business-logic details (like plan information, payment, and credit card validation) must be maintained in your application. You can keep your current back-end interaction. Windows supports web services or cellular protocols like Unstructured Supplementary Service Data (USSD) to interact with your back end to develop this business logic.
  • Provisioning. After the user has purchased the plan, Windows must provision the device, and the operator must activate the device in its back end. Provisioning is defined as configuring a Windows-based PC with information that is required to connect to a carrier network. Typically, it occurs after subscription purchase. Provisioning information contains mobile broadband profile (access point name [APN], user name, and password), hot-spot profiles, Wi-Fi credentials, and plan information. Your application should use the Provisioning API to provide this information to Windows. By using this information, Windows will automatically connect to your network without any user input. For some carriers, the activation process on the mobile network is not instantaneous and can take time up to 10 minutes. Your application must handle this case elegantly and give a good experience to the user.

Design considerations:

  • Simplify the user experience by retrieving device information. During a purchase, your business logic needs device information (such as IMEI and IMSI) to show the plans that are available for the device. By using the Subscriber and Device Information API, your app can get the information, and you don’t have to ask the user to enter this information manually.
  • Provide a seamless connection experience by using the Provisioning API. After the user has purchased the plan, you can assign credentials to the subscription. The user must use these credentials and connectivity parameters for connecting to your network. You can use the Provisioning API to provide this information. The Provisioning Engine will store this information and automatically connect to your network, and the user will get a seamless connection experience.
  • Choose the back-end interaction. For purchasing the plan, the user can use limited (“walled garden”) connectivity, alternate Internet connectivity (home, coffee shop), or control channel protocols (USSD). Windows supports all these methods, and your application can use one or more ways to connect to your back end.

Account Management

  • View current data usage. Users can view their current data usage and understand their billing cycle (or session end date) to make an appropriate decision on their data usage.
  • Manage account settings. Users can view and securely manage their payment and account details (like password, email address, and automatic payment information).
  • Pay a bill. Users can pay their recurring or one-time bill by using your Metro style app.

Design considerations:

  • Make data usage a combination of local and back-end information - Windows provides a local Data Usage API that you can use to combine back-end data usage.
  • Periodically update Windows with data usage. Windows 8 is designed to behave intelligently on metered networks. To be more accurate and to include more information for applications (for example, data limits and usage), Windows relies on operators to provide correct information periodically. This information can be set by your app using Data Usage APIs.

image

Help and Support

Design considerations include the following:

  • Simplify the user experience by retrieving device information. You will want to show only appropriate help for the user’s device. You can get device model and firmware information by using the Subscriber and Device Information API.

Premium Services

You can use Metro style apps for discovering and consuming additional services. As an operator, you are increasingly trying to upsell your customer base by providing value-added services such as navigation, mobile TV, music services, movie streaming, and online storage.

image

Notifications

You want to keep your users informed through service notifications such as “plan activation status”, “approaching data cap”, and “currently roaming”. Windows supports existing channels like Short Message Service (SMS), Unstructured Supplementary Service Data (USSD), and Windows Notification Service to trigger notifications to your app.

image

You can also develop a messaging experience in your app that will show a history of alerts that came from the operator.

Live Tile Updates

Hot-Spot Authentication

You want to offload data traffic to Wi-Fi hot spots whenever possible. Windows Connection Manager can automatically connect to Wi-Fi networks when they are available. For connecting to Wi-Fi networks, you must provide hot-spot credentials to Windows. You can provide hot-spot credentials through account provisioning metadata, or you can use implement your own authentication in the app.

APIs

  • SMS API - Provides functions that are required to implement an SMS client.
  • Subscriber and Device Information API - Provides subscriber information for the SIM and device information for the mobile broadband adapter.
  • USSD API - Enables the operator account experience to establish a USSD session with a network (client and network initiated).
  • Connection Profile API - Provides information about the connection status (for example, to the Internet).
  • Provisioning API - Enables the operator account experience to provision Windows by using the account provisioning data.
  • Data Usage API - Enables the operator account experience to inform Windows about the subscriber’s current data usage.
  • SIM PIN API - Enables the operator account experience to enable, disable, or change the SIM PIN.
  • Device Services Extension API - Enables device-specific extensions, such as SIM Toolkit and Preferred Roaming List (PRL) download.

The Subscriber and Device Information API provides the following subscriber and device information to the operator account experience:

  • Device name. Name of the device.
  • Technology. GSM, CDMA, and similar information.
  • Subscriber and device ID. Subscriber and device identification information (IMSI, IMEI, electronic serial number [ESN], and similar information)
  • Manufacturer. Manufacturer of the device.
  • Mobile number. Mobile number that is associated with the device.
  • SIM ID. ICCID that is associated with SIM.
  • Device capabilities. Device interface capabilities, such as GSM Band Class and CDMA Band Class.
  • Firmware and hardware version. Firmware and hardware.

By using the SIM PIN API, the app can support of operations that are related to the SIM PIN and the Pin Unlock Key (PUK).

By using the Connection Profile API, the app can query the status of the network connection on the operator’s mobile broadband interface. The available statuses are:

  • Local access. There is connectivity to a routed network on the operator’s interface.
  • Full Internet access. There is connectivity to the Internet on the operator’s interface.

This API also includes a status change event that notifies the application whenever connectivity on the operator’s interface has changed.

Any device services that are not natively implemented by the Windows wireless platform can be accessed via the Device Services Extension API.

MobileBroadbandAccountStatics, MobileBroadbandAccountWatcher

Preparing to Develop Metro style Device Apps for Mobile Broadband

Most mobile network operators will need to create a new account on the Windows Dev Center - Hardware Dashboard. Only mobile network operators or mobile virtual network operators can submit metadata for Metro style apps for mobile broadband. VeriSign is used to validate the company account that is being created to ensure the person creating the account is authorized and does indeed work for the company they are trying to create. The user must obtain a VeriSign certificate for their company.

Designing User Experience of Metro Style Device Apps for Mobile Broadband

Your Metro style app is available to end users as a tile on the Start screen, in the connection manager, or through a toast notification.

Developing Apps with Mobile Broadband SMS

Windows Developer Preview provides a Short Message Service (SMS) text messaging platform for mobile network operators and general application developers who want to integrate SMS.

The mobile broadband SMS platform provides:

  • Sending and reading SMS data in text-mode or PDU-mode (binary)
  • Filtering for data cap overage, roaming, and other administrative SMS from operator
  • New SMS received background event
  • Reading messages from the mobile broadband device message store
  • Deleting messages from the mobile broadband device message store
  • Getting properties of the mobile broadband device
  • SMS API access prompt

Supported devices

SMS messaging with mobile broadband network adapters.

image

Basic requirements

  • PC running Windows 8, mobile broadband device, and active service from a mobile network operator.
  • The device should be Windows Mobile Broadband logo certified with the SMS send/receive capabilities set. 
  • Internal and external devices are supported.
  • Both GSM- and CDMA-based devices are supported. 

Picture messaging, video messaging, and other types of multimedia messaging are not supported in the mobile broadband SMS platform.

Filtering for operator SMS notifications

The mobile broadband SMS platform filters new received SMS data into one of two types: administrative SMS notifications from a MNO and general SMS messages. Administrative SMS notifications received from a mobile network operator are only accessible to the MNO Metro style application and are hidden from general SMS client apps.

Mobile network operators specify custom filtering rules for administrative SMS notifications in the Windows Provisioning platform. If no message filtering rules are specified, then SMS platform classifies all SMS messages as general SMS messages available to any application.

General SMS API

An app must request access by declaring SMS capability in its package manifest.

Enumerating SMS devices

var smsDevice = new Windows.Devices.Sms.SmsDevice.getDefault();

Windows.Devices.Enumeration.DeviceInformation.findAllAsync(Windows.Devices.Sms.SmsDevice.getDeviceSelector()).then(function (smsdevices) {

       if (smsdevices.length > 0) {

               // for simplicity we choose the first device

                // we strip out the Device Interface Id

               var startIndex = smsdevices[0].Id.indexOf("{");

               var endIndex = smsdevices[0].Id.indexOf("}");

               var smsDeviceId = smsdevices[0].Id.slice(startIndex,endIndex + 1);

               var smsDevice = new Windows.Devices.Sms.SmsDevice.fromId(smsDeviceId)

       }

Sending SMS with text-mode interface

Application developers can choose between using the text-mode send interface, suitable for simple plain text SMS messages, or the PDU-mode mode send interface for advanced control of the SMS message sent.

Windows automatically chooses the optimal character encoding. Application developers can optionally override the optimal encoding functionality and specify which character set to use.

try {

    if (smsDevice != null) {

            // defines a text message

            var smsMessage = new Windows.Devices.Sms.SmsTextMessage();

            smsMessage.to = id("phoneNumber").value;

            smsMessage.body = id("messageText").value + "\n\nSent via Windows 8 SMS API";

            var sendSmsMessageOperation = smsDevice.sendMessageAsync(smsMessage);

            console.log("Sending message...");

            sendSmsMessageOperation.then(function (reply) {

                console.log("Text message sent.");

            });

    } else {

        console.log("No SMS device found");

    }

} catch (err) {

    console.log("SMS exception: " + err);

}

Windows automatically segments long messages into multiple parts.

Calculating characters remaining and segments used of a draft SMS

var smsMessage = new Windows.Devices.Sms.SmsTextMessage();

smsMessage.body = id('messageText').value; // Set message body text to text of messageText HTML element

var messageLength = smsDevice.calculateLength(smsMessage);

id('remainingCharsCount').innerText = messageLength.charactersPerSegment - messageLength.characterCountLastSegment;

id('messageSegmentsCount').innerText = messageLength.segmentCount;

Specifying mobile phone numbers

Phone numbers must be specified in ITU E.164 format. The “+” prefix in front of the first digit in the phone number is optional. SMS short codes that have short phone numbers 4-6 digits long and are typically used to communicate with automated MNO services are supported.

Reading received SMS with the text-mode interface

Developers can choose between using the text-mode read interface, suitable for simple plain text SMS messages, or the PDU-mode mode read interface for advanced control of decoding SMS messages. Received messages are stored in encoded format on mobile broadband devices. SMS platform supports decoding received messages to plain text.

try {

       if (smsDevice!= null) {

               var messageStore = smsDevice.messageStore;

               var messageID = id('whichMessage').value;

 

               var getSmsMessageOperation = messageStore.getMessageAsync(messageID);

              getSmsMessageOperation.operation.completed = function () {

                      result = getSmsMessageOperation.operation.getResults();

                      var readableMessage = new Windows.Devices.Sms.SmsTextMessage.fromBinaryMessage(result);

                      id('fromWho').innerHTML = readableMessage.from;

                      id('fromMessageBody').innerHTML = readableMessage.body;

                      console.log("Successfully retrieved message " + messageID + " from message store.");

               }

               getSmsMessageOperation.operation.start();

       }

       else {

               console.log("No SMS Device Found");

       }

}

catch (err) {

       console.log("SMS did not set up: " + err);

}

Device SMS storage limits

SMS client apps should use SMS device storage as a message queue. Total SMS storage on devices varies, but device storage is commonly limited to 30 messages.

The Windows SMS platform is designed to maintain the ability to receive new incoming SMS messages by freeing up SMS device storage space while minimizing deletion of user data.

Devices can’t receive new SMS messages if SMS storage becomes full. Windows automatically deletes old SMS messages from device storage to ensure the ability to receive new incoming SMS data, such as important MNO notifications.

Recommendations:

  • SMS client apps should use local application storage to maintain message history instead of relying on device SMS storage.
  • SMS client apps should not delete messages on read. SMS client apps should let Windows automatically delete old messages when device storage gets full.

Getting SMS device information

The SMS platform provides information about the mobile broadband device, including account phone number, status, and cellular class.

var mobileNumber = smsDevice.accountPhoneNumber;

New SMS received background event

The mobile broadband SMS platform provides separate system events for new SMS data received depending on whether it’s an administrative SMS notification from a mobile network operator or a general SMS messages. The background system event for new administrative SMS notification received from a mobile network operator (MNO) is only accessible by an MNO Metro style application.

Apps must have already gotten user consent to use SMS in order to read new received SMS messages in a background tasks.

namespace SmsBackgroundSample

{

public sealed class SmsBackgroundTask : IBackgroundTask

{

        //

        // The Run method is the entry point of a background task.

        //

        public void Run(IBackgroundTaskInstance taskInstance)

        {

    

            //

            // Associate a cancellation handler with the background task.

            //

            taskInstance.Canceled += new BackgroundTaskCanceledEventHandler(OnCanceled);

 

            ManualResetEvent manualEventWaiter = new ManualResetEvent(false);

       

            manualEventWaiter.Reset();

           

            //

            // Do the background task activity.

            //

            DisplayToastAsync(taskInstance, manualEventWaiter);

 

            //

            // Wait until the async operation is done. We need to do this else the background process will exit.

            //

            manualEventWaiter.WaitOne(5000);

 

            Debug.Print("Background " + taskInstance.Task.Name + (" process ran"));

 

        }

 

        async void DisplayToastAsync(IBackgroundTaskInstance taskInstance, ManualResetEvent manualEventWaiter)

        {

            SmsReceivedEventDetails smsDetails = (SmsReceivedEventDetails)taskInstance.TriggerDetails;

 

            SmsDevice smsDevice = SmsDevice.FromId(smsDetails.DeviceId);

 

            SmsBinaryMessage smsEncodedmsg = (SmsBinaryMessage)await smsDevice.MessageStore.GetMessageAsync(smsDetails.MessageIndex);

 

            SmsTextMessage smsTextMessage = Windows.Devices.Sms.SmsTextMessage.FromBinaryMessage(smsEncodedmsg);

 

            XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(ToastTemplateType.ToastText02);

 

            XmlNodeList stringElements = toastXml.GetElementsByTagName("text");

 

            stringElements.Item(0).AppendChild(toastXml.CreateTextNode(smsTextMessage.From));

 

            stringElements.Item(1).AppendChild(toastXml.CreateTextNode(smsTextMessage.Body));

 

            ToastNotification notification = new ToastNotification(toastXml);

            ToastNotificationManager.CreateToastNotifier().Show(notification);

 

            manualEventWaiter.Set();

        }

 

}

var triggerAway = new Windows.ApplicationModel.Background.SystemTrigger(Windows.ApplicationModel.Background.SystemTriggerType.smsReceived, false);

var builderAway = new Windows.ApplicationModel.Background.BackgroundTaskBuilder();

builderAway.setTrigger(triggerAway);

builderAway.taskEntryPoint = "HelloWorldBackground.BackgroundTask1";

builderAway.name = "Sms";

var taskAway = builderAway.register();

taskAway.addEventListener("progress", new ProgressHandler(taskAway).onProgress);

taskAway.addEventListener("completed", new CompleteHandler(taskAway).onCompleted);

SMS access consent prompt

Users in Windows 8 can control access to SMS capability at an app level. Through the settings charm, a user has the ability to grant or deny access to a particular application.

Limited CDMA support

The SMS platform supports sending and receiving 7-bit (ASCII) messages only. Automatic segmentation of long messages into separate parts is not supported.

Development Guide to Creating Metro style Device Apps for Mobile Broadband

The Mobile Broadband Metadata Authoring Wizard is the recommended way of creating metadata packages.

Mobile Operator Notifications

The background events offered by the Network Operator API, including the MobileOperatorNotification event and HotspotAuthentication event, are treated by Windows as critical events. Compared to general background events in Windows 8, background work items associated with MobileOperatorNotification and HotspotAuthentication events will execute for every instance of the event regardless of a processing time quota, though each instance of the background work item is subject to a processing time quota.

Submitting a Metro style Device App for Mobile Broadband

Notatki o Windows 8 Consumer Preview - odc. 19

W dzisiejszym odcinku będzie trochę hardcorowo, a mianowicie pozwolę sobie na cytaty z części niszowych dokumentów poświęconych tworzeniu aplikacji Metro dla urządzeń w ujęciu ogólnym oraz w dedykowanym przypadku dla kamer internetowych. Starałem się wyłapać ogólny sens i różne ciekawostki, które mogą być użyteczne nawet, gdy tylko będziemy korzystać z jakiegoś urządzenia w Windows 8. Niskopoziomowe szczegóły oczywiście zawarte są w dokumentach i przydadzą się producentom urządzeń (ewentualnie pasjonatom).

Metro style Device Apps

A Metro style device app involves several components:

  • Metro style Device Apps  - The Metro style Device App Lifecycle
  • Device Metadata in Windows 8 - Like in Windows 7, device manufacturers can use the device metadata system to deliver a device experience in Devices and Printers and Device Stage for a connected device or the PC. New to Windows 8, the device metadata system can also link the device or PC to Metro style device apps.
  • Device Drivers

Device Categories

  • Printers
  • Mobile Broadband
  • Cameras
  • Networked Entertainment Devices (Play To)
  • Specialized Devices

When the user plugs in or pairs a new device with the PC, Windows will identify the manufacturer and model of the device and then download the remaining components from Microsoft online services like Windows Update and Windows Store automatically. The user can also manually download it from the Windows Store. An Independent Software Vendor (ISV) may create the Metro style device app in partnership with the Independent Hardware Vendor (IHV), which supplies the device metadata and driver.

Device metadata is a set of XML files that create the link between a particular device and its Metro style device app. In addition to UI content for the device (localizable model name, description & photorealistic icons) the device metadata package indicates which app Windows should download. Device Metadata is authored using the Device Metadata Authoring Tool, and submitted to the Windows Hardware Center Dashboard.

Visual Studio 2011 Ultimate is required because it includes the Metadata Authoring Tool. Visual Studio 2011 Express doesn’t include WDK support or the recommended metadata tools.

image

Experience ID is part of the required information that the Windows Store uses when validating the Metro style device app. It is a 128-bit Globally Unique Identifier (GUID). The application developer then specifies in a file named StoreManifest.xml using a <ExperienceId> tag. The GUID is automatically generated by the Metadata Authoring Tool, and can be found in the PackageInfo XML component of the device metadata

image

 

<?xml version="1.0" encoding="utf-8"?>

<StoreManifest

  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

  xsi:noNamespaceSchemaLocation="StoreManifest.xsd"

  xmlns="http://schemas.microsoft.com/appx/2010/StoreManifest">

 

  <ProductFeatures>

    <DeviceCompanionApplication>

      <ExperienceIds>

        <ExperienceId>F9D916A7-AFD3-445B-8B9C-5B6466831C9E</ExperienceId>

        <ExperienceId>4A393BAA-DE6B-4B9A-A4BC-35FDE4A97FB2</ExperienceId>

      </ExperienceIds>

    </DeviceCompanionApplication>

</ProductFeatures>

 

</StoreManifest>

Each Device Metadata package can only reference a single Metro style device app, but the store manifest for a Metro style device app may list several Device Experience IDs, since many device models may use the same app.

If the Metro style device app is for a specialized device or a mobile broadband device, the app needs to declare the device interface in the application manifest (package.appxmanifest).

You must submit your device driver (if any) and your Metro style device app before you can submit device metadata.

There are three ways by which device software is acquired by the user:

  • Automatic Acquisition - The app is automatically acquired the first time an externally connected device is connected. This is the most common way Metro style device apps are acquired.
  • Windows Store Download - A user may find and purchase the app directly from the Windows Store. This is typically how app updates or additional apps are distributed.
  • OEM Preinstall - An app for a PC internal system component can be preloaded by an OEM as part of a new PC.

Automatic Acquisition

The user opts in to the Recommended Settings during Windows installation. This allows Windows to acquire drivers from Windows Update, metadata from WMIS, and the Metro style device app from the Windows Store.

Uninstalling Device Software

Devices may be uninstalled by the user. Only the driver and metadata are automatically uninstalled as part of device uninstall. The user needs to manually uninstall the Metro style device app. The user may choose to uninstall the Metro style device app without uninstalling the device as well, if they do not feel the app adds value to their experience.

Updating the Device Software Components

Updating Drivers

Driver updates are distributed through Windows Update as optional updates, provided that the user has opted in to receiving updates from Windows Update. Driver updates are not automatically distributed to devices if they have completed device setup, and already have metadata and drivers installed. Driver updates are not coupled to app updates, so driver updates should be designed to ensure compatibility with existing apps. If a driver update is distributed through Windows Update, or if the user manually reinstalls or updates the driver, the app should handle this appropriately.

Updating Device Metadata

The metadata that’s distributed by WMIS may be updated to point to a new or different Metro style device app.

Approximately 8 to 15 days after the submission of updated metadata that indicates a new app, new devices that are connected and set up for the first time will get the new app.

However, a new app indicated in updated metadata is not automatically distributed to PCs for which the device setup is already complete, because the users have previously received device metadata for the device. The Metro style device app is automatically downloaded only once, when the device is initially set up.

If the device metadata is updated to point to a different app, the old Metro style device app should advertise the new one to the user, so that users can acquire it from the Windows Store manually. Eventually, the old app should be removed from the Windows Store.

Users can also get to the new app, if they go to the Settings > Devices Page and click the ‘Get app’ link for that device.

Updating the Metro style Device App

Metro style device app updates are manually triggered by users, just like any other Metro style app updates. The Windows Store shows all available application updates to the user. The user manually chooses to update the app.

You should design apps to be compatible with older metadata and drivers. The device metadata or driver might not be up-to-date with the app, since manual installation of a Metro style device app from the Windows Store doesn’t automatically trigger distribution of metadata or drivers.

Metro style Device Apps for Cameras

image

Links

Your camera’s driver must use the AvStream driver model.

Windows 8 offers IHVs and system OEMs the ability to create video processing plug-ins in the form of a Media Foundation Transform (MFT). This special MFT is known as the driver MFT. It is also known as MFT0 to indicate it is the first MFT to operate in the source reader. A separate instance of MFT0 is attached to every pin on the capture source. For some system OEMs, the AVStream capture driver must support a preview pin, a capture pin, and a still pin. This means that there may be three instances of MFT0.

Two popular functions for MFT0 are:

  • Analyzing the video stream to provide feedback to the camera for improved capture (such as host-based auto focus and auto exposure).
  • Adding video effects.

Additionally, there are two final compounding factors:

  • Each instance of the MFT0 may be created or shut down at any time.
  • The Metro style device app is only connected to one instance of the MFT0, currently the one associated with the preview pin.

When your camera’s Metro style device app is registered with Windows, the features it implements are automatically made available to any Metro style apps that call the Windows.Media.Capture.CameraOptionsUI.Show API to display a camera options user interface.

image

The Driver MFT is the Media Foundation Transform (MFT) that implements the effects. This media extension that provides the effects is an implementation of IMediaTransform. This MFT is the first transform applied to the video stream coming out of the driver.

A Metro style device app for camera can be launched in two different contexts: the Start experience (when the app is launched from the app tile in the Start screen), and the Options experience.

image

 

image

 

A Metro style device app that is declared as a camera settings extension can be activated by Windows when a user clicks the Options button or an app calls Windows.Media.Capture.CameraOptionsUI.Show. The Metro style device app then handles the event that is raised when the app is activated

image

var activatedHandler = function (eventArgs) {

        var kind = eventArgs.detail.kind;

        var activationType =

            Windows.ApplicationModel.Activation.ActivationKind;

        if (kind === activationType.cameraSettings)

        { 

           // Initialize logic for the flyout that provides camera

           // effects here.

 

        } else if (kind === activationType.launch)

        {

           // Do not provide settings or effects if launched.

           // Instead, you may provide support, services,

           // or other functionality that does not apply effects.   

 

        }

}

WinJS.Application.start();

WinJS.Application.addEventListener("activated", activatedHandler, false);

namespace CameraMetrostyleDeviceApp

{

    public partial class App

    {

        public App()

        {

            InitializeComponent();

        }

 

        protected override void OnLaunched(

             LaunchActivatedEventArgs args)

        {

            // Initialize the start page

            Window.Current.Content = new StartPage();

            Window.Current.Activate();

        }

 

 

        protected override void OnActivated(IActivatedEventArgs args)

        {

            if (args.Kind == ActivationKind.CameraSettings)

            {

                base.OnActivated(args);

                MainPage page = new MainPage();

                Window.Current.Content = page;

 

           // The args object contains properties for

           // controlling the device settings                      

              page.Initialize((CameraSettingsActivatedEventArgs)args);

 

                Window.Current.Activate();

            }

        }

    }

}

Type Windows.ApplicationModel.Activation.CameraSettingsActivatedEventArgs exposes two properties for controlling the camera.

  • The VideoDeviceController property provides methods for adjusting standard settings. It is an object of type Windows.Media.Devices.VideoDeviceController.
  • The VideoDeviceExtension is a pointer to the Driver MFT interfaces for applying custom settings.

var videodev = null;

var videoext = null;

var lcWrapper = null;

 

function activatedHandler(eventArgs) {

    if (eventArgs.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.cameraSettings) {

        videoext = eventArgs.detail.videoDeviceExtension;

        videodev = eventArgs.detail.videoDeviceController;

 

        if (videoext !== null) {

            initializeExtension(videoext);

        }

 

        if (videodev !== null) {

            initializeSlider();

            // do other initialization here…

        }

    }

}

 

WinJS.Application.start();

WinJS.Application.addEventListener("activated", activatedHandler, false);

 

function initializeExtension(mft0) {

    lcWrapper = Wrapper.WinRTComponent();

    lcWrapper.initialize(mft0);

}

 

// Initialize a slider element using the VideoDeviceController object

function initializeSlider() {

    try {

        var bValue = 0;

        var bAuto = 0;

        var slider;

            if (videodev != null) {

                bValue = videodev.brightness.tryGetValue();

                slider = document.getElementById("slBrt");

                slider.value = bValue.value;

                slider.min = videodev.brightness.capabilities.min;

                slider.max = videodev.brightness.capabilities.max;

            }

}

If your Metro style device app is more than 560 pixels in height, the user may slide or scroll to view parts of the app that are above or below the viewable area. A Metro style device app should not exceed 340 pixels in width.

Suggested effects
  • Color effects, such as grayscale, sepia tone, or solarizing the entire picture.
  • Face-tracking effects - these are often overlays, where a face is identified in the picture and an overlay, such as a hat or a pair of glasses, is added on top of it.
  • Scene modes - these are preset exposure and focus modes for different lighting conditions.
Suggested settings
  • Your Metro style device app can provide a switch to enable hardware-implemented settings, such as color correction schemes. Some examples of color correction schemes are TrueColor and RightColor.
  • Implement basic properties that supplement the other settings exposed by your Metro style device app. For example, many devices may expose controls for adjusting brightness, contrast, flicker, focus, and exposure, but a device that implements TrueColor to automatically adjust the brightness and contrast may not need to provide these settings.

Restrictions

  • Do not show a user interface for selecting settings or effects if the app is launched from its tile in Start rather than from a capture app. Settings will not persist from the Start experience.
  • Do not provide a preview or otherwise take ownership of the video stream from inside your Metro style device app.
  • Do not adjust resolution in your Metro style device app.
  • Do not attempt to display pop-ups, notifications, or dialogs outside of the area intended for the Metro style device app’s Options experience
  • Do not declare the Webcam, Microphone, SMS device capabilities

image

The Metro style device app for camera runs in a different process than the app that is capturing from the camera.

Note that the Driver MFT is not strictly required for a Metro style device app, but it supplies the custom settings and effects. A device manufacturer may choose to implement a Metro style device app without a Driver MFT, simply to provide a differentiated user interface containing branding for their hardware, without applying custom effects to the video stream.

The Driver MFT implements IMFTransform. It also must be exposed to the Windows Runtime, so it must also implement IInspectable.

A Driver MFT is registered with Windows as a COM interface so that the transform it implements can be applied to the media stream coming out of a specific device, such as a camera. When an app initiates a video capture, a Media Foundation Source Reader is instantiated to provide the video stream. This media source reads a registry value from the device registry key. If the CLSID of the Driver MFT’s COM class is found in the registry value, the source reader instantiates the Driver MFT and inserts it into the media pipeline.

In addition to Metro style device apps, the Driver MFT functionality can be accessed when the device associated with it is used to capture video using the following APIs:

  • HTML5 <video> tags in a Metro style app using HTML.
  • Windows.Media.MediaCapture API in a Metro style app using the Windows Runtime

To write a Metro style device app in C# or JavaScript that interacts with a Driver MFT, you need to create an additional component in the Metro style device app’s Visual Studio project. This component is a wrapper that exposes the Driver MFT interfaces in a Windows Runtime Component that is visible to the Metro style device app.

 

KSCATEGORY_VIDEO_CAMERA:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceClasses\{E5323777-F976-4f5b-9B55-B94699C46E44}\##?#USB#VID_045E&PID_075D&MI_00#8&23C3DB65&0&0000#{E5323777-F976-4f5b-9B55-B94699C46E44}\#GLOBAL\Device Parameters]

"CLSID"="{17CCA71B-ECD7-11D0-B908-00A0C9223196}"

"FriendlyName"="USB Video Device"

"RTCFlags"=dword:00000010

"CameraPostProcessingPluginCLSID"="{3456A71B-ECD7-11D0-B908-00A0C9223196}"

Internal cameras embedded inside a portable computer do not have their Metro style device app downloaded, because there is no act of connecting the camera to trigger the download.

You submit your camera’s Metro style device app to the Windows Store or preinstall it, in the case of internal cameras.