Skip to main content

XPackageCreateInstallationMonitor

Cria um monitor do estado da instalação.

Sintaxe

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). selectorCount   _In_
Tipo: uint32_t
O número de seletores no parâmetro selectors. selectors   _In_reads_opt_(selectorCount)
Tipo: 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

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.
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; 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:
Vamos analisar cada chamada de API no código mostrado acima:
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.
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; 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.
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. 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

Confira também

XPackage
Last modified on October 6, 2026