xCurl 라이브러리를 설명합니다. xCurl은 특별한 타이틀 로직이나 처리를 요구하지 않고도 모든 보안 요구 사항과 모범 사례를 준수하여 타이틀 개발을 간소화합니다. 그러나 WebSocket 통신은 지원하지 않습니다. WebSocket 통신을 구현해야 하는 경우 대신 libHttpClient를 사용하세요.
xCurl은 WinHttp 위에 구현되며 프로세스 수명 관리(PLM)를 포함한 Microsoft Game Development Kit (GDK) 요구 사항 및 모범 사례를 자동으로 따른다는 점에서 libCurl과 다릅니다. xCurl은 libCurl과 API 호환이지만 xCurl 내의 전송 계층은 오직 WinHttp를 사용하며 libCurl을 활용하지 않습니다. 따라서 xCurl은 버그 수정, 버전 번호 등을 포함하여 libCurl의 오픈 소스 구현과 동기화되어야 할 필요가 없습니다. 개발자는 하나의 헤더 include와 라이브러리 링크만 변경하면서 모든 플랫폼에서 동일한 libCurl HTTP 구현을 유지하기 위해 xCurl을 사용할 수 있습니다.
여러 libCurl API는 게임 개발 시나리오에서 일반적으로 사용되지 않거나 매핑할 수 있는 동등한 기능이 WinHttp 내에 없기 때문에 xCurl에 구현되지 않았습니다. 이러한 차이점은 이 문서의 뒷부분에서 설명됩니다.
xCurl은 Gaming Runtime에 의존하며 XGameRuntimeInitialize가 호출될 때까지 초기화할 수 없습니다.
xCurl 메서드가 작동하는 방식을 이해하려면 libCurl API 문서를 참조하세요.
xCurl과 WinHttp 구현은 Windows PC와 XBOX 콘솔 모두에서 코드 변경 없이 작동합니다.개발자 지원
xCurl은 libCurl이 아닌 WinHttp로 구동되며 Microsoft Game Development Kit (GDK)의 일부입니다.
지원 요청은 Microsoft 담당자에게 연락하거나 XBOX Developer Forums를 통해 개발자 지원 팀에 문의하는 등, Microsoft Game Development Kit (GDK) 타이틀에 권장되는 지원 경로를 통해 전송되어야 합니다.
프로젝트에 xCurl 추가
Windows 10 PC 또는 XBOX 콘솔의 Microsoft Game Development Kit (GDK) 게임에서xCurl을 사용하려면 프로젝트에 xCurl 확장 SDK 헤더 및 라이브러리를 포함시킵니다.
- 개발 PC에 Gaming Runtime Development Kit (GRDK)이 설치되어 있는지 확인합니다.
- 게임의 .vcxproj 파일을 열고 다음 요소를 추가합니다. 이는 import 라이브러리를 링크하고 빌드 출력에 xCurl.dll을 포함시킵니다.
xCurl은libCurl과 자신을 구별하기 위한 다른 헤더를 가지고 있습니다. 게임에서 curl.h가 포함될 위치에서 다음과 같이 헤더를 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용 multi 인터페이스를 사용하는 경우, 대기 중인 요청이 있는 동안 일시 중지 시 curl_multi_perform과 선택적으로 curl_multi_poll 또는 curl_multi_wait를 계속 호출해야 합니다. xCurl은 진행 중인 모든 요청이 완료될 때까지 일시 중지를 차단하며, curl_multi_perform 호출에 실패하면 일시 중지 중에 타이틀이 시간 초과될 수 있습니다. 일시 중지/재개 상태와 관계없이 전체 수명 주기 동안 curl_multi_perform을 계속 호출하는 것이 좋습니다. xCurl은 일시 중지 상태의 모든 복잡성을 내부적으로 처리합니다.보안 기능
xCurl을 통한 모든 HTTPS 요청은 통신 보안 모범 사례(NDA 문서)를 따릅니다. xCurl은 타이틀의 “Single Sign-on Portal”을 통해 지정된 특수 인증서 고정을 자동으로 강제합니다. 인증서 검증을 비활성화하기 위해 CURLOPT_SSL_VERIFYPEER를 사용하는 것은 지원되지 않습니다.
개발 킷에서는 디버그 트래픽 및 테스트 목적으로 암호화되지 않은 HTTP 체계 http://를 지정할 수 있습니다. 모든 RETAIL 요청의 경우 권장되는 보호 수준을 제공하기 위해 HTTPS 체계 https://를 지정해야 합니다. 체계를 명시적으로 지정하지 않은 xCurl 요청은 HTTPS 체계로 유추됩니다.
xCurl은 자동 토큰 삽입을 수행하지 않습니다. XBOX Live 토큰을 검색하려면 타이틀이 XUserGetTokenAndSignatureAsync 또는 XUserGetTokenAndSignatureUtf16Async GRTS API를 호출하여 authorization 및 signature 헤더를 검색한 다음, 요청 전에 헤더를 설정하기 위해 curl_easy_setopt 호출에서 CURLOPT_HEADER, CURLOPT_HTTPHEADER 또는 CURLOPT_HEADERFUNCTION 옵션을 사용해야 합니다.메모리 및 동시성 고려 사항
xCurl은 WinHttp에 적용되는 것과 동일한 동시 요청 제한을 공유합니다. 모든 호출이 올바르게 작동하도록 타이틀은 동시 요청을 8개 이하로 제한해야 합니다. 이 동시성 제한은 xCurl, WinHttp, XBOX 서비스 API 중 어느 곳에서든 발행된 동시 요청에 적용됩니다.
xCurl은 데이터를 수신하기 위해 flip buffer를 사용합니다. 이 패턴은 타이틀이 첫 번째 버퍼에서 읽는 동안 두 번째 버퍼를 채워 더 많은 처리량을 제공할 수 있게 합니다. 그러나 읽기 콜백이 너무 오래 걸리거나 multi 모드에서 curl_multi_perform이 충분히 자주 호출되지 않으면 WinSock 커널 메모리가 축적될 수 있습니다. WinSock 커널 메모리에 대한 자세한 내용은 소켓 메모리 고려 사항을 참조하세요.
xCurl 할당 제어
기본적으로xCurl은 Windows 힙을 사용하며 할당은 XMemSetWin32HeapTrackingHooks를 통해 추적할 수 있습니다. 대안적으로, libCurl과 같이 초기화 시점에 메모리 함수를 제공할 수 있습니다.
curl_global_init_mem에 더해, xCurl은 선택적인 xCurl_global_init_mem를 제공합니다. 이 init 버전에 제공되는 콜백은 다른 Microsoft Game Development Kit (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_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
CURL의 Share 인터페이스는 구현되지 않았습니다.