다음을 통해 공유

Microsoft 게임 개발 키트의 오류 처리

  • 아티클

Microsoft GDK(게임 개발 키트)는 새로운 기술과 기존 기술을 모두 포함하여 구축되었습니다. 이러한 기술에는 많은 클래식 Win32 스타일 API, COM API, DirectX 그래픽 API 등이 있으며 표준 오류 처리 방법이 이미 정의되어 있습니다. 따라서 오류를 처리하는 방법은 특정 기술에 따라 다릅니다.

대부분의 Microsoft 게임 개발 키트(GDK) API는 HRESULT 값을 반환하지만 일부 API는 여전히 클래식 Win32 또는 COM 오류 처리를 사용해야 할 수 있습니다.

대부분의 경우 Microsoft GDK(게임 개발 키트) API는 "예외 없음"으로 설계되었지만 원하는 경우 게임에서 여전히 C++ 예외 처리를 사용할 수 있습니다. 이 방법은 빠른 실패가 필요한 복구할 수 없는 오류를 처리하는 데 종종 적합합니다. 또한 코드에서 C++ 예외를 포함하여 또는 C++ 예외 없이 작동하는 '예외 안전' 코딩 스타일을 계속 사용하는 것이 좋습니다.

Microsoft GDK(게임 개발 키트) API에서 HRESULTS 처리

대부분의 Microsoft 게임 개발 키트(GDK) API는 HRESULT 값을 반환하여 API 호출의 성공 또는 실패를 나타냅니다. SUCCEEDED(hr) 또는 FAILED(hr) 매크로를 사용하여 복구할 수 있는 성공 또는 오류를 처리할 수 있습니다. 특정 오류 사례에 대한 특수 처리의 경우 HRESULT 반환 값을 확인하여 오류 처리 방법을 결정할 수 있습니다.

참고 항목

일반적으로 성공은 S_OK(으)로 표시되지만 S_FALSE을(를) 포함한 다른 유효한 성공 반환 값이 있습니다. 이 값은 최신 COM API에서 일반적으로 사용되지 않지만 hr == S_OK 대신 SUCCEEDED(hr)를 사용하는 것이 좋습니다.

Microsoft GDK(게임 개발 키트)는 XgameErr.h 파일에 사용자 지정 오류 코드 세트를 정의합니다. 자세한 내용은 오류 코드를 참조하세요.

많은 Microsoft GDK(게임 개발 키트) API는 WIL(Windows 구현 라이브러리)을 사용하여 내부 Win32 또는 COM 호출에서 반환된 오류를 래핑합니다. WIL이 HRESULT를 반환하기 위해 오류를 래핑하는 방법은 오류 처리 도우미를 참조하세요.

Xbox Live API의 HRESULTS 처리

Xbox Live 호출에서 반환되는 HRESULTS 목록을 보려면 Xbox Live HRESULT 오류 코드를 참조하세요.

또한 HRESULT 값을 XblGetErrorCondition에 전달하여 오류 조건을 관련 오류 그룹으로 그룹화한 다음 조치를 취할 수 있습니다. 오류 그룹은 XblErrorCondition 열거에 정의됩니다.

새 비동기 모델을 사용하여 오류 처리

Microsoft GDK(게임 개발 키트)에는 비동기 프로그래밍 모델에 설명된 새로운 C 스타일 비동기 모델이 도입되었습니다. 비동기 모델에는 일반적으로 사용자가 호출하는 API 쌍(예: XGameUiShowTextEntryAsync 및 XGameUiShowTextEntryResult)이 있습니다.

비동기 작업 제출

이 ...Async API는 다른 스레드에서 기능 호출을 대기시키기 위해 호출됩니다. 비동기 호출에 전달되는 매개 변수 중 하나는 XAsyncBlock 구조이며, 선택적으로 사용자 지정 콜백 기능이 들어 있을 수도 있습니다. 들어 있을 경우 이 기능는 async 작업이 완료될 때 호출됩니다. XAsyncBlock은 선택적으로 비동기 큐에 사용할 특정 작업 큐를 지정할 수도 있습니다. 호출의 진행 상황 추적에는 XAsyncBlock을 사용할 수 있습니다.

이 기능은 API가 작업을 대기시킬 수 있었는지 여부를 나타내는 ...Async 코드를 반환합니다HRESULT.

비동기 API 호출에서 가장 일반적인 HRESULTS 반환은 다음과 같습니다.

  • S_OK: 작업이 작업 큐에 성공적으로 추가되었음을 나타냅니다.
  • E_NO_TASK_QUEUE: 프로세스 작업 큐가 비활성화되었고(null(으)로 설정됨) XAsyncBlock이 작업 큐를 지정하지 않았음을 나타냅니다.

비동기 작업의 진행률 확인

비동기 API 호출에 사용된 XAsyncBlock을 전달하여 XAsyncGetStatus를 호출하여 비동기 작업의 상태를 확인할 수 있습니다. XAsyncGetStatus가 비동기 작업이 완료되거나 취소되기를 기다릴 것인지를 나타내는 선택적 부울 값을 전달할 수도 있습니다.

XAsyncGetStatus 호출에서 가장 일반적인 HRESULTS 반환은 다음과 같습니다.

  • S_OK: 비동기 작업이 성공적으로 완료되었습니다.
  • E_PENDING: 비동기 작업이 아직 큐에 있거나 진행 중입니다.
  • E_ABORT: 비동기 작업이 취소되었습니다.
  • E_INVALIDARG: 비동기 블록이 잘못되었습니다.
  • 기타: 비동기 작업이 실패하는 경우 비동기 작업에서 반환된 HRESULT 오류 코드를 나타냅니다. 가능한 값 목록은 해당 API 설명서를 확인하거나, 오류 코드를 참조하세요.

비동기 작업의 결과 확인

비동기 블록에서 콜백을 지정한 경우 콜백 기능에서 일치하는 ...Result API를 호출하여 비동기 호출의 결과를 확인할 수 있습니다. HRESULT 반환 값은 XAsyncGetStatus를 호출하여 반환되는 값과 일치해야 합니다. 콜백에서 API를 호출 하는 경우에는 E_PENDING을 반환 값으로 가져올 수 없습니다. 그러나 콜백 외부에서 API를 호출 하는 경우에는 반환 값을 확인하여 작업이 아직 진행 중인지 확인해야 합니다.

클래식 Win32 오류 처리 및 COM 오류 처리

HRESULT 값을 반환하지 않는 Win32 API는 설명서에서 반환 값이 오류를 나타내는 방법(일반적으로 0을 반환)을 참조하세요. 그런 다음 GetLastError API를 호출하여 최신 오류 코드를 검색할 수 있습니다. HRESULT_FROM_WIN32 매크로를 사용하여 클래식 Win32 오류 코드를 HRESULT로 변환할 수 있습니다.

Win32 API의 오류 처리에 대한 자세한 내용은 오류 처리를 참조하세요.

COM 오류 처리에 대한 자세한 내용은 COM의 오류 처리를 참조하세요.