xCurl, una implementación de las API de libCurl compatible con el Microsoft Game Development Kit (GDK). xCurl simplifica el desarrollo de títulos al cumplir todos los requisitos de seguridad y procedimientos recomendados sin necesidad de ninguna lógica o gestión especial en el título. Sin embargo, no admite la comunicación WebSocket. Si necesita implementar comunicación WebSocket, use libHttpClient en su lugar.
xCurl se diferencia de libCurl en que xCurl está implementada sobre WinHttp y sigue automáticamente los requisitos y procedimientos recomendados del Microsoft Game Development Kit (GDK), incluida la administración del ciclo de vida de procesos (PLM). Aunque xCurl es compatible a nivel de API con libCurl, la capa de transporte dentro de xCurl usa exclusivamente WinHttp y no utiliza libCurl. Por lo tanto, no es necesario mantener xCurl sincronizada con la implementación de código abierto de libCurl, incluidas las correcciones de errores, los números de versión, etc. Los desarrolladores pueden usar xCurl para mantener la misma implementación HTTP de libCurl en todas las plataformas cambiando solo la inclusión de un encabezado y la vinculación de una biblioteca.
Varias API de libCurl no están implementadas en xCurl porque o bien no se usan habitualmente en escenarios de desarrollo de juegos, o bien no tienen una funcionalidad equivalente en WinHttp a la que se puedan asignar. Las diferencias se describen más adelante en este artículo.
xCurl depende del entorno de ejecución de juegos (Gaming Runtime) y no puede inicializarse hasta que se llame a XGameRuntimeInitialize.
Para comprender cómo funcionan los métodos de xCurl, consulte la documentación de la API de libCurl.
Las implementaciones de
xCurl y WinHttp funcionan tanto en PC con Windows como en consola XBOX sin necesidad de cambios de código.Soporte técnico para desarrolladores
xCurl funciona con WinHttp, no con libCurl, y forma parte del Microsoft Game Development Kit (GDK).
Las solicitudes de soporte técnico deben enviarse a través de las vías de soporte recomendadas para los títulos del Microsoft Game Development Kit (GDK), como ponerse en contacto con su representante de Microsoft o dirigirse al equipo de soporte técnico para desarrolladores a través de los foros de desarrolladores de XBOX.
Agregar xCurl al proyecto
Para usarxCurl en un juego del Microsoft Game Development Kit (GDK) en un PC con Windows 10 o en una consola XBOX, incluya los encabezados y las bibliotecas del SDK de extensión de xCurl en su proyecto.
- Asegúrese de instalar el Gaming Runtime Development Kit (GRDK) en su PC de desarrollo.
- Abra el archivo .vcxproj de su juego y, a continuación, agregue el elemento siguiente. Esto vincula la biblioteca de importación e incluye xCurl.dll con la salida de la compilación.
xCurltiene un encabezado diferente para diferenciarse delibCurl. En las ubicaciones donde se incluiría curl.h en su juego, sustituya el encabezado por xCurl.h, como se muestra a continuación.
Configuración
xCurl es equivalente a libCurl compilada con las siguientes marcas de compilación.
- HTTP_ONLY
- CURL_NO_OLDIES
- CURL_DISABLE_PROXY
- CURL_DISABLE_COOKIES
- CURL_DISABLE_DOH
- CURL_DISABLE_PROGRESS_METER
- CURL_DISABLE_MIME
- USE_SCHANNEL
Inicialización de la red
xCurl gestiona la inicialización de la red automáticamente. Puede configurar y realizar solicitudes en cualquier momento del ciclo de vida de su título. Las solicitudes iniciadas antes de que la red esté inicializada se retrasan y se ponen en cola hasta que la red se inicializa. xCurl garantiza que sus solicitudes se realicen en la primera oportunidad posible sin ninguna gestión adicional por parte de su título.
Suspensión/reanudación del título
xCurl gestiona la suspensión y la reanudación automáticamente. Al suspender, todas las solicitudes pendientes se cancelan inmediatamente y producen un error con CURLE_NO_CONNECTION_AVAILABLE. Además, consultar curl_easy_getinfo para CURLINFO_OS_ERRNO en estas solicitudes devuelve HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME) al igual que cualquier otra API de GRTS, por si desea gestionar estos errores de forma diferente a los errores generales de desconexión de red.
Todos los identificadores de xCurl siguen siendo válidos durante todo el ciclo de vida del título, incluso a través de los límites de suspensión/reanudación. No es necesario limpiar ni inicializar ningún identificador de xCurl al suspender/reanudar. Las nuevas solicitudes iniciadas después de la suspensión se retrasan hasta la reanudación y la posterior inicialización de la red. Este retraso garantiza que se inicien lo antes posible sin requerir ninguna gestión adicional por parte de su título.
Cuando su título use la interfaz multi de
xCurl, su título debe seguir llamando a curl_multi_perform junto con, opcionalmente, curl_multi_poll o curl_multi_wait durante la suspensión mientras haya solicitudes pendientes. xCurl bloquea la suspensión hasta que se completen todas las solicitudes en curso, y no llamar a curl_multi_perform podría hacer que su título agotara el tiempo de espera durante la suspensión. Recomendamos seguir llamando a curl_multi_perform durante todo el ciclo de vida, independientemente del estado de suspensión/reanudación. xCurl gestiona internamente todas las complejidades del estado suspendido.Funcionalidad de seguridad
Todas las solicitudes HTTPS a través dexCurl siguen los procedimientos recomendados de seguridad en las comunicaciones (artículo con NDA). xCurl aplica automáticamente cualquier anclaje de certificados especial especificado a través del “Single Sign-on Portal” de su título. No se admite el uso de CURLOPT_SSL_VERIFYPEER para deshabilitar la validación de certificados.
En los kits de desarrollo puede especificar el esquema HTTP sin cifrar, http://, para tráfico de depuración y con fines de prueba. Para todas las solicitudes RETAIL, debe especificar el esquema HTTPS, https://, para proporcionar el nivel de protección recomendado. Las solicitudes de xCurl que no especifican explícitamente un esquema infieren el esquema HTTPS.
xCurl no realiza la inserción automática de tokens. Para recuperar tokens de XBOX Live, su título debe llamar a las API de GRTS XUserGetTokenAndSignatureAsync o XUserGetTokenAndSignatureUtf16Async para recuperar los encabezados de autorización y firma y, a continuación, usar las opciones CURLOPT_HEADER, CURLOPT_HTTPHEADER o CURLOPT_HEADERFUNCTION en una llamada a curl_easy_setopt para establecer los encabezados antes de realizar la solicitud.Consideraciones sobre memoria y simultaneidad
xCurl comparte las mismas limitaciones de solicitudes simultáneas que se aplican a WinHttp. Los títulos deben limitar las solicitudes simultáneas a ocho o menos para garantizar que todas las llamadas funcionen correctamente. Este límite de simultaneidad se aplica a las solicitudes simultáneas que se emiten desde cualquiera de xCurl, WinHttp y las API de servicios de XBOX.
xCurl usa un búfer alternante (flip buffer) para recibir datos. Este patrón le permite proporcionar más rendimiento al llenar un segundo búfer mientras el título lee del primero. Sin embargo, si la devolución de llamada de lectura tarda demasiado o si no se llama a curl_multi_perform con la suficiente frecuencia en modo multi, la memoria del kernel de WinSock podría acumularse. Para obtener más información sobre la memoria del kernel de WinSock, consulte consideraciones sobre la memoria de sockets.
Control de las asignaciones de xCurl
De forma predeterminada,xCurl usa el montón de Windows y sus asignaciones pueden rastrearse mediante XMemSetWin32HeapTrackingHooks. Como alternativa, se pueden proporcionar funciones de memoria en el momento de la inicialización, como en libCurl.
Además de curl_global_init_mem, xCurl proporciona la función opcional xCurl_global_init_mem. Las devoluciones de llamada que se proporcionan a esta versión de init son similares a otras devoluciones de llamada de memoria del Microsoft Game Development Kit (GDK) y proporcionan más información que las devoluciones de llamada estándar de libCurl sobre los datos que se están asignando.
Opciones admitidas
Las siguientes opciones se admiten con identificadoreseasy en xCurl.
- CURLOPT_VERBOSE
- CURLOPT_HEADER
- CURLOPT_NOBODY
- CURLOPT_FAILONERROR
- CURLOPT_UPLOAD
- CURLOPT_PUT
- CURLOPT_ACCEPT_ENCODING
- CURLOPT_TRANSFER_ENCODING
- CURLOPT_FOLLOWLOCATION
- CURLOPT_MAXREDIRS
- CURLOPT_POST
- CURLOPT_COPYPOSTFIELDS
- CURLOPT_POSTFIELDS
- CURLOPT_POSTFIELDSIZE
- CURLOPT_POSTFIELDSIZE_LARGE
- CURLOPT_POSTREDIR
- CURLOPT_REFERER
- CURLOPT_USERAGENT
- CURLOPT_HTTPHEADER
- CURLOPT_HTTPGET
- CURLOPT_HTTP_VERSION
- CURLOPT_CUSTOMREQUEST
- CURLOPT_HEADERDATA
- CURLOPT_ERRORBUFFER
- CURLOPT_WRITEDATA
- CURLOPT_READDATA
- CURLOPT_INFILESIZE
- CURLOPT_INFILESIZE_LARGE
- CURLOPT_CURLU
- CURLOPT_URL
- CURLOPT_PORT
- CURLOPT_TIMEOUT
- CURLOPT_TIMEOUT_MS
- CURLOPT_CONNECTTIMEOUT
- CURLOPT_CONNECTTIMEOUT_MS
- CURLOPT_DEBUGFUNCTION
- CURLOPT_DEBUGDATA
- CURLOPT_HEADERFUNCTION
- CURLOPT_WRITEFUNCTION
- CURLOPT_READFUNCTION
- CURLOPT_SSL_VERIFYPEER
- CURLOPT_SSL_VERIFYHOST
- CURLOPT_SSLCERT
- CURLOPT_BUFFERSIZE
- CURLOPT_UPLOAD_BUFFERSIZE
- CURLOPT_PRIVATE
- CURLOPT_IGNORE_CONTENT_LENGTH
- CURLOPT_HTTP_TRANSFER_DECODING
- CURLOPT_HTTP_CONTENT_DECODING
Funcionalidad no admitida
Sockets y fd_set
xCurl no expone el socket subyacente que se usa para el transporte. Por lo tanto, xCurl no implementa ninguna opción ni API que se usaría para operaciones de socket. Este límite también elimina la posibilidad de usar fd_sets para esperar la llegada de datos mediante select y poll. Para esperar la llegada de trabajo, use curl_multi_wait y curl_multi_poll.
Las siguientes API no están presentes en xCurl
curl_easy_sendcurl_easy_recvcurl_multi_socketcurl_multi_socket_actioncurl_multi_socket_allcurl_multi_assigncurl_multi_fdset
CURLE_NOT_BUILT_IN.
- CURLOPT_LOCALPORT
- CURLOPT_CONNECT_ONLY
- CURLOPT_SOCKOPTFUNCTION
- CURLOPT_SOCKOPTDATA
- CURLOPT_OPENSOCKETFUNCTION
- CURLOPT_OPENSOCKETDATA
- CURLOPT_CLOSESOCKETFUNCTION
- CURLOPT_CLOSESOCKETDATA
- CURLOPT_XOAUTH2_BEARER
- CURLOPT_PROGRESSFUNCTION
- CURLOPT_PROGRESSDATA
- CURLOPT_XFERINFOFUNCTION
- CURLOPT_XFERINFODATA
- CURLOPT_NOPROGRESS
- CURLINFO_LASTSOCKET
- CURLINFO_ACTIVESOCKET
- CURLMOPT_SOCKETFUNCTION
- CURLMOPT_SOCKETDATA
- CURLMOPT_PIPELINING
- CURLMOPT_PUSHFUNCTION
CURL Share
La interfazShare de CURL no está implementada.