IReferenceClock Interface

The IReferenceClock interface represents a system reference clock to be implemented by a filter in the filter graph and used by other filters.

Implement this interface if you are writing a filter that generates a system reference clock. Typically, this applies to audio renderer filters because audio sound boards usually contain a reference clock. Use the CBaseReferenceClock class to implement this interface.

Use this interface on any filter to obtain reference clock notifications for a duration of elapsed time (both singular and repetitive), or to retrieve the current time.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IReferenceClock methods Description
GetTime Gets the current time.
AdviseTime Requests an asynchronous notification that a duration has elapsed.
AdvisePeriodic Requests an asynchronous, periodic notification that a duration has elapsed.
Unadvise Cancels a request for notification.

IUnknown methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IReferenceClock methods	Description
GetTime	Gets the current time.
AdviseTime	Requests an asynchronous notification that a duration has elapsed.
AdvisePeriodic	Requests an asynchronous, periodic notification that a duration has elapsed.
Unadvise	Cancels a request for notification.

IReferenceClock::AdvisePeriodic

IReferenceClock Interface

Requests an asynchronous, periodic notification that a duration has elapsed.

Syntax

HRESULT AdvisePeriodic(

  REFERENCE_TIME rtStartTime,

  REFERENCE_TIME rtPeriodTime,

  HSEMAPHORE hSemaphore,

  DWORD *pdwAdviseCookie

  );

Parameters

rtStartTime
[in] Time the notification should begin.
rtPeriodTime
[in] Duration between notifications.
hSemaphore
[in] Handle of a semaphore through which to advise.
pdwAdviseCookie
[out] Pointer used to identify this call to AdvisePeriodic in the future; for example, to cancel it.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

When the time indicated by rtStartTime is reached, the semaphore whose handle is set as hSemaphore will be released. Thereafter, the semaphore will be released repetitively with a period of rtPeriodTime.

IReferenceClock::AdviseTime

IReferenceClock Interface

Requests an asynchronous notification that a duration has elapsed.

Syntax

HRESULT AdviseTime(

  REFERENCE_TIME rtBaseTime,

  REFERENCE_TIME rtStreamTime,

  HEVENT hEvent,

  DWORD *pdwAdviseCookie

  );

Parameters

rtBaseTime
[in] Base reference time.
rtStreamTime
[in] Stream offset time.
hEvent
[in] Handle of an event through which to advise.
pdwAdviseCookie
[out] Pointer to the destination of the token.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

When the time rtBaseTime+rtStreamTime is reached, the event whose handle is hEvent will be set. If the time has already passed, the event will be set immediately.

IReferenceClock::GetTime

IReferenceClock Interface

Retrieves the current time. REFERENCE_TIME is a LONGLONG type and loosely represents the number of 100-nanosecond units that have elapsed since some fixed start time. See Characteristics of a Reference Clock for other requirements on the reference clock.

Syntax

HRESULT GetTime(

  REFERENCE_TIME *pTime

  );

Parameters

pTime
[out] Pointer to the current time.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

IReferenceClock::Unadvise

IReferenceClock Interface

Cancels a request for notification.

Syntax

HRESULT Unadvise(
  DWORD dwAdviseCookie
  );

Parameters

dwAdviseCookie
[in] Request to cancel.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.