Inicialización de la red
Usa este artículo para comprender cómo recuperar información de conectividad e inicialización de la red en títulos de Microsoft Game Development Kit (GDK). A menudo se inician antes de que los componentes principales del sistema operativo y los servicios de red estén en ejecución. Como resultado, intentar llamar a la mayoría de las API de redes y seguridad, incluidasWinSock, WinHTTP, BCrypt, WinCrypt, schannel e IPHLPAPI, demasiado pronto después del inicio del título provoca un comportamiento indeterminado. Este comportamiento puede incluir errores inesperados, valores devueltos sin inicializar, pérdida arbitraria de paquetes y posibles daños en la memoria y bloqueos.
Para evitar este comportamiento indeterminado, los títulos de Microsoft Game Development Kit (GDK) deben usar las funciones XNetworkingGetConnectivityHint y XNetworkingRegisterConnectivityHintChanged. En particular, el campo XNetworkingConnectivityHint::networkInitialized indica si la red está inicializada. Los títulos deben esperar a que el campo networkInitialized sea true antes de llamar a las API de redes y seguridad.
Muchas bibliotecas de middleware también usan internamente las API de redes y seguridad; incluso el middleware que no es de redes puede usar la pila de red para telemetría o depuración. Consulta con el proveedor del middleware qué hacer en cada caso. Si el propio middleware no espera a la inicialización de la red, es posible que tengas que retrasar la carga del middleware hasta que la red se inicialice. Varias bibliotecas del Microsoft Game Development Kit (GDK), como XSAPI y Azure PlayFab Party, requieren que esperes a que la red esté inicializada antes de usarlas.
Secuenciación de la pila HTTP
xCurl y libHttpClient son las únicas bibliotecas HTTP cubiertas en este conjunto de documentación que administran la inicialización de la red automáticamente. Si tu título usa cualquier otra pila HTTP, haz explícita la secuencia de arranque. Un patrón seguro es:
- Consulta la sugerencia de conectividad actual o regístrate para los cambios de conectividad.
- Espera hasta que
XNetworkingConnectivityHint::networkInitializedseatrue. - Inicializa
WinSocky cualquier otra dependencia de red. - Accede al estado de los certificados y configura la confianza.
- Crea la pila HTTP y comienza a emitir solicitudes.
WinSock, el estado de los certificados o el estado HTTP demasiado pronto puede producir errores difíciles de diagnosticar, porque el error visible suele aparecer más tarde que la causa raíz.
El ejemplo siguiente muestra los primeros pasos de una secuencia de arranque de una pila HTTP propiedad del título. Consulta XNetworkingConnectivityHint directamente antes de poner en marcha WinSock.
Suspensión y reanudación
Además, los ciclos de suspensión y reanudación del título restablecen el camponetworkInitialized a false. En la suspensión, los títulos deben limpiar todos los identificadores de todos los componentes de red y seguridad y cesar todas las operaciones de red. Consulta la página de información general de cada API de redes para obtener más información sobre los requisitos de esa API en la suspensión. En la reanudación, los títulos deben esperar de nuevo a que el campo networkInitialized sea true antes de intentar restablecer las conexiones y usar cualquiera de las API de redes o seguridad. Recomendamos que la ruta de inicialización de la red en la reanudación sea la misma que la ruta del inicio inicial del título: en la reanudación o en el inicio del título, espera a que la red esté inicializada antes de iniciar tu código de red. Las bibliotecas de middleware que no son conscientes de la suspensión y reanudación, como GameChat2 y Azure PlayFab Party, deben limpiarse en la suspensión y reinicializarse en la reanudación después de esperar a que la red esté inicializada.
Da por hecho que toda pila HTTP distinta de xCurl requiere un control explícito del ciclo de vida. En la suspensión o el apagado, deja de poner en cola nuevas solicitudes y cancela o vacía el trabajo en curso. Destruye los identificadores de solicitud, las sesiones y los sockets que no deban sobrevivir a la suspensión.
En la reanudación, trata la puesta en marcha de la red como una ruta de inicialización nueva. Espera de nuevo a networkInitialized antes de volver a crear el estado HTTP o volver a registrar los agentes de escucha. Los diseños basados en trabajo cancelable y sin bloqueo son más fáciles de deshacer limpiamente durante la suspensión que las llamadas de bloqueo de larga duración.
Prueba de la inicialización de la red
La inicialización de la red normalmente tarda un par de segundos tanto en la reanudación como en el inicio del título, y varía según el tipo de consola y el entorno de red del usuario. Durante el desarrollo, la inicialización de la red es casi instantánea. Esto puede ocultar problemas de distintas partes de tu título que no esperan correctamente a que la red esté inicializada. Para probar escenarios de inicialización de la red, usaxbconfig NetworkInitDelayInSeconds=30 para agregar un retraso arbitrario al proceso de inicialización de la red. Al usar esta configuración, asegúrate de reiniciar completamente tu título entre cada prueba mediante xbapp terminate /full. Vuelve a establecer NetworkInitDelayInSeconds en 0 cuando termines las pruebas.
Para las pilas HTTP que crean su propio estado de red, incluye al menos estos escenarios en tu cobertura de pruebas:
- Arranque en frío
- Suspensión mientras hay solicitudes activas
- Reanudación después de una suspensión limpia
- Quick Resume o flujos de restauración equivalentes
- Desconexiones de red en torno a los límites de suspensión y reanudación
Ejemplos de código de inicialización de la red
El ejemplo de código siguiente muestra cómo sondear de forma segura y en tiempo real si la red está inicializada.Información de la red
La información de la red en los títulos de Microsoft Game Development Kit (GDK) puede recuperarse con la API XNetworkingGetConnectivityHint. La API XNetworkingGetConnectivityHint devuelve información de todo el dispositivo sobre los niveles de conectividad de red, los límites de datos, los tipos de conectividad cableada o inalámbrica y si la red está inicializada. Es una API segura y en tiempo real que devuelve inmediatamente la información actual. Puedes escuchar los cambios con las funciones XNetworkingRegisterConnectivityHintChanged y XNetworkingUnregisterConnectivityHintChanged. El ejemplo de código siguiente muestra cómo usar la función XNetworkingGetConnectivityHint para consultar información sobre el estado actual de la red.Procedimientos recomendados de conectividad de red
Los campos de la estructura XNetworkingConnectivityHint devuelta, distintos del campoXNetworkingConnectivityHint::networkInitialized, son sugerencias. Son la mejor estimación posible del dispositivo sobre el estado actual de la red. Se basa en heurísticas del tráfico de red observado en el dispositivo.
El estado de XNetworkingConnectivityLevelHint representa una aproximación general del nivel de red para simplificar la lógica de conectividad de los títulos. Los títulos pueden esperar que XNetworkingConnectivityLevelHint::None refleje la desconexión del medio de red y la falta general de conectividad en estado estable, donde el entorno de red no ha cambiado durante varios minutos. Los demás estados no representan si hay conectividad con los puntos de conexión específicos de tu título.
Como resultado, recomendamos que, después de esperar a la inicialización de la red, uses WinSock o WinHTTP para intentar establecer una conexión con tu punto de conexión, independientemente del estado del campo XNetworkingConnectivityHint::connectivityLevelHint. Si esas API producen errores más adelante, recomendamos que uses entonces la API XNetworkingGetConnectivityHint para fines adicionales de interfaz de usuario y de informes de diagnóstico. A continuación, debes esperar a un cambio en el nivel de conectividad de red antes de volver a intentarlo.
Recuperación de información de red avanzada
La mayoría de los títulos de Microsoft Game Development Kit (GDK) deben usar la API XNetworkingGetConnectivityHint con las API deWinSock para recuperar el estado de la red y la información de red básica, como las direcciones IP. Si necesitas más información, la API IP Helper de bajo nivel está disponible en el GDK.
En general, trabaja con la API IP Helper en el Microsoft Game Development Kit (GDK) de la misma manera en que trabajarías con esta API en un programa Win32.
-
En tus archivos de código fuente, agrega
#include <iphlpapi.h>después de#include <winsock2.h>. -
Vincula con
XGamePlatform.liben lugar de vincular directamente conWs2_32.libyIphlpapi.lib.
WINAPI\_PARTITION\_GAMES funcionan en los títulos de Microsoft Game Development Kit (GDK).
En las consolas XBOX, cierta información no es precisa al usar la API IP Helper debido a la abstracción de la plataforma subyacente. Esto incluye, entre otros, los casos siguientes:
- La dirección MAC siempre será
AA-AA-AA-AA-AA-AA. - Todas las interfaces siempre notifican una interfaz cableada, independientemente del tipo de conexión de red subyacente. El tipo de interfaz real solo puede recuperarse mediante XNetworkingGetConnectivityHint.
