> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# xCurl の概要
> xCurl の概要
この記事では、[libCurl](https://curl.haxx.se/libcurl/) API の Microsoft Game Development Kit (GDK) 準拠実装である `xCurl` ライブラリについて説明します。`xCurl` は、タイトルに特別なロジックや処理を求めることなく、すべてのセキュリティ要件およびベスト プラクティスに従うことで、タイトル開発を簡素化します。ただし、WebSocket 通信はサポートしていません。WebSocket 通信を実装する必要がある場合は、代わりに [libHttpClient](/build/console-features/networking/web-requests/http-networking#libhttpclient) を使用してください。
`xCurl` は、[WinHttp](/build/console-features/networking/web-requests/intro-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](/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize) が呼び出されるまで初期化できません。
`xCurl` メソッドの動作を理解するには、[libCurl API](https://curl.haxx.se/libcurl/c/) ドキュメントを参照してください。
`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 のヘッダーとライブラリをプロジェクトに追加します。
1. 開発 PC に Gaming Runtime Development Kit (GRDK) がインストールされていることを確認します。
2. ゲームの .vcxproj ファイルを開き、次の要素を追加します。これによりインポート ライブラリがリンクされ、ビルド出力に *xCurl.dll* が含まれます。
```xml theme={null}
Xbox.xCurl.API
```
1. `xCurl` は `libCurl` と区別するために別のヘッダーを持ちます。ゲームで *curl.h* をインクルードしている箇所を、以下のように *xCurl.h* に置き換えてください。
```cpp theme={null}
#include
```
## 構成
`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 記事)](/build/game-principles/security/communication-security-overview) に従います。`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 のカーネル メモリの詳細は、[ソケットのメモリに関する考慮事項](/build/console-features/networking/game-mesh/winsock-intro-networking#SocketMemory) を参照してください。
### xCurl のアロケーションの制御
既定では、`xCurl` は Windows ヒープを使用し、`XMemSetWin32HeapTrackingHooks` を通じてアロケーションを追跡できます。あるいは、`libCurl` と同様に初期化時にメモリ関数を提供することもできます。
[curl\_global\_init\_mem](https://curl.haxx.se/libcurl/c/curl_global_init_mem.html) に加えて、`xCurl` はオプションの [xCurl\_global\_init\_mem](/reference/networking/xcurl/functions/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_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` の `Share` インターフェイスは実装されていません。
### 転送の一時停止と再開
この機能は現時点でサポートされていません。コールバックから CURL\_WRITEFUNC\_PAUSE または CURL\_READFUNC\_PAUSE を返すと処理が中止され、再開できません。
## 関連項目
[libCurl API](https://curl.haxx.se/libcurl/c/)
[パートナー センターでの Web サービス構成 (NDA 記事)](/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/web-services/live-web-services)
[XBOX One コンソール上の Fiddler](/build/console-features/networking/tools/fiddler-setup-networking)
[通信セキュリティのベスト プラクティスの概要 (NDA 記事)](/build/game-principles/security/communication-security-overview)
## Related topics
- [xcurl_global_resume](/ja-jp/reference/networking/xcurl/functions/xcurl_global_resume.md)
- [xcurl_global_suspend](/ja-jp/reference/networking/xcurl/functions/xcurl_global_suspend.md)
- [xcurl_global_init_mem](/ja-jp/reference/networking/xcurl/functions/xcurl_global_init_mem.md)
- [Web リクエスト](/ja-jp/build/console-features/networking/web-requests/web-requests-toc.md)
- [Microsoft Game Development Kit ネットワークの概要](/ja-jp/build/console-features/networking/introduction-networking.md)