## 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

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