File type activation

Games can register file type associations so that when a user opens a file with a registered extension, the game is launched if it isn't already running or brought to the foreground if it is.

Registering file type associations

To register file type associations, the game must add a FileTypeAssociation element within the DesktopRegistration section of its MicrosoftGame.Config. Games can register multiple file extensions under a single association, as shown in the example below.

<Game configVersion="1">
   <Identity Name="ExampleGame" Publisher="CN=NoPub" Version="1.6.0.0"/>
   <ExecutableList>
      <Executable Name="mygame.exe" TargetDeviceFamily="PC" Id="Game"/>
   </ExecutableList>
   <DesktopRegistration>
      <FileTypeAssociation Name="gameAssociatedFiles" Executable="mygame.exe">
         <DisplayName>Game Supported Files</DisplayName>
         <SupportedFileTypes>
            <FileType>.awesomemapextension</FileType>
            <FileType>.mygameiscoolext</FileType>
         </SupportedFileTypes>
      </FileTypeAssociation>
   </DesktopRegistration>
   <!-- Lots of stuff excluded -->
</Game>

This example registers two file extensions (.awesomemapextension and .mygameiscoolext) with the executable mygame.exe. When a user opens a file with either of these extensions, the game is launched or brought to the foreground.

Handling file activations

Games should register for an XGameActivationCallback using XGameActivationRegisterForEvent. When a file activation occurs, the callback receives an XGameActivationInfo structure with the type field set to XGameActivationType::File and the file field containing the path to the file that was opened.

#include <XTaskQueue.h>
#include <XGameActivation.h>

XTaskQueueHandle g_taskQueue;
XTaskQueueRegistrationToken g_activationToken;

void CALLBACK OnActivation(void* context, const XGameActivationInfo* activationInfo)
{
    switch (activationInfo->type)
    {
    case XGameActivationType::File:
        // activationInfo->file contains the path to the opened file.
        // e.g. Load a custom map, replay, or mod file.
        HandleFileActivation(activationInfo->file);
        break;

    case XGameActivationType::Protocol:
        HandleProtocolActivation(activationInfo->protocolUri);
        break;

    // Handle other activation types as needed...
    default:
        break;
    }
}

void InitializeGame()
{
    XGameActivationRegisterForEvent(g_taskQueue, nullptr, OnActivation, &g_activationToken);
}

void ShutdownGame()
{
    XGameActivationUnregisterForEvent(g_activationToken, true);
}

Note

File type activation is supported on PC only. The FileTypeAssociation element is part of the DesktopRegistration section of MicrosoftGame.Config and does not apply to console targets.

Note

The XGameActivation APIs handle all activation types — protocol, file, and game invite — through a single callback. Games only need to register once with XGameActivationRegisterForEvent and check the XGameActivationType in the callback to determine which kind of activation occurred.

Reference API documentation

See also

XGameActivationRegisterForEvent
XGameActivationUnregisterForEvent
XGameActivationCallback
Protocol activation
MicrosoftGame.config - FileTypeAssociation

  • Last updated on