​

API XBOX PC Remote Iteration

Proporciona funciones para copiar archivos e iniciar, reanudar y finalizar juegos en dispositivos remotos basados en Windows.

​

Introducción

​

Información general

La API XBOX PC Remote Iteration habilita flujos de trabajo de desarrollo basados en PC dirigidos a dispositivos Windows remotos. Proporciona un conjunto de funciones de C para transferir archivos de juego entre un PC local y un dispositivo remoto, iniciar y administrar procesos de juego en el dispositivo remoto y registrar juegos para su ejecución remota. La API está diseñada para ciclos de iteración rápidos durante el desarrollo de juegos, lo que permite a los desarrolladores compilar localmente e implementar y probar en hardware remoto sin administración manual de archivos.

​

Cuándo usarla

• Implementación de compilaciones de juegos desde un PC local en un dispositivo Windows remoto durante el desarrollo.
• Copia de archivos actualizados (copia diferencial) en un dispositivo remoto para minimizar los tiempos de transferencia durante las compilaciones iterativas.
• Inicio, suspensión, reanudación y finalización de procesos de juego en un dispositivo remoto desde el PC de desarrollo.
• Automatización de flujos de trabajo de compilación, implementación y prueba en canalizaciones de integración continua dirigidas a dispositivos Windows remotos.
• Creación de herramientas de estudio personalizadas, o integración en ellas, para la implementación en dispositivos Windows remotos de forma local o en laboratorios de pruebas.

​

Cuándo NO usarla

• No use esta API para la implementación comercial ni de producción de juegos en consolas de usuarios finales.
• No use esta API para transferir archivos entre dos dispositivos remotos; uno de los extremos debe ser el PC local.
• No use esta API si el dispositivo remoto no se ha emparejado y configurado para el desarrollo remoto.

​

Requisitos previos

• Paquete NuGet: Microsoft.GDK.RemoteIterationClientApi versión 0.1.0-preview.26.3.6001 o posterior.
• Emparejamiento de dispositivos: El PC local y el dispositivo remoto deben estar emparejados y ser mutuamente de confianza mediante la aplicación XBOX PC Toolbox para aprovisionarlos.
• wdEndpoint: wdEndpoint debe estar instalado y en ejecución en el dispositivo remoto. La instalación de XBOX PC Toolbox instala y configura wdEndpoint de forma predeterminada.
• Encabezado y biblioteca: Incluya WdRemoteIteration.h y vincule con wdremoteapi.lib.

​

Funciones

​

Estructuras

​

Enumeraciones

​

Devoluciones de llamada

​

Modelo de subprocesos

La API XBOX PC Remote Iteration está diseñada para operaciones de copia de un solo subproceso. Se aplican las reglas siguientes:

• Una copia a la vez. Solo puede haber una llamada a WdRemoteCopy activa en un momento dado, independientemente del dispositivo de destino o de la ruta de acceso de destino. Llamar a WdRemoteCopy mientras hay otra copia en curso da lugar a un comportamiento indefinido.
• Las demás funciones son seguras durante una copia. Funciones como WdLaunchRemoteGame, WdTerminateRemoteGame, WdResumeRemoteGame y WdRegisterRemoteXboxGame se pueden llamar desde subprocesos independientes mientras hay una copia en curso.
• Todas las funciones son de bloqueo. Cada función de la API bloquea el subproceso que realiza la llamada hasta que la operación se completa o falla. WdRemoteCopy, en particular, puede bloquear durante un período prolongado en función del tamaño de la transferencia y de las condiciones de la red.
• La cancelación es segura para subprocesos. Se puede llamar a WdCancelRemoteCopy desde cualquier subproceso. Si varios subprocesos intentan cancelar la misma operación simultáneamente, las llamadas se serializan internamente: la primera se realiza correctamente y las llamadas posteriores devuelven un error porque ya no queda nada que cancelar.
• No hay estado de conexión entre llamadas. Cada llamada a la API establece su propia conexión con el dispositivo remoto. No hay una sesión persistente; por ejemplo, si la conexión se interrumpe después de que WdLaunchRemoteGame se complete, aún puede llamar a WdTerminateRemoteGame una vez restaurada la conectividad.

​

Comportamiento de reintento

La API XBOX PC Remote Iteration no reintenta automáticamente las operaciones con error a nivel de la API. Si una operación falla debido a una interrupción de la red o a otro error transitorio, el autor de la llamada es responsable de reintentarla.

• Sin reintento automático. Si una operación de copia falla (por ejemplo, debido a la pérdida de conectividad de red), WdRemoteCopy devuelve un error. El autor de la llamada debe volver a invocar la función para reintentarlo.
• Sin tiempo de espera configurable. WdRemoteCopy no impone un tiempo de espera a la operación de copia. Continúa transfiriendo hasta que se completa, se produce un error o se cancela mediante WdCancelRemoteCopy. En condiciones de red degradadas, las transferencias pueden avanzar muy lentamente en lugar de fallar.
• El progreso se conserva en caso de error. Los archivos que se copiaron correctamente antes de un error permanecen en el destino. Cuando el autor de la llamada reintenta la copia, el comportamiento de copia diferencial garantiza que solo se transfieran los archivos incompletos o que falten; los archivos copiados anteriormente no se vuelven a transferir.
• Los errores de espacio en disco se notifican. Si el dispositivo de destino se queda sin espacio en disco durante una copia, la operación falla con un error en lugar de bloquearse.
• Resistencia a nivel de transporte. La capa de transporte subyacente controla la retransmisión de paquetes de bajo nivel de forma transparente. Los problemas de red menores (como la pérdida de un único paquete) no provocan un error en la operación. Sin embargo, una pérdida de conectividad sostenida acabará provocando un error.
• Patrón de reintento recomendado. Después de un error de WdRemoteCopy, simplemente vuelva a llamar a WdRemoteCopy con los mismos parámetros. El comportamiento de copia diferencial minimiza el trabajo redundante transfiriendo solo los archivos que faltan o están incompletos en el destino.

​

Cancelación

La API XBOX PC Remote Iteration proporciona un modelo de cancelación basado en identificadores para las operaciones de copia de larga duración. El autor de la llamada es responsable del ciclo de vida del identificador:

1. Cree un identificador llamando a WdCreateCancellationHandle.
2. Pase el identificador a WdRemoteCopy mediante el parámetro cancellationHandle.
3. Desde un subproceso independiente, llame a WdCancelRemoteCopy con el identificador para cancelar la copia en curso. WdCancelRemoteCopy no es de bloqueo. Una vez señalada la cancelación, WdRemoteCopy completa la cancelación y devuelve S_OK.
4. Cuando WdRemoteCopy devuelva un valor, cierre el identificador llamando a WdCloseCancellationHandle.

Si varios componentes necesitan hacer referencia al mismo identificador de cancelación, use WdDuplicateCancellationHandle para duplicarlo. Cada copia debe cerrarse de forma independiente.

​

Raíces comunes

Las raíces comunes son ubicaciones conocidas preconfiguradas en el dispositivo remoto en las que normalmente se copian los juegos o desde las que se inician. En lugar de especificar una ruta de acceso absoluta completa, los autores de las llamadas pueden hacer referencia a estas ubicaciones mediante un alias usando el campo commonRootAlias de WdCopyOptions o WdLaunchOptions. Si destinationPath es una ruta de acceso absoluta, el commonRootAlias se omite. Cuando destinationPath es una ruta de acceso relativa, se resuelve con respecto a la raíz común identificada por el alias. Si no se especifica ningún alias, se usa la ubicación de raíz común predeterminada.

​

Códigos de error

Para obtener una lista completa de los códigos de error específicos de la API, incluidas las descripciones, las causas raíz y las instrucciones de solución de problemas, consulte Códigos de error de la API XBOX PC Remote Iteration.

​

Control de versiones, mantenimiento y distribución

La API de Remote Iteration Tools (RIT) sigue el Versionado Semántico 2.0.0 (MAJOR.MINOR.PATCH) para ofrecer expectativas claras en cuanto a compatibilidad, actualizaciones y soporte a largo plazo. Todas las bibliotecas públicas de la API RIT se distribuyen mediante NuGet, lo que permite flujos de trabajo estándar de administración y actualización de dependencias.

​

Modelo de control de versiones

​

Versiones PATCH

Las actualizaciones PATCH proporcionan correcciones de errores y mejoras de confiabilidad. Estas actualizaciones no cambian los contratos de la API ni el comportamiento en tiempo de ejecución, y son actualizaciones de sustitución directa seguras. Actualizar a una versión PATCH más reciente no requiere cambios en el código.

​

Versiones MINOR

Las actualizaciones MINOR introducen nuevas API o hacen evolucionar la funcionalidad existente de manera compatible con versiones anteriores. Cuando se planea cambiar o quitar API en el futuro, se marcan claramente como en desuso, lo que da tiempo a los desarrolladores para migrar. Las actualizaciones de dependencias se revisan para garantizar la compatibilidad dentro de la misma versión MAJOR.

​

Versiones MAJOR

Las actualizaciones MAJOR representan cambios importantes intencionados. Estas versiones pueden requerir cambios de código o actualizaciones de dependencias y van acompañadas de instrucciones de migración claras. La actualización a una nueva versión MAJOR se trata como una decisión explícita y voluntaria alineada con los ciclos normales de validación y publicación.

​

Modelo de mantenimiento y soporte

Una vez que una versión MAJOR o MINOR de la API RIT se publica, entra en un período de mantenimiento activo con una ventana de soporte objetivo de aproximadamente 18 meses. Durante este tiempo:

• Se aprueban versiones PATCH para corregir errores y mejorar la confiabilidad de las versiones compatibles.
• A medida que se publican nuevas versiones, y las revisiones y los cambios menores mejoran las versiones existentes y corrigen errores, se pueden mantener simultáneamente varias versiones MAJOR y MINOR.
• Las versiones PATCH no amplían la vida útil de mantenimiento de una versión MAJOR o MINOR.
• Las nuevas características solo se introducen en versiones MINOR o MAJOR más recientes y no se transfieren a versiones anteriores.

Una vez que finaliza la ventana de mantenimiento, la versión se retira y se espera que los desarrolladores migren a una versión MAJOR o MINOR compatible más reciente.

​

Expectativas de actualización

Se recomienda a los desarrolladores mantenerse al día dentro de una versión MAJOR adoptando las actualizaciones PATCH y MINOR. Las actualizaciones de versión MAJOR deben planearse y validarse de forma explícita para garantizar la compatibilidad con los flujos de trabajo de producción.

​

Compatibilidad de versiones entre la API y wdEndpoint

La biblioteca cliente de la API RIT y el wdEndpoint que se ejecuta en el dispositivo remoto siempre deben mantenerse en versiones compatibles. Usar una versión más reciente de la API con un wdEndpoint más antiguo puede provocar errores E_SERVERTOOOLD o un comportamiento inesperado. Para garantizar un comportamiento correcto, la compatibilidad total con versiones anteriores y la compatibilidad con las características más recientes de la API, se recomienda actualizar wdEndpoint en todos los dispositivos remotos cada vez que se actualice la biblioteca cliente de la API. Consulte las notas de la versión del paquete NuGet para conocer los requisitos de versión mínima de wdEndpoint.

​

Requisitos

​

Documentación conceptual

• Notas de la versión de XBOX PC Remote Tools (marzo de 2026)

​

Consulte también

• WdRemoteCopy
• WdCancelRemoteCopy
• WdCreateCancellationHandle
• WdLaunchRemoteGame
• WdRegisterRemoteXboxGame