> ## 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.

# XPackageCreateInstallationMonitor

> XPackageCreateInstallationMonitor

# XPackageCreateInstallationMonitor

Cria um monitor do estado da instalação.

## Sintaxe

```cpp theme={null}
HRESULT XPackageCreateInstallationMonitor(  
         const char* packageIdentifier,  
         uint32_t selectorCount,  
         XPackageChunkSelector* selectors,  
         uint32_t minimumUpdateIntervalMs,  
         XTaskQueueHandle queue,  
         XPackageInstallationMonitorHandle* installationMonitor  
)  
```

### Parâmetros

*packageIdentifier*   \_In\_z\_\
Tipo: char\*

Uma cadeia de caracteres que identifica exclusivamente o pacote instalado no disco. Para obter mais informações sobre identificadores de pacote, consulte [Gerenciar e licenciar conteúdo para download (DLC)](/pt-BR/publishing/xstore-commerce/xstore-dlc).

*selectorCount*   \_In\_\
Tipo: uint32\_t

O número de seletores no parâmetro *selectors*.

*selectors*   \_In\_reads\_opt\_(selectorCount)\
Tipo: [XPackageChunkSelector\*](/pt-BR/reference/system/xpackage/structs/xpackagechunkselector)

Uma matriz de seletores que especificam as partes a serem monitoradas.

*minimumUpdateIntervalMs*   \_In\_\
Tipo: uint32\_t

A resolução do monitor, em milissegundos.

*queue*   \_In\_opt\_\
Tipo: XTaskQueueHandle

A fila na qual as atualizações são executadas.

*installationMonitor*   \_Out\_\
Tipo: XPackageInstallationMonitorHandle\*

No retorno, aponta para o monitor de instalação criado.

### Valor retornado

Tipo: HRESULT

Código de sucesso ou de erro HRESULT.

## Comentários

<Note>Não é seguro chamar esta função em um thread sensível ao tempo. Para obter mais informações, consulte [Threads sensíveis ao tempo](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads).</Note>

**XPackageCreateInstallationMonitor** cria um monitor que acompanha o estado da instalação. O monitor se atualiza em uma cadência regular determinada pelo intervalo de atualização especificado. As atualizações são agendadas na fila de tarefas especificada. Um intervalo de zero especifica que as atualizações nunca devem ser executadas e cria um monitor de instalação que é um instantâneo único da instalação. Se um intervalo zero for passado, o parâmetro queue poderá ser nulo.

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. Esse monitor de instalação pode ser criado para o pacote inteiro ou para um subconjunto específico.

Um jogo implementou um marcador de inicialização, portanto, ele pode 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 analisar 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.

```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 você deseja saber sobre 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 no tempo, ela poderá ser mais lenta.

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

Você deseja saber quando a pista terminou de carregar, portanto, 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 do monitor de instalação está vinculado ao monitor de instalação; portanto, fechar o monitor cancela o registro de todas as notificações para 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

* [Instalação por streaming: status](/pt-BR/build/core-features/common/packaging/packaging-installstatus)
* [Threads sensíveis ao tempo](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)
* [Verificando atualizações](/pt-BR/publishing/xstore-commerce/xstore-checking-updates)

## Confira também

[XPackage](/pt-BR/reference/system/xpackage/xpackage_members)


## Related topics

- [XPackageCreateInstallationMonitor](/reference/system/xpackage/functions/xpackagecreateinstallationmonitor.md)
- [XPackageInstallationProgressCallback](/reference/system/xpackage/functions/xpackageinstallationprogresscallback.md)
- [XPackageRegisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged.md)