次の方法で共有

XCurl の概要

  • [アーティクル]

このトピックでは、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 ヘッダーとライブラリを含めます。

  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 で失敗します。 さらに、これらの要求に対して 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 共有

CURL Share インターフェイスは実装されていません。

転送の一時停止と再開

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

関連項目

libCurl API

パートナー センターで Web サービスをセットアップする (NDA トピック)

Xbox One 本体上の Fiddler

通信セキュリティのベスト プラクティスの概要 (NDA トピック)