> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XPackageRegisterInstallationProgressChanged

> XPackageRegisterInstallationProgressChanged

# XPackageRegisterInstallationProgressChanged

Registra um retorno de chamada a ser chamado quando o progresso da instalação mudar.

## Sintaxe

```cpp theme={null}
HRESULT XPackageRegisterInstallationProgressChanged(  
         XPackageInstallationMonitorHandle installationMonitor,  
         void* context,  
         XPackageInstallationProgressCallback* callback,  
         XTaskQueueRegistrationToken* token  
)  
```

### Parâmetros

*installationMonitor*   \_In\_\
Tipo: XPackageInstallationMonitorHandle

Um identificador para o monitor de instalação com o qual o retorno de chamada deve ser registrado.

*context*   \_In\_opt\_\
Tipo: void\*

Contexto a ser passado para o retorno de chamada.

*callback*   \_In\_\
Tipo: XPackageInstallationProgressCallback\*

Retorno de chamada definido pelo usuário a ser chamado quando o progresso da instalação mudar.

*token*   \_Out\_\
Tipo: [XTaskQueueRegistrationToken\*](/pt-BR/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken)

Um token que identifica o retorno de chamada e que pode ser usado para cancelar o registro do retorno de chamada posteriormente, usando [XPackageUnregisterInstallationProgressChanged](/pt-BR/reference/system/xpackage/functions/xpackageunregisterinstallationprogresschanged).

### Valor retornado

Tipo: HRESULT

Código de sucesso ou de erro HRESULT.

## Comentários

Um jogo implementou um marcador de inicialização para que possa ser executado antes de ser totalmente instalado. O jogo precisará saber quais partes estão instaladas e quais não estão. Neste exemplo, o jogo precisa saber quando as partes associadas a uma pista de corrida com o nome de pista especificado estão instaladas:

```cpp theme={null}
void CALLBACK ProgressChangedCallback(
    void* /* context*/,
    XPackageInstallationMonitorHandle monitor)
{
    XPackageInstallationProgress progress;
    XPackageGetInstallationProgress(monitor, &progress);

    if (progress.completed)
    {
        printf("Track ready\n");
        XPackageCloseInstallationMonitorHandle(monitor);
    }
}

HRESULT StartMonitoring(XTaskQueueHandle queue, char* trackName)
{
    char id[XPACKAGE_IDENTIFIER_MAX_LENGTH];

    HRESULT hr = XPackageGetCurrentProcessPackageIdentifier(_countof(id), id);
    if (FAILED(hr)) return hr;

    XPackageChunkSelector selector;
    selector.type = XPackageChunkSelectorType::Tag;
    selector.tag = trackName;

    XPackageInstallationMonitorHandle monitor;
    hr = XPackageCreateInstallationMonitor(
        id,         // Identity to be monitored
        1,          // Number of selectors
        &selector,  // Selectors
        1000,       // Resolution of the monitor, in milliseconds
        queue,      // Queue where updates are performed
        &monitor);
    if (FAILED(hr)) return hr;

    XTaskQueueRegistrationToken token;
    hr = XPackageRegisterInstallationProgressChanged(
        monitor,
        nullptr,
        ProgressChangedCallback,
        &token);

    if (FAILED(hr))
    {
        XPackageCloseInstallationMonitorHandle(monitor);
    }

    return hr;
}
```

Vamos examinar cada chamada de API no código mostrado acima:

```cpp theme={null}
XPackageGetCurrentProcessPackageIdentifier(_countof(id), id);
```

Todo conteúdo instalado terá um identificador exclusivo. Você pode monitorar a instalação de qualquer pacote se souber o identificador do pacote e tiver acesso a esse conteúdo. Um processo em execução pode obter seu próprio identificador de pacote. Para obter mais informações sobre identificadores de pacote, consulte [Gerenciar e licenciar conteúdo baixável (DLC)](/pt-BR/publishing/xstore-commerce/xstore-dlc).

```cpp theme={null}
XPackageCreateInstallationMonitor(
    id,         // Identity to be monitored
    1,          // Number of selectors
    &selector,  // Selectors
    1000,       // Resolution of the monitor, in milliseconds
    queue,      // Queue where updates are performed
    &monitor);
```

Isso cria um monitor que acompanha o estado da instalação. Esse monitor de instalação se atualiza em uma cadência regular. Para obter o progresso atual de uma instalação, chame [XPackageGetInstallationProgress](/pt-BR/reference/system/xpackage/functions/xpackagegetinstallationprogress); para ser notificado sobre uma alteração durante uma instalação, registre um retorno de chamada.

Você pode criar o monitor de instalação para o pacote inteiro ou para um subconjunto específico. Aqui, você definiu um "seletor" que indica que deseja saber o progresso da instalação de um nome de pista. Você pode especificar uma frequência (neste caso, 1000 ms) que indica com que frequência o monitor de instalação atualizará seu instantâneo do progresso, até essa velocidade. Se nenhum progresso tiver sido feito nesse tempo, poderá ser mais lento.

```cpp theme={null}
XPackageRegisterInstallationProgressChanged(
    monitor,
    nullptr,
    ProgressChangedCallback,
    &token);
```

Você quer saber quando a pista terminou de carregar, então registra um evento de alteração de progresso no monitor. Esse retorno de chamada será invocado por meio da fila de tarefas fornecida quando o monitor foi criado, aproximadamente na cadência especificada em [XPackageCreateInstallationMonitor](/pt-BR/reference/system/xpackage/functions/xpackagecreateinstallationmonitor). Dentro do retorno de chamada, você pode renderizar o progresso no jogo ou notificar o jogo de que uma pista está pronta.

Neste exemplo, você fecha o monitor de instalação, mas não cancela o registro da notificação. O tempo de vida de uma notificação de monitor de instalação está vinculado ao monitor de instalação; portanto, fechar o monitor cancela o registro de todas as notificações associadas a ele.

## Requisitos

**Cabeçalho:** XPackage.h

**Biblioteca:** xgameruntime.lib

**Plataformas compatíveis:** Windows, consoles da família XBOX One e consoles XBOX Series

## Documentação conceitual

* [Intelligent Delivery: especificadores de idioma](/pt-BR/build/core-features/common/packaging/intelligentdelivery-language)
* [Instalação por streaming: status](/pt-BR/build/core-features/common/packaging/packaging-installstatus)

## Confira também

[XPackage](/pt-BR/reference/system/xpackage/xpackage_members)\
[Instalação por streaming e Intelligent Delivery](/pt-BR/build/core-features/common/packaging/overviews/streaming_install-intelligent_delivery)\
[XPackageGetInstallationProgress](/pt-BR/reference/system/xpackage/functions/xpackagegetinstallationprogress)\
[XPackageCreateInstallationMonitor](/pt-BR/reference/system/xpackage/functions/xpackagecreateinstallationmonitor)


## Related topics

- [XPackageRegisterInstallationProgressChanged](/ja-jp/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged.md)
- [XPackageUnregisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageunregisterinstallationprogresschanged.md)
- [XPackageInstallationProgressCallback](/reference/system/xpackage/functions/xpackageinstallationprogresscallback.md)
- [Streaming installation: status](/build/core-features/common/packaging/packaging-installstatus.md)
- [流式安装:状态](/zh-CN/build/core-features/common/packaging/packaging-installstatus.md)