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.

When to Implement

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.

When to Use

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.

---

IReferenceClock::AdvisePeriodic

IReferenceClock Interface

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

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] Used to identify this call to AdvisePeriodic in the future; for example, to cancel it.

Return Values

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

Value	Meaning
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.

See Also

IReferenceClock::Unadvise, CBaseReferenceClock::AdvisePeriodic

---

IReferenceClock::AdviseTime

IReferenceClock Interface

Requests an asynchronous notification that a duration has elapsed.

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] Destination of the token.

Return Values

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

Value	Meaning
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.

See Also

IReferenceClock::Unadvise

---

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.

HRESULT GetTime(
  REFERENCE_TIME * pTime
  );

Parameters

pTime

[out] Current time.

Return Values

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

Value	Meaning
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.

HRESULT Unadvise(
  DWORD dwAdviseCookie
  );

Parameters

dwAdviseCookie

[in] Request to cancel.

Return Values

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

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

See Also

IReferenceClock::AdviseTime, IReferenceClock::AdvisePeriodic

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page