다음을 통해 공유

xCurl 개요

  • 아티클

이 주제에서는 libCurl API의 Microsoft GDK(게임 개발 키트) 호환 구현인 xCurl 라이브러리에 대해 설명합니다. Microsoft GDK(Game Development Kit) 타이틀용 HTTP API로 xCurl을(를) 권장합니다. xCurl은(는) 특별한 타이틀 논리나 처리 없이 모든 보안 요구 사항과 모범 사례를 준수하여 타이틀 개발을 단순화합니다. 그러나 WebSocket 통신을 지원하지 않습니다. WebSocket 통신을 구현해야 하는 경우 libHttpClient를 대신 사용합니다.

XR-134: 웹 프로토콜을 사용한 데이터 전송을 사용하려면 Xbox 콘솔용으로 개발된 타이틀에서 사용자 지정 HTTP 스택 구현을 사용하지 않아야 합니다. 대신 운영 체제에서 제공되고 운영 체제를 통해 유지 관리 가능한 스택을 사용합니다. 이를 통해 Xbox 게이머는 시간이 지남에 따라 안정성과 보안 향상을 제공할 수 있습니다.

xCurl은(는) xCurl이(가) WinHttp 위에 구현되고 Microsoft GDK(게임 개발 키트) 요구사항 및 PLM(프로세스 수명 관리)를 비롯한 모범 사례를 자동으로 따른다는 점에서 libCurl과(와) 다릅니다. xCurl은(는) libCurl와(과)PI 호환이 가능하지만, xCurl 내의 전송 계층은 WinHttp만 사용하고 libCurl을(를) 사용하지 않습니다. 따라서 xCurl은(는) 버그 수정, 버전 번호 등을 포함하여 libCurl의 오픈 소스 구현과 동기화할 필요가 없습니다. 개발자는 xCurl을(를) 사용하여 모든 플랫폼에서 동일한 libCurl HTTP 구현을 유지하면서 헤더 포함 및 라이브러리 링크를 하나만 변경하는 것이 좋습니다.

여러 libCurl API는 게임 개발 시나리오에서 일반적으로 사용되지 않거나 WinHttp 내에서 매핑할 수 있는 동일한 기능이 없으므로 xCurl에서 구현되지 않습니다. 차이점은 이 항목의 뒷부분에 설명되어 있습니다.

xCurl은(는) Gaming Runtime에 의존하며 XGameRuntimeInitialize이(가) 호출될 때까지 초기화할 수 없습니다.

xCurl 메서드의 작동 방식을 이해하려면 libCurl API 설명서를 참조하세요.

참고 항목

xCurl 및 WinHttp은(는) Xbox 콘솔에서 HTTP에 대한 유일한 XR 호환 옵션입니다. xCurl 및 WinHttp 구현은 코드 변경 없이 Windows PC와 Xbox 콘솔 모두에서 작동합니다. 그러나 Windows PC에서는 Microsoft 게임 개발 키트(GDK) 타이틀과 함께 libCurl 또는 다른 HTTP 스택을 직접 사용할 수 있으며, XR-134는 Windows PC에는 적용되지 않습니다.

개발자 지원

xCurl은(는) libCurl이(가) 아닌 WinHttp로 구동되며 Microsoft 게임 개발 키트(GDK)의 일부입니다.

지원 요청은 Microsoft GDK(게임 개발 키트) 타이틀에 대한 권장 지원 경로를 통해 전송되어야 합니다. 여기에는 Microsoft 담당자에게 문의하거나 Xbox 개발자 포럼을 통해 개발자 지원 팀에 문의하는 것이 포함됩니다.

프로젝트에 xCurl 추가

Windows 10 PC 또는 Xbox 콘솔의 Microsoft GDK(게임 개발 키트) 게임에서 xCurl을 사용하려면 프로젝트에 xCurl 확장 SDK 헤더 및 라이브러리를 포함합니다.

  1. 개발 PC에 GRDK(게임 런타임 개발 키트)가 설치되어 있는지 확인합니다.

  2. 게임에 사용할 .vcxproj 파일을 열고 다음 요소를 추가하세요. 그러면 가져오기 라이브러리가 연결되고 빌드 출력과 함께 XCurl.dll이 포함됩니다.

    <GDKExtLibNames>Xbox.xCurl.API</GDKExtLibNames>

  3. xCurl에는 libCurl과(와) 자신을 구분하기 위해 다른 헤더가 있습니다. 게임의 curl.h가 포함되는 곳에서, 다음과 같이 헤더를 xCurl.h로 교체해야 합니다.

    #include <xCurl.h>

구성

xCurl은(는) 다음 빌드 플래그로 컴파일된 libCurl와 동일합니다.

  • HTTP_ONLY
  • CURL_NO_OLDIES
  • CURL_DISABLE_PROXY
  • CURL_DISABLE_COOKIES
  • CURL_DISABLE_DOH
  • CURL_DISABLE_PROGRESS_METER
  • CURL_DISABLE_MIME
  • USE_SCHANNEL

네트워크 초기화

xCurl은(는) 네트워크 초기화를 자동으로 처리합니다. 타이틀 라이프 사이클의 어느 시점에서든 요청을 설정하고 수행할 수 있습니다. 네트워크가 초기화되기 전에 시작된 모든 요청은 네트워크가 초기화될 때까지 지연되고 대기됩니다. 이러한 방식으로 XCurl은 귀하의 소유권에 필요한 추가 처리 없이 가능한 한 빨리 귀하의 요청이 이루어지도록 보장합니다.

타이틀 일시 중단/재개

xCurl은(는) 자동으로 일시 중단 및 다시 시작을 처리합니다. 일시 중단시 모든 미해결 요청이 즉시 취소되고 CURLE_NO_CONNECTION_AVAILABLE(으)로 실패합니다. 또한 이러한 요청에서 CURLINFO_OS_ERRNO에 대해 curl_easy_getinfo을(를) 쿼리하면 일반 네트워크 연결 해제 실패와 다르게 이러한 실패를 처리하려는 경우 다른 GRTS API와 마찬가지로 HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME)이(가) 반환됩니다.

모든 xCurl 핸들은 일시 중단/재개 경계를 포함하여 타이틀 수명 주기 동안 유효합니다. 일시 중단/재개시 xCurl 핸들을 정리하거나 초기화할 필요가 없습니다. 일시 중단 후 시작된 모든 새 요청은 재개 및 후속 네트워크 초기화까지 지연되어 타이틀에 대한 추가 처리 없이 가능한 한 빨리 시작됩니다.

참고 항목

xCurl에 다중 인터페이스를 사용할 때 타이틀은 보류 중인 요청이 있는 동안 일시 중단시 curl_multi_poll 또는 curl_multi_wait와(과) 함께 curl_multi_perform을(를) 계속 호출해야 합니다. xCurl은(는) 진행 중인 모든 요청이 완료될 때까지 정지를 차단하며 curl_multi_perform 호출에 실패하면 정지 중에 타이틀이 시간 초과될 수 있습니다. 일시 중단/재개 상태에 관계없이 전체 수명 주기 동안 curl_multi_perform을 계속 호출하는 것이 좋습니다. xCurl은(는) 정지 상태의 모든 복잡성을 내부적으로 처리합니다.

보안 기능

xCurl을(를) 통과하는 모든 HTTPS 요청은 통신 보안 모범 사례(NDA 항목)를 따릅니다. xCurl은(는) 타이틀의 "SSO(Single Sign-On) 포털"을 통해 지정된 특수 인증서 고정을 자동으로 시행합니다. 를 사용하여 CURLOPT_SSL_VERIFYPEER 인증서 유효성 검사를 사용하지 않도록 설정하는 것은 지원되지 않습니다.

개발 키트에서 디버그 트래픽 및 테스트 목적으로 암호화되지 않은 HTTP 체계 http://을(를) 지정할 수 있습니다. 모든 RETAIL 요청에 대해 권장되는 보호 수준을 제공하려면 HTTPS 스키마 https://을(를) 지정해야 합니다. 체계를 명시적으로 지정하지 않은 xCurl 요청은 HTTPS 체계를 유추합니다.

참고 항목

xCurl은(는) 자동 토큰 삽입을 수행하지 않습니다. Xbox Live 토큰을 검색하려면 타이틀이 XUserGetTokenAndSignatureAsync 또는 XUserGetTokenAndSignatureUtf16Async GRTS API를 호출하여 인증 및 서명 헤더를 검색한 다음 curl_easy_setopt에 대한 호출에서 CURLOPT_HEADER, CURLOPT_HTTPHEADER 또는 CURLOPT_HEADERFUNCTION 옵션을 사용하여 요청하기 전에 헤더를 설정합니다.

메모리 및 동시성 고려 사항

xCurl은(는) WinHttp에 적용되는 동일한 동시 요청 제한을 공유합니다. 모든 호출이 제대로 작동하도록 타이틀은 동시 요청을 여덟 개 이하로 제한해야 합니다. 이 동시성 제한은 xCurl, WinHttp 및 Xbox 서비스 API에서 발행된 동시 요청에 적용됩니다.

xCurl은(는) 플립 버퍼를 사용하여 데이터를 수신합니다. 이를 통해 읽기 콜백에 전체 버퍼를 제공하면서 두 번째 버퍼 채우기를 시작한 다음 첫 번째 버퍼가 채워지는 동안 두 번째 버퍼를 읽기 콜백에 제공하도록 전환할 수 있습니다. 그러나 읽기 콜백이 너무 오래 걸리거나 다중 모드에서 curl_multi_perform이(가) 충분히 자주 호출되지 않으면 WinSock 커널 메모리가 축적될 수 있습니다. WinSock 커널 메모리에 대한 자세한 내용은 소켓 메모리 고려 사항을 참조하세요.

xCurl 할당 제어

기본적으로 xCurl은(는) Windows 힙을 사용하며 XMemSetWin32HeapTrackingHooks을(를) 통해 할당을 추적할 수 있습니다. 또는 libCurl과(와) 같이 초기화할 때 메모리 기능을 제공할 수 있습니다.

xCurl은(는) curl_global_init_mem와(과) 함께 선택적인 xCurl_global_init_mem을(를) 제공합니다. 이 init 버전에 제공되는 콜백은 다른 Microsoft GDK(게임 개발 키트) 메모리 콜백과 유사하며 할당되는 데이터에 대한 표준 libCurl 콜백보다 더 많은 정보를 제공합니다.

지원되는 옵션

다음 옵션은 xCurl의 easy 핸들에서 지원됩니다.

  • 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

지원되지 않는 기능

소켓 및 fd_set

xCurl은(는) 전송에 사용되는 기본 소켓을 노출하지 않습니다. 따라서 xCurl은(는) 소켓 작업에 사용되는 옵션 및 API를 구현하지 않습니다. 또한 select 및 poll을 통해 데이터가 도착할 때까지 기다리는 fd_sets 기능도 제거됩니다. 작업이 도착할 때까지 기다리려면 curl_multi_wait 및 curl_multi_poll을(를) 사용하세요.

다음 API는 xCurl에 없습니다.

  • curl_easy_send
  • curl_easy_recv
  • curl_multi_socket
  • curl_multi_socket_action
  • curl_multi_socket_all
  • curl_multi_assign
  • curl_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 공유

CURL Share 인터페이스가 구현되지 않습니다.

전송 일시중지 재개

이 기능은 현재 지원되지 않습니다. 콜백에서 CURL_WRITEFUNC_PAUSE 또는 CURL_READFUNC_PAUSE를 반환하면 작업이 중단되고 다시 시작할 수 없습니다.

참고 항목

libCurl API

파트너 센터에서 웹 서비스 설정(NDA 항목)

Xbox One 본체에서의 Fiddler

통신 보안 모범 사례 개요(NDA 항목)