IDirectInputDevice8::GetDeviceData メソッド

[アーティクル]
04/22/2010

IDirectInputDevice8::GetDeviceData メソッド

デバイスからバッファリングデータを取得する。

構文

HRESULT GetDeviceData(      
    DWORD cbObjectData,
    LPDIDEVICEOBJECTDATA rgdod,
    LPDWORD pdwInOut,
    DWORD dwFlags
);

パラメータ

cbObjectData
DIOBJECTDATAFORMAT 構造体のサイズ (バイト単位)。
rgdod
バッファリングデータを受け取る DIDEVICEOBJECTDATA 構造体の配列。この配列の要素数は、pdwInOut パラメータの値と等しくなければならない。このパラメータが NULL の場合、バッファリングデータはどこにも格納されないが、その他の副次エフェクトはすべて発生する。
pdwInOut
入力パラメータは、rgdod パラメータが指す配列の要素数である。出力パラメータは、実際に取得された要素数である。
dwFlags
データの取得方法を制御するフラグ。ゼロまたは次のフラグを指定する。
- DIGDD_PEEK
  バッファから項目を削除しない。これ以降の IDirectInputDevice8::GetDeviceData 呼び出しで、同じデータを読み取ることができる。通常、データは読み取り後、バッファから削除される。

戻り値

成功した場合は、DI_OK または DI_BUFFEROVERFLOW を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INPUTLOST	入力デバイスへのアクセスが失われた。再取得しなければならない。
DIERR_INVALIDPARAM	無効なパラメータが、戻ってくる関数に渡されたか、オブジェクトがその関数を呼び出せる状態になかった。この値は、標準のコンポーネントオブジェクトモデル (COM) 戻り値である E_INVALIDARG に等しい。
DIERR_NOTACQUIRED	操作は、デバイスが取得されない限り実行できない。
DIERR_NOTBUFFERED	デバイスはバッファリングされていない。バッファリングを有効にするには、DIPROP_BUFFERSIZE プロパティを設定する。
DIERR_NOTINITIALIZED	このオブジェクトは初期化されていない。

注意

注メソッドが DI_BUFFEROVERFLOW を返す場合、rgdod 配列のデータは切り捨てられている。

Microsoft® DirectInput® のデバッグバージョンでは、IDirectInputDevice8::GetDeviceData への呼び出しが実行され、デバイスが解放されていないと、デバイスデータバッファにランダムバイトが送信される。ランダムデバイスデータを使わないようにするには、常に DIERR_UNACQUIRED を確認する。

デバイスデータを取得する前に、IDirectInputDevice8::SetDataFormat メソッドと IDirectInputDevice8::SetProperty メソッド、または IDirectInputDevice8::SetActionMap メソッドを使ってデータ形式とバッファサイズを設定しなければならない。また、IDirectInputDevice8::Acquire メソッドを使ってデバイスを取得しなければならない。

バッファが保持する最大イベント数は、IDirectInputDevice8::SetProperty メソッドで設定したバッファサイズよりも小さい。

次の例では、バッファリングデータ要素を最大 10 個まで読み取る。デバイスバッファからデータを読み取りながら削除している。

DIDEVICEOBJECTDATA rgdod[10]; 
DWORD dwItems = 10; 
hres = idirectinputdevice9_GetDeviceData( 
    sizeof(DIDEVICEOBJECTDATA), 
    rgdod, 
    &dwItems, 
    0); 
if (SUCCEEDED(hres)) { 
    // dwItems = Number of elements read (could be zero).
    if (hres == DI_BUFFEROVERFLOW) { 
    // Buffer had overflowed. 
    } 
}

バッファをフラッシュして、フラッシュした項目の数を取得するには、rgdod パラメータに NULL、pdwInOut パラメータに INFINITE を含む変数へのポインタをそれぞれ指定する。次の例は、その方法を示している。

dwItems = INFINITE; 
hres = idirectinputdevice9_GetDeviceData( 
            pdid, 
            sizeof(DIDEVICEOBJECTDATA), 
            NULL, 
            &dwItems, 
            0); 
if (SUCCEEDED(hres)) { 
    // Buffer successfully flushed. 
    // dwItems = Number of elements flushed. 
    if (hres == DI_BUFFEROVERFLOW) { 
        // Buffer had overflowed. 
    } 
}

デバイスバッファ中の要素数を調べるには、rgdod パラメータに NULL、pdwInOut パラメータに INFINITE、dwFlags に DIGDD_PEEK をそれぞれ指定する。次の例は、その方法を示している。

dwItems = INFINITE; 
hres = idirectinputdevice9_GetDeviceData( 
            pdid, 
            sizeof(DIDEVICEOBJECTDATA), 
            NULL, 
            &dwItems, 
            DIGDD_PEEK); 
if (SUCCEEDED(hres)) { 
    // dwItems = Number of elements in buffer. 
    if (hres == DI_BUFFEROVERFLOW) { 
        // Buffer overflow occurred; not all data 
        //   was successfully captured. 
    } 
}

バッファオーバーフローが発生したかどうかを調べるには、rgdod パラメータに NULL、pdwInOut パラメータにゼロをそれぞれ設定する。次の例は、その方法を示している。

dwItems = 0; 
hres = idirectinputdevice9_GetDeviceData( 
            pdid, 
            sizeof(DIDEVICEOBJECTDATA), 
            NULL, 
            &dwItems, 
            0); 
if (hres == DI_BUFFEROVERFLOW) { 
    // Buffer overflow occurred. 
}

参照

IDirectInputDevice8::Poll、ポーリングとイベント通知

IDirectInputDevice8::GetDeviceData メソッド

IDirectInputDevice8::GetDeviceData メソッド

その他のリソース