XCurl の概要

[アーティクル]
11/19/2024

このトピックでは、libCurl API の Microsoft Game Development Kit (GDK) 準拠の実装である xCurl ライブラリについて説明します。 Microsoft Game Development Kit (GDK) タイトルには xCurl を HTTP API にお勧めします。 xCurl は、特別なタイトルロジックや処理を必要とすることなく、すべてのセキュリティ要件とベストプラクティスに準拠することで、タイトル開発を簡素化します。ただし、これは WebSocket をサポートしていません。 WebSocket 通信を実装する必要がある場合は、代わりに libHttpClient を使用します。

XR-134: Web プロトコルを使用したデータ転送では、Xbox 本体用に開発されたタイトルがカスタム HTTP スタック実装を使用しないようにする必要があります。代わりに、オペレーティングシステムによって提供され、保守可能なスタックを使用します。これにより、Xbox ゲーマーは長期にわたって安定性とセキュリティの向上が保証されます。

xCurl が libCurl と異なる点は、xCurl が WinHttp 上に実装されており、Microsoft Game Development Kit (GDK) の要件やプロセスライフタイム管理 (PLM) を含むベストプラクティスに自動的に従っている点です。 xCurl は libCurl と API 互換ですが、xCurl 内のトランスポート層は WinHttp のみを使用し、libCurl は使用しません。したがって、xCurl は、バグ修正やバージョン番号など、libCurl のオープンソース実装と同期を保つ必要はありません。開発者は xCurl を使用して、ヘッダーインクルードとライブラリリンケージを 1 つだけ変更しながら、すべてのプラットフォームで同じ libCurl HTTP 実装を維持することをお勧めします。

一部の libCurl API は、ゲーム開発シナリオでは一般的に使用されていないか、WinHttp 内にマッピングできる同等の機能がないため、xCurl には実装されていません。違いは、このトピックの後半で説明します。

xCurl は、ゲームランタイムに依存し、XGameRuntimeInitialize が呼び出されるまで初期化することはできません。

xCurl メソッドの動作を理解するには、libCurl API ドキュメントのご覧ください。

注意

xCurl および WinHttp は、Xbox コンソールにおける唯一の HTTP の XR 準拠オプションです。 xCurl と WinHttp の実装は Windows PC と Xbox コンソールの両方で機能し、コードを変更する必要はありません。ただし、Windows PC では、libCurl またはその他の HTTP スタックを Microsoft Game Development Kit (GDK) タイトルで直接使用できます。XR-134 は Windows PC には適用されません。

デベロッパーサポート

xCurl は、libCurl ではなく WinHttp を搭載しており、Microsoft Game Development Kit (GDK) の一部です。

サポートリクエストは、Microsoft Game Development Kit (GDK) タイトルの推奨サポートパスを介して送信する必要があります。これには、Microsoft の担当者に連絡したり、Xbox デベロッパーフォーラムを介して開発者サポートチームに連絡したりすることが含まれます。

プロジェクトへの XCurl の追加

Windows 10 PC または Xbox コンソールのMicrosoft Game Development Kit (GDK) ゲームで xCurl を使用するには、プロジェクトに xCurl 拡張 SDK ヘッダーとライブラリを含めます。

開発用 PC にゲームランタイム開発キット (GRDK) がインストールされていることを確認します。
ゲームの vcxproj ファイルを開き、次の要素を追加します。これにより、インポートライブラリがリンクされ、ビルド出力に xCurl.dll が含まれます。
```
<GDKExtLibNames>Xbox.xCurl.API</GDKExtLibNames>
```
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 で失敗します。さらに、これらの要求に対して curl_easy_getinfo に CURLINFO_OS_ERRNO を問い合わせると、HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME) が返ってきます。これらの障害を一般的なネットワーク切断障害とは異なる方法で処理したい場合は、他の GRTS API を使用してください。

すべての xCurl ハンドルは、中断/再開の境界を含め、タイトルのライフサイクル全体を通じて有効です。中断/再開時に、xCurl ハンドルをクリーンアップまたは初期化する必要はありません。中断後に開始された新しい要求は、再開とそれに続くネットワークの初期化まで遅延され、タイトルによる追加の処理を必要とせず、できるだけ早く開始されるようになります。

注意

xCurl 用のマルチインターフェイスを使用している場合、タイトルは、未処理の要求がある間、中断時に、オプションで curl_multi_perform と共に curl_multi_poll または curl_multi_wait を継続して呼び出す必要があります。 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 を呼び出して、承認および署名ヘッダーを取得する必要があります。また CURLOPT_HEADER、CURLOPT_HTTPHEADER、CURLOPT_HEADERFUNCTION のオプションを curl_easy_setopt の呼び出しで使用して、要求を行う前にヘッダーを設定します。

メモリと同時実行に関する考慮事項

xCurl は WinHttp に適用される同じ同時実行要求の制限を共有しています。タイトルは、すべての呼び出しが正常に動作するように、同時実行要求を 8 以下に制限する必要があります。この同時実行制限は、xCurl、WinHttp、Xbox Service API のいずれかから発行された同時実行要求に適用されます。

xCurlは、反転バッファーを使用してデータを受信します。これにより、読み取りコールバックにフルバッファを提供しながら 2 つ目のバッファの埋め込みを開始し、1 つ目のバッファが埋め込みされている間に、読み取りコールバックに 2 つ目のバッファを提供するように切り替えることができます。ただし、読み取りコールバックに時間がかかりすぎたり、マルチモードで curl_multi_perform が頻繁に呼び出されない場合、WinSock のカーネルメモリ消費量が増えることもあります。 WinSock のカーネルメモリの詳細については、「socket memory considerations (ソケットメモリに関する考慮事項)」を参照してください。

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が実装されていません。これにより、fd_sets を使用して select や poll からデータが届くのを待つ機能も削除されます。処理の到着を待つには、curl_multi_wait と curl_multi_poll を使います。

xCurl では、以下の API は存在しません。

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 Share インターフェイスは実装されていません。

転送の一時停止と再開

現在、この機能はサポートされていません。コールバックから CURL_WRITEFUNC_PAUSE または CURL_READFUNC_PAUSE を返すと、再開することができない中断された操作が実行されます。

次の方法で共有

XCurl の概要

デベロッパーサポート

プロジェクトへの XCurl の追加

構成

ネットワークの初期化

タイトルの一時停止/再開

セキュリティ機能

メモリと同時実行に関する考慮事項

xCurl 割り当ての制御

サポートされているオプション

サポートされていない機能

ソケットおよび fd_set

転送の一時停止と再開

関連項目

その他のリソース

次の方法で共有

XCurl の概要

デベロッパー サポート

プロジェクトへの XCurl の追加

構成

ネットワークの初期化

タイトルの一時停止/再開

セキュリティ機能

メモリと同時実行に関する考慮事項

xCurl 割り当ての制御

サポートされているオプション

サポートされていない機能

ソケットおよび fd_set

CURL 共有

転送の一時停止と再開

関連項目

その他のリソース

デベロッパーサポート