Win32 API 日本語リファレンス
ホーム › Media › IReferenceClock

IReferenceClock

COM
📘 Microsoft Learn (日本語) · English
IID56a86897-0ad4-11ce-b03a-0020af0ba770継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IReferenceClock インターフェイスは、フィルターグラフの基準時刻(リファレンスタイム)を提供します。リファレンスクロックとして機能できるフィルターは、このインターフェイスを公開できます。

メソッド 4

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetTime(LONGLONG* pTime)

GetTime メソッドは、現在の基準時刻を取得します。

pTimeLONGLONG*out現在の時刻を 100 ナノ秒単位で受け取る変数へのポインター。

戻り値

HRESULT 値を返します。取り得る値には次のものが含まれます。

リターンコード 説明
E_POINTER
 NULL ポインター引数です。
S_FALSE
 返される時刻は前回の値と同じです。
S_OK
 成功しました。
vtbl 4 HRESULT AdviseTime(LONGLONG baseTime, LONGLONG streamTime, HANDLE hEvent, UINT_PTR* pdwAdviseCookie)

AdviseTime メソッドは、1 回限りの通知(advise)要求を作成します。

baseTimeLONGLONGin基準時刻。100 ナノ秒単位。「解説」を参照してください。
streamTimeLONGLONGinストリームオフセット時刻。100 ナノ秒単位。「解説」を参照してください。
hEventHANDLEin呼び出し側が作成したイベントのハンドル。
pdwAdviseCookieUINT_PTR*out通知要求の識別子を受け取る変数へのポインター。

戻り値

HRESULT 値を返します。取り得る値には次のものが含まれます。

リターンコード 説明
S_OK
 成功しました。
E_INVALIDARG
 時刻の値が無効です。
E_OUTOFMEMORY
 失敗しました。
E_POINTER
 NULL ポインター引数です。

解説(Remarks)

このメソッドは、基準時刻 rtBaseTime + rtStreamTime に対する 1 回限りの通知要求を作成します。この合計は 0 より大きく MAX_TIME より小さくなければなりません。そうでない場合、このメソッドは E_INVALIDARG を返します。要求された時刻になると、クロックは hEvent パラメーターで指定されたイベントをシグナル状態にします。

指定時刻に達する前に通知をキャンセルするには、Unadvise メソッドを呼び出し、この呼び出しで返された pdwAdviseToken の値を渡します。通知が発生した後は、クロックが自動的に通知をクリアするため、Unadvise を呼び出す必要はありません。ただし、呼び出してもエラーにはなりません。

vtbl 5 HRESULT AdvisePeriodic(LONGLONG startTime, LONGLONG periodTime, HANDLE hSemaphore, UINT_PTR* pdwAdviseCookie)

AdvisePeriodic メソッドは、周期的な通知要求を作成します。

startTimeLONGLONGin最初の通知の時刻。100 ナノ秒単位。0 より大きく MAX_TIME より小さくなければなりません。
periodTimeLONGLONGin通知間の間隔。100 ナノ秒単位。0 より大きくなければなりません。
hSemaphoreHANDLEin呼び出し側が作成したセマフォのハンドル。
pdwAdviseCookieUINT_PTR*out通知要求の識別子を受け取る変数へのポインター。

戻り値

HRESULT 値を返します。取り得る値には次のものが含まれます。

リターンコード 説明
S_OK
 成功しました。
E_INVALIDARG
 時刻の値が無効です。
E_OUTOFMEMORY
 失敗しました。
E_POINTER
 NULL ポインター引数です。

解説(Remarks)

各通知時刻において、クロックは hSemaphore パラメーターで指定されたセマフォを解放します。これ以上通知が不要になったら、IReferenceClock::Unadvise を呼び出し、この呼び出しで返された pdwAdviseToken の値を渡します。

次のコード例は、作成された時刻から 5 秒後にシグナルを発生させ、その後は 1 秒ごとにシグナルを発生させる通知要求を作成します。

C++ 
IReferenceClock *pRefClock = NULL;
// IReferenceClock ポインターを取得します(コードは省略)。


DWORD          dwAdviseToken;
HANDLE         hSemaphore = CreateSemaphore(NULL, 0, 0x7FFFFFFF, NULL);
REFERENCE_TIME rtPeriodTime = 10000000; // 1 秒間隔
REFERENCE_TIME rtNow;


pRefClock->GetTime(&rtNow);
pRefClock->AdvisePeriodic(rtNow + (5 * rtPeriodTime),
                          rtPeriodTime, 
                          hSemaphore, 
                          &dwAdviseToken);
...


pRefClock->Unadvise(dwAdviseToken);

vtbl 6 HRESULT Unadvise(UINT_PTR dwAdviseCookie)

Unadvise メソッドは、保留中の通知要求を削除します。

dwAdviseCookieUINT_PTRin削除する要求の識別子。IReferenceClock::AdviseTime または IReferenceClock::AdvisePeriodic が pdwAdviseToken パラメーターで返した値を使用します。

戻り値

HRESULT 値を返します。取り得る値には次のものが含まれます。

リターンコード 説明
S_FALSE
 見つかりませんでした。
S_OK
 成功しました。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IReferenceClock "{56A86897-0AD4-11CE-B03A-0020AF0BA770}"
#usecom global IReferenceClock IID_IReferenceClock "{}"
#comfunc global IReferenceClock_GetTime         3 var
#comfunc global IReferenceClock_AdviseTime      4 int64,int64,sptr,var
#comfunc global IReferenceClock_AdvisePeriodic  5 int64,int64,sptr,var
#comfunc global IReferenceClock_Unadvise        6 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。