Streaming Installation: Status

While an installation is in progress and a user is playing, the title must track the necessary content to support gameplay and check whether the required content has been installed. A title can use system APIs to query for the status of chunks on the hard drive, as well as for the progress of the downloading content. If the user attempts to enter a portion of gameplay that requires content that is not yet installed, the title should display a dialog box or progress bar to inform the user that this is the case, and communicate the progress of the installation. Also, the title should always offer the user the option of navigating away from the progress screen, ideally to allow the user to experience content that is currently installed.

For example, a user may be playing the single-player campaign of a shooter title and get to the point where the content to support the next area of the campaign is not yet installed. A good user experience would be to display a progress bar that shows the status of content acquisition, along with an option to join a multiplayer game (enabled by including a subset of multiplayer content as part of the required data for launching the title).

A title can monitor progress, verify installation, and receive an alert upon installation:

• Monitoring Progress
• Monitoring Completion
• Receiving notice of installation
• Determining the current state of the installer

Monitoring Progress

The streaming installation API supports monitoring the progress of an installation of packages and of a set of chunks. Progress is monitored using a PackageTransferWatcher instance and the ProgressChanged event. The version of Create used to create the PackageTransferWatcher instance determines whether the ProgressChanged events will show progress of the entire package or a set of chunks.

Monitoring the percentage complete of a package

Use the PackageTransferWatcher class and the ProgressChanged event to monitor installation of a package as a percentage of completion.

auto transferWatcher = Windows::Xbox::Management::Deployment::PackageTransferWatcher::Create(
    Windows::ApplicationModel::Package::Current );

transferWatcher->ProgressChanged += ref new TypedEventHandler<PackageTransferWatcher ^,ProgressChangedEventArgs ^>(
            [=] (PackageTransferWatcher ^ ptm, ProgressChangedEventArgs ^ args){
                
            });  

Monitoring the percentage complete of a set of chunks

Use the PackageTransferWatcher class and the ProgressChanged event to monitor installation of a set of chunks as a percentage of completion.

IVector<uint32> ^chunkIds = ref new Vector<uint32>;
chunkIds->Append(1);
chunkIds->Append(2);
chunkIds->Append(3);
chunkIds->Append(4);

//Create a PackageTransferWatcher for just the specified set of chunk Ids
auto transferWatcher = Windows::Xbox::Management::Deployment::PackageTransferWatcher::Create( 
    Windows::ApplicationModel::Package::Current,
    chunkIds);

transferWatcher->ProgressChanged += ref new TypedEventHandler<PackageTransferWatcher ^,ProgressChangedEventArgs ^>(
        [=] (PackageTransferWatcher ^ ptm, ProgressChangedEventArgs ^ args){
                
        });  

Monitoring Completion

The streaming installation API supports notifying when specific chunks have been installed. A title registers to recieve completion events using a PackageTransferWatcher instance and the ChunkCompleted event or the TransferCompleted event. The ChunkCompleted event is used to monitor when a a single chunk has finished installing. The TransferCompleted event is used to monitor when a set of chunks has finished installing.

Checking whether a single chunk has been installed

Use the PackageTransferWatcher class and the ChunkCompleted event to recieve notification when a single chunk has finished installing.

IVector<uint32> ^chunkIds = ref new Vector<uint32>;
chunkIds->Append(1);
chunkIds->Append(2);
chunkIds->Append(3);
chunkIds->Append(4);

auto transferWatcher = Windows::Xbox::Management::Deployment::PackageTransferWatcher::Create( 
    Windows::ApplicationModel::Package::Current,
    chunkIds);

transferWatcher->ChunkCompleted += ref new TypedEventHandler<PackageTransferWatcher ^,ChunkCompletedEventArgs ^>(
            [=] (PackageTransferWatcher ^ ptm, ChunkCompletedEventArgs ^ args){
                
            });  

Checking whether a set of chunks has been installed

Use the PackageTransferWatcher class and the TransferCompleted event to recieve notification when a set of chunks has finished installing.

IVector<uint32> ^chunkIds = ref new Vector<uint32>;
chunkIds->Append(1);
chunkIds->Append(2);
chunkIds->Append(3);
chunkIds->Append(4);

auto transferWatcher = Windows::Xbox::Management::Deployment::PackageTransferWatcher::Create( 
    Windows::ApplicationModel::Package::Current,
    chunkIds);

transferWatcher->TransferCompleted += ref new TypedEventHandler<PackageTransferWatcher ^,TransferCompletedEventArgs ^>(
        [=] (PackageTransferWatcher ^ ptm, TransferCompletedEventArgs ^ args){
                
        });  

Receiving notice of installation

If your title requires content in a specific chunk for gameplay to continue, use the PackageTransferWatcher class to trigger an event when that chunk has been installed.

auto ptm = Windows::Xbox::Management::Deployment::PackageTransferManager::Current;

IVector<uint32> ^chunkIds = ref new Vector<uint32>;

chunkIds->Append(1);
chunkIds->Append(2);
chunkIds->Append(3);
chunkIds->Append(4);

if( !(ptm->AreChunksInstalled(chunkIds)))
{
    ptm->UpdateInstallOrder(chunkIds,Windows::Xbox::Management::Deployment::UpdateInstallOrderBehavior::InterruptCurrentTransfer);

    auto transferWatcher = Windows::Xbox::Management::Deployment::PackageTransferWatcher::Create( 
    Windows::ApplicationModel::Package::Current,
    chunkIds);
    
    transferWatcher->TransferCompleted += ref new TypedEventHandler<PackageTransferWatcher ^,TransferCompletedEventArgs ^>(
            [=] (PackageTransferWatcher ^ ptm, TransferCompletedEventArgs ^ args){
                
            });
}  

Note Note that there are some system-defined chunks for which progress events will be triggered. Developer code should not make assumptions about the number of chunks in a package. Developer code should pay attention to the ChunkId specified in the ChunkCompletedEventArgs and be tolerant of ChunkIDs which were not specified in the packaging map file.

Determining the current state of the installer

If your code is monitoring an installation and determines that it has taken too long for a chunk to install, check the PackageTransferManager::TransferStatus value to see if the installation has been stopped, been paused, or encountered an error. If the installer is no longer in the Running or Paused state, then you should take action to mitigate this for the user.

You should examine the TransferStatus property once per frame at most. Ideally, you should check it only in response to a chunk taking longer than your title expects or to the user trying to initiate an action they cannot perform until the chunk is present.

Network installations and download times can vary considerably, so applying a simple timeout may lead to false failures. If you have a watchdog for chunk installation and TransferStatus returns Running, you should continue waiting for the chunk and handle the delay in your title code. Do not assume that it has failed.

See the System Behavior When Title Installation Fails (Developer Education Materials > All NDA Whitepapers) white paper on the White Papers XGD page for additional information.