xCurl ライブラリについて説明します。xCurl は、タイトルに特別なロジックや処理を求めることなく、すべてのセキュリティ要件およびベスト プラクティスに従うことで、タイトル開発を簡素化します。ただし、WebSocket 通信はサポートしていません。WebSocket 通信を実装する必要がある場合は、代わりに libHttpClient を使用してください。
xCurl は、WinHttp 上に実装されており、Process Lifetime Management (PLM) を含む Microsoft Game Development Kit (GDK) の要件とベスト プラクティスに自動的に従う点で libCurl と異なります。xCurl は libCurl と API 互換ですが、xCurl 内のトランスポート層は WinHttp のみを使用し、libCurl は利用しません。そのため、xCurl はバグ修正やバージョン番号などを含め、libCurl のオープンソース実装と同期を保つ必要はありません。開発者は xCurl を使用することで、ヘッダー インクルードとライブラリ リンクを 1 か所変更するだけで、すべてのプラットフォームで同じ libCurl の HTTP 実装を維持できます。
いくつかの libCurl API は xCurl に実装されていません。理由は、ゲーム開発シナリオで一般的に使用されない、または WinHttp 内にマッピング可能な同等機能が存在しないためです。差異はこの記事の後半で説明します。
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 ファイルを開き、次の要素を追加します。これによりインポート ライブラリがリンクされ、ビルド出力に 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 で失敗します。また、他の GRTS API と同様に、これらのリクエストに対して curl_easy_getinfo で CURLINFO_OS_ERRNO を問い合わせると HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME) が返されるため、一般的なネットワーク切断による失敗とは別に扱うこともできます。
すべての xCurl ハンドルは、サスペンド/レジュームの境界を含むタイトル ライフサイクル全体を通して有効なままです。サスペンド/レジューム時に xCurl ハンドルをクリーンアップしたり初期化したりする必要はありません。サスペンド後に開始された新しいリクエストは、レジュームとそれに続くネットワーク初期化まで遅延されます。この遅延により、タイトル側で追加の処理を行うことなく、可能な限り早いタイミングでリクエストを開始できます。
タイトルが
xCurl の multi インターフェイスを使用している場合、未完了のリクエストがあるサスペンド中は、必要に応じて curl_multi_poll または curl_multi_wait とともに curl_multi_perform を呼び続ける必要があります。xCurl はすべての進行中のリクエストが完了するまでサスペンドをブロックするので、curl_multi_perform を呼び出さないとタイトルがサスペンド中にタイムアウトする可能性があります。サスペンド/レジューム状態にかかわらず、ライフサイクル全体を通じて curl_multi_perform を呼び続けることを推奨します。xCurl はサスペンド状態のすべての複雑さを内部で処理します。セキュリティ機能
xCurl を通じたすべての HTTPS リクエストは、通信セキュリティのベスト プラクティス (NDA 記事) に従います。xCurl は、タイトルの「シングル サインオン ポータル」で指定された特別な証明書ピニングも自動的に適用します。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 に適用される同時リクエスト制限を共有します。すべての呼び出しが正しく動作するよう、タイトルは同時リクエストを 8 以下に制限してください。この同時実行制限は、xCurl、WinHttp、および XBOX サービス API のいずれから発行される同時リクエストにも適用されます。
xCurl はデータ受信にフリップ バッファーを使用します。このパターンにより、タイトルが 1 つ目のバッファーから読み取っている間に 2 つ目のバッファーを埋めることでスループットを向上させます。ただし、読み取りコールバックが時間を要しすぎる場合や、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 インターフェイスは実装されていません。