Microsoft Game Development Kit でのエラー処理

Microsoft Game Development Kit (GDK) は、新しいテクノロジと既存のテクノロジの両方からなる数多くのテクノロジで構築されています。 これらのテクノロジとして、従来の多くの Win32 スタイルの API、COM API、DirectX グラフィックス API などがありますが、これらには標準的なエラー処理方法が既に定義されています。 その結果、各テクノロジごとに異なるエラー処理方法が存在します。

ほとんどの Microsoft Game Development Kit (GDK) の API は、 HRESULT 値を返しますが、従来の Win32 または COM のエラー処理を必要とする API もあります。

ほとんどの場合、Microsoft Game Development Kit (GDK) の API は "例外が発生しない" ように設計されていますが、ゲームでは必要に応じて C++ の例外処理を使用できます。 この方法は、直ちに失敗することを必要とする回復不能なエラーを処理する際に適しています。 また、コードで C++ の例外を使用しているかどうかに関係なく機能する "例外セーフ" なコーディング スタイルを引き続き採用することをお勧めします。

• Microsoft Game Development Kit (GDK) API からの HRESULTS の処理
• Xbox Live API による HRESULT の処理
• 新しい非同期モデルによるエラーの処理
• 従来の Win32 のエラー処理と COM のエラー処理

Microsoft Game Development Kit (GDK) API からの HRESULTS の処理

Microsoft Game Development Kit (GDK) の API の大多数では、API 呼び出しの成功または失敗を示すHRESULT 値が返されます。 SUCCEEDED(hr) マクロまたは FAILED(hr) マクロを使用して、それぞれ成功または回復可能なエラーを処理できます。 特定のエラーで固有の処理を実行するために、戻り値の HRESULT を確認して、エラーの処理方法を決定できます。

Microsoft Game Development Kit (GDK) では、XgameErr.h で一連のカスタム エラー コードを定義しています。 詳細については、エラー コードをご覧ください。

Microsoft Game Development Kit (GDK) のAPI の多くでは、Windows 実装ライブラリ (WIL) を使用して、Win32 または COM の呼び出しから返されたエラーをラップします。 WIL でエラーがラップされて HRESULT が返される様子について詳しくは、「Error handling helpers」をご覧ください。

Xbox Live API による HRESULT の処理

Xbox Live の呼び出しから返されることが考えられる HRESULTS のリストについては「Xbox Live HRESULT エラー コード」を参照してください。

また、HRESULT 値を XblGetErrorCondition に渡し、互いに関連するエラーのグループにエラー条件をまとめて、それらのグループごとに適切なアクションを実施できます。 XblErrorCondition 列挙型でエラー グループが定義されています。

新しい非同期モデルによるエラーの処理

Microsoft Game Development Kit (GDK) では、「非同期プログラミングモデル」に説明がある新しい C スタイルの非同期モデルが導入されています。 非同期モデルでは、呼び出す API がペアになっていることが普通です。たとえば、XGameUiShowTextEntryAsync と XGameUiShowTextEntryResult がペアになっています。

非同期タスクの送信

...Async API は、別のスレッドで関数呼び出しをキューに置くために呼び出します。 非同期呼び出しに渡すパラメーターとして XAsyncBlock 構造体があります。この構造体には、ユーザー指定のコールバック関数を必要に応じて記述できます。 存在する場合、この関数は非同期タスクが完了すると呼び出されます。 XAsyncBlock では、非同期キューに使用する特定のタスク キューを必要に応じて指定することもできます。 XAsyncBlock を使用して呼び出しの進捗状況を追跡できます。

...Async 関数からは、API でキューにタスクを置くことができたかどうかを示す HRESULT コードが返されます。

非同期 API 呼び出しで一般的に返される HRESULTS は次のとおりです。

• S_OK: タスクキューにタスクが正常に追加されたことを示します。
• E_NO_TASK_QUEUE: プロセス タスク キューが無効になって (null に設定されて) おり、XAsyncBlock がタスクキューを指定していないことを示します。

非同期タスクの進捗状況の確認

XAsyncGetStatus を呼び出して、非同期 API 呼び出しで使用された XAsyncBlock を渡すことにより、非同期タスクの状態を確認できます。 また、非同期タスクの完了まで XAsyncGetStatus を待機状態にするか、タスクをキャンセルするかを示すブール値を必要に応じて渡すこともできます。

XAsyncGetStatus の呼び出しで一般的に返される HRESULTS は次のとおりです。

• S_OK: 非同期タスクが正常に完了しました。
• E_PENDING: 非同期タスクがまだキューに置かれたままか、その実行が進行中です。
• E_ABORT: 非同期タスクがキャンセルされました。
• E_INVALIDARG: 非同期ブロックが無効です。
• その他: 非同期タスクが失敗すると、HRESULT によるエラー コードが非同期タスクから返されたことを示します。 返される可能性のある値のリストについては、個々の API のドキュメントを確認するか、「エラー コード」で参照します。

非同期タスクの実行結果の確認

非同期ブロックでコールバックを指定している場合は、該当の ...Result API を呼び出すことで、非同期呼び出しの結果をコールバック関数で確認できます。 戻り値 HRESULT は、XAsyncGetStatus を呼び出して返される値と一致する必要があります。 コールバックで API を呼び出す場合は、戻り値として E_PENDING が得られません。 ただし、コールバックの外部で API を呼び出す場合は、戻り値を確認してタスクが進行中ではないことを確認する必要があります。

従来の Win32 のエラー処理と COM のエラー処理

Win32 API で HRESULT 値が返されない場合は、該当のドキュメントを参照して、エラーが戻り値でどのように示されるかを確認します (通常はゼロを返すことでエラーであることが示されます)。 つづいて、GetLastError API を呼び出すことによって最新のエラーコードを取得できます。 HRESULT_FROM_WIN32 マクロを使用すると、従来の Win32 のエラー コードを HRESULT に変換できます。

Win32 API によるエラー処理の詳細については「エラー処理」を参照してください。

COM によるエラー処理の詳細については「Error Handling in COM」を参照してください。