Harlinn::Windows::Media::StreamingMediaSink Class Reference

#include <HWStreamingMediaSink.h>

Inheritance diagram for Harlinn::Windows::Media::StreamingMediaSink:

Collaboration diagram for Harlinn::Windows::Media::StreamingMediaSink:

Public Member Functions
virtual HRESULT STDMETHODCALLTYPE	GetCharacteristics (__RPC__out DWORD *pdwCharacteristics) override
	Gets the characteristics of the media sink.
virtual HRESULT STDMETHODCALLTYPE	AddStreamSink (DWORD dwStreamSinkIdentifier, __RPC__in_opt IMFMediaType *pMediaType, __RPC__deref_out_opt IMFStreamSink **ppStreamSink) override
	Adds a new stream sink to the media sink.
virtual HRESULT STDMETHODCALLTYPE	RemoveStreamSink (DWORD dwStreamSinkIdentifier) override
	Removes a stream sink from the media sink.
virtual HRESULT STDMETHODCALLTYPE	GetStreamSinkCount (__RPC__out DWORD *pcStreamSinkCount) override
	Gets the number of stream sinks on this media sink.
virtual HRESULT STDMETHODCALLTYPE	GetStreamSinkByIndex (DWORD dwIndex, __RPC__deref_out_opt IMFStreamSink **ppStreamSink) override
	Gets a stream sink, specified by index.
virtual HRESULT STDMETHODCALLTYPE	GetStreamSinkById (DWORD dwStreamSinkIdentifier, __RPC__deref_out_opt IMFStreamSink **ppStreamSink) override
	Gets a stream sink, specified by stream identifier.
virtual HRESULT STDMETHODCALLTYPE	SetPresentationClock (__RPC__in_opt IMFPresentationClock *pPresentationClock) override
	Sets the presentation clock on the media sink.
virtual HRESULT STDMETHODCALLTYPE	GetPresentationClock (__RPC__deref_out_opt IMFPresentationClock **ppPresentationClock) override
	Gets the presentation clock that was set on the media sink.
virtual HRESULT STDMETHODCALLTYPE	Shutdown () override
	Shuts down the media sink and releases the resources it is using.
virtual HRESULT STDMETHODCALLTYPE	BeginFinalize (IMFAsyncCallback *pCallback, IUnknown *punkState) override
	Notifies the media sink to asynchronously take any steps it needs to finish its tasks.
virtual HRESULT STDMETHODCALLTYPE	EndFinalize (IMFAsyncResult *pResult) override
	Completes an asynchronous finalize operation.
virtual HRESULT STDMETHODCALLTYPE	OnClockStart (MFTIME hnsSystemTime, LONGLONG llClockStartOffset) override
	Called when the presentation clock starts.
virtual HRESULT STDMETHODCALLTYPE	OnClockStop (MFTIME hnsSystemTime) override
	Called when the presentation clock stops.
virtual HRESULT STDMETHODCALLTYPE	OnClockPause (MFTIME hnsSystemTime) override
	Called when the presentation clock pauses.
virtual HRESULT STDMETHODCALLTYPE	OnClockRestart (MFTIME hnsSystemTime) override
	Called when the presentation clock restarts from the same position while paused.
virtual HRESULT STDMETHODCALLTYPE	OnClockSetRate (MFTIME hnsSystemTime, float flRate) override
	Called when the rate changes on the presentation clock.
virtual HRESULT STDMETHODCALLTYPE	GetParameters (__RPC__out DWORD *pdwFlags, __RPC__out DWORD *pdwQueue) override
	Provides configuration information to the dispatching thread for a callback.
virtual HRESULT STDMETHODCALLTYPE	Invoke (__RPC__in_opt IMFAsyncResult *pAsyncResult) override

Member Function Documentation

AddStreamSink()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::AddStreamSink ( DWORD dwStreamSinkIdentifier, __RPC__in_opt IMFMediaType * pMediaType, __RPC__deref_out_opt IMFStreamSink ** ppStreamSink )

inlineoverridevirtual

Adds a new stream sink to the media sink.

Parameters

dwStreamSinkIdentifier	Identifier for the new stream. The value is arbitrary but must be unique
pMediaType	Pointer to the IMFMediaType interface, specifying the media type for the stream. This parameter can be NULL.
ppStreamSink	Receives a pointer to the new stream sink's IMFStreamSink interface. The caller must release the interface.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• MF_E_INVALIDSTREAMNUMBER: The specified stream identifier is not valid.
• MF_E_SHUTDOWN: The media sink's Shutdown method has been called.
• MF_E_STREAMSINK_EXISTS: There is already a stream sink with the same stream identifier.
• MF_E_STREAMSINKS_FIXED: This media sink has a fixed set of stream sinks.New stream sinks cannot be added.

Not all media sinks support this method. If the media sink does not support this method, the IMFMediaSink::GetCharacteristics method returns the MEDIASINK_FIXED_STREAMS flag.

If pMediaType is NULL, use the IMFMediaTypeHandler interface to set the media type. Call IMFStreamSink::GetMediaTypeHandler to get a pointer to the interface.

</remakrs>

BeginFinalize()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::BeginFinalize ( IMFAsyncCallback * pCallback, IUnknown * punkState )

inlineoverridevirtual

Notifies the media sink to asynchronously take any steps it needs to finish its tasks.

Parameters

pCallback	Pointer to the IMFAsyncCallback interface of an asynchronous object. The caller must implement this interface.
punkState	Pointer to the IUnknown interface of a state object, defined by the caller. This parameter can be NULL. You can use this object to hold state information. The object is returned to the caller when the callback is invoked.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.

Many archive media sinks have steps they need to do at the end of archiving to complete their file operations, such as updating the header (for some formats) or flushing all pending writes to disk. In some cases, this may include expensive operations such as indexing the content. BeginFinalize is an asynchronous way to initiate final tasks.

When the finalize operation is complete, the callback object's IMFAsyncCallback::Invoke method is called. At that point, the application should call IMFFinalizableMediaSink::EndFinalize to complete the asynchronous request.

EndFinalize()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::EndFinalize ( IMFAsyncResult * pResult )

inlineoverridevirtual

Completes an asynchronous finalize operation.

Parameters

pResult

Pointer to the IMFAsyncResult interface. Pass in the same pointer that your callback object received in the IMFAsyncCallback::Invoke method.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.

Call this method after the IMFFinalizableMediaSink::BeginFinalize method completes asynchronously.

GetCharacteristics()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::GetCharacteristics ( __RPC__out DWORD * pdwCharacteristics )

inlineoverridevirtual

Gets the characteristics of the media sink.

Parameters

pdwCharacteristics

Receives a bitwise OR of zero or more flags. The following flags are defined:

• MEDIASINK_FIXED_STREAMS (0x00000001): The media sink has a fixed number of streams. It does not support the IMFMediaSink::AddStreamSink and IMFMediaSink::RemoveStreamSink methods.This flag is a hint to the application.

• MEDIASINK_CANNOT_MATCH_CLOCK (0x00000002):The media sink cannot match rates with an external clock. For best results, this media sink should be used as the time source for the presentation clock. If any other time source is used, the media sink cannot match rates with the clock, with poor results(for example, glitching).

  This flag should be used sparingly, because it limits how the pipeline can be configured.

• MEDIASINK_RATELESS (0x00000004): The media sink is rateless. It consumes samples as quickly as possible, and does not synchronize itself to a presentation clock. Most archiving sinks are rateless.

• MEDIASINK_CLOCK_REQUIRED (0x00000008): The media sink requires a presentation clock. The presentation clock is set by calling the media sink's IMFMediaSink::SetPresentationClock method.

  This flag is obsolete, because all media sinks must support the SetPresentationClock method, even if the media sink ignores the clock (as in a rateless media sink).

• MEDIASINK_CAN_PREROLL (0x00000010): The media sink can accept preroll samples before the presentation clock starts. The media sink exposes the IMFMediaSinkPreroll interface.
• MEDIASINK_REQUIRE_REFERENCE_MEDIATYPE (0x00000020): The first stream sink (index 0) is a reference stream. The reference stream must have a media type before the media types can be set on the other stream sinks.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• MF_E_SHUTDOWN: The media sink's Shutdown method has been called.

GetParameters()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::GetParameters ( __RPC__out DWORD * pdwFlags, __RPC__out DWORD * pdwQueue )

inlineoverridevirtual

Provides configuration information to the dispatching thread for a callback.

Parameters

pdwFlags

Receives a flag indicating the behavior of the callback object's IMFAsyncCallback::Invoke method. The following values are defined. The default value is zero.

• Zero: The callback does not take a long time to complete, but has no specific restrictions on what system calls it makes. The callback generally takes less than 30 milliseconds to complete.

• MFASYNC_FAST_IO_PROCESSING_CALLBACK: The callback does very minimal processing. It takes less than 1 millisecond to complete.

  The callback must be invoked from one of the following work queues:

  • MFASYNC_CALLBACK_QUEUE_IO
  • MFASYNC_CALLBACK_QUEUE_TIMER

• MFASYNC_SIGNAL_CALLBACK: Implies MFASYNC_FAST_IO_PROCESSING_CALLBACK, with the additional restriction that the callback does no processing (less than 50 microseconds), and the only system call it makes is SetEvent.

  The callback must be invoked from one of the following work queues:

  • MFASYNC_CALLBACK_QUEUE_IO
  • MFASYNC_CALLBACK_QUEUE_TIMER
• MFASYNC_BLOCKING_CALLBACK: Blocking callback.
• MFASYNC_REPLY_CALLBACK: Reply callback.

Parameters

pdwQueue

Receives the identifier of the work queue on which the callback is dispatched.

This value can specify one of the standard Media Foundation work queues, or a work queue created by the application. For list of standard Media Foundation work queues, see Work Queue Identifiers. To create a new work queue, call MFAllocateWorkQueue. The default value is MFASYNC_CALLBACK_QUEUE_STANDARD.

If the work queue is not compatible with the value returned in pdwFlags, the Media Foundation platform returns MF_E_INVALID_WORKQUEUE when it tries to dispatch the callback. (See MFPutWorkItem.)

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• E_NOTIMPL: Not implemented. Assume the default behavior.

The GetParameters method returns information about the callback so that the dispatching thread can optimize the process that it uses to invoke the callback.

If the method returns a value other than zero in the pdwFlags parameter, your Invoke method must meet the requirements described here. Otherwise, the callback might delay the pipeline.

If you want default values for both parameters, return E_NOTIMPL. The default values are given in the parameter descriptions on this page.

GetPresentationClock()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::GetPresentationClock ( __RPC__deref_out_opt IMFPresentationClock ** ppPresentationClock )

inlineoverridevirtual

Gets the presentation clock that was set on the media sink.

Parameters

ppPresentationClock

Receives a pointer to the presentation clock's IMFPresentationClock interface. The caller must release the interface.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• MF_E_NO_CLOCK: No clock has been set.To set the presentation clock, call IMFMediaSink::SetPresentationClock.
• MF_E_SHUTDOWN: The media sink's Shutdown method has been called.

GetStreamSinkById()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::GetStreamSinkById ( DWORD dwStreamSinkIdentifier, __RPC__deref_out_opt IMFStreamSink ** ppStreamSink )

inlineoverridevirtual

Gets a stream sink, specified by stream identifier.

Parameters

dwStreamSinkIdentifier	Stream identifier of the stream sink.
ppStreamSink	Receives a pointer to the stream's IMFStreamSink interface. The caller must release the interface.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• MF_E_INVALIDSTREAMNUMBER: The stream identifier is not valid.
• MF_E_SHUTDOWN: The media sink's Shutdown method has been called.

If you add a stream sink by calling the IMFMediaSink::AddStreamSink method, the stream identifier is specified in the dwStreamSinkIdentifier parameter of that method. If the media sink has a fixed set of streams, the media sink assigns the stream identifiers.

To enumerate the streams by index number instead of stream identifier, call IMFMediaSink::GetStreamSinkByIndex.

GetStreamSinkByIndex()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::GetStreamSinkByIndex ( DWORD dwIndex, __RPC__deref_out_opt IMFStreamSink ** ppStreamSink )

inlineoverridevirtual

Gets a stream sink, specified by index.

Parameters

dwIndex	Zero-based index of the stream. To get the number of streams, call IMFMediaSink::GetStreamSinkCount.
ppStreamSink	Receives a pointer to the stream's IMFStreamSink interface. The caller must release the interface.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• MF_E_INVALIDINDEX: Invalid index.
• MF_E_SHUTDOWN: The media sink's Shutdown method has been called.

Enumerating stream sinks is not a thread-safe operation, because stream sinks can be added or removed between calls to this method.

GetStreamSinkCount()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::GetStreamSinkCount ( __RPC__out DWORD * pcStreamSinkCount )

inlineoverridevirtual

Gets the number of stream sinks on this media sink.

Parameters

pcStreamSinkCount

Receives the number of stream sinks.

Returns

• S_OK: The method succeeded.
• MF_E_SHUTDOWN: The media sink's Shutdown method has been called.

Invoke()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::Invoke ( __RPC__in_opt IMFAsyncResult * pAsyncResult )

inlineoverridevirtual

OnClockPause()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::OnClockPause ( MFTIME hnsSystemTime )

inlineoverridevirtual

Called when the presentation clock pauses.

Parameters

hnsSystemTime

The system time when the clock was paused, in 100-nanosecond units.

Returns

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code

When the presentation clock's IMFPresentationClock::Pause method is called, the clock notifies the presentation time source by calling the time source's OnClockPause method. This call occurs synchronously within the Pause method. If the time source returns an error from OnClockPause, the presentation clock's Pause method returns an error and the state change does not take place.

For any object that is not the presentation time source, the OnClockPause method is called asynchronously, after the state change is completed. In that case, the return value from this method is ignored.

OnClockRestart()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::OnClockRestart ( MFTIME hnsSystemTime )

inlineoverridevirtual

Called when the presentation clock restarts from the same position while paused.

Parameters

hnsSystemTime

The system time when the clock restarted, in 100-nanosecond units.

Returns

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

This method is called if the presentation clock is paused and the IMFPresentationClock::Start method is called with the value PRESENTATION_CURRENT_POSITION.

The clock notifies the presentation time source by calling the time source's OnClockRestart method. This call occurs synchronously within the Start method. If the time source returns an error from OnClockRestart, the presentation clock's Start method returns an error and the state change does not take place.

For any object that is not the presentation time source, the OnClockRestart method is called asynchronously, after the state change is completed. In that case, the return value from this method is ignored.

OnClockSetRate()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::OnClockSetRate ( MFTIME hnsSystemTime, float flRate )

inlineoverridevirtual

Called when the rate changes on the presentation clock.

Parameters

hnsSystemTime	The system time when the rate was set, in 100-nanosecond units.
flRate	The new rate, as a multiplier of the normal playback rate.

Returns

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

When the presentation clock's IMFRateControl::SetRate method is called, the clock notifies the presentation time source by calling the time source's OnClockSetRate method. This call occurs synchronously within the SetRate method. If the time source returns an error from OnClockSetRate, the presentation clock's SetRate method returns an error and the state change does not take place.

For any object that is not the presentation time source, the OnClockSetRate method is called asynchronously, after the state change is completed. In that case, the return value from this method is ignored.

OnClockStart()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::OnClockStart ( MFTIME hnsSystemTime, LONGLONG llClockStartOffset )

inlineoverridevirtual

Called when the presentation clock starts.

Parameters

hnsSystemTime	The system time when the clock started, in 100-nanosecond units.
llClockStartOffset	The new starting time for the clock, in 100-nanosecond units. This parameter can also equal PRESENTATION_CURRENT_POSITION, indicating the clock has started or restarted from its current position.

Returns

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

This method is called when the presentation clock's IMFPresentationClock::Start method is called, with the following exception: If the clock is paused and Start is called with the value PRESENTATION_CURRENT_POSITION, IMFClockStateSink::OnClockRestart is called instead of OnClockStart.

The clock notifies the presentation time source by calling the time source's OnClockStart method. This call occurs synchronously within the Start method. If the time source returns an error from OnClockStart, the presentation clock's Start method returns an error and the state change does not take place.

For any object that is not the presentation time source, the OnClockStart method is called asynchronously, after the state change is completed. In that case, the return value from this method is ignored.

The value given in llClockStartOffset is the presentation time when the clock starts, so it is relative to the start of the presentation. Media sinks should not render any data with a presentation time earlier than llClockStartOffSet. If a sample straddles the offset—that is, if the offset falls between the sample's start and stop times—the sink should either trim the sample so that only data after llClockStartOffset is rendered, or else simply drop the sample.

OnClockStop()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::OnClockStop ( MFTIME hnsSystemTime )

inlineoverridevirtual

Called when the presentation clock stops.

Parameters

hnsSystemTime

The system time when the clock stopped, in 100-nanosecond units.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• MF_E_SINK_ALREADYSTOPPED: Deprecated.Do not use this error code.

When the presentation clock's IMFPresentationClock::Stop method is called, the clock notifies the presentation time source by calling the presentation time source's OnClockStop method. This call occurs synchronously within the Stop method. If the time source returns an error from OnClockStop, the presentation clock's Stop method returns an error and the state change does not take place.

For any object that is not the presentation time source, the OnClockStop method is called asynchronously, after the state change is completed.

If an object is already stopped, it should return S_OK from OnClockStop. It should not return an error code.

RemoveStreamSink()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::RemoveStreamSink ( DWORD dwStreamSinkIdentifier )

inlineoverridevirtual

Removes a stream sink from the media sink.

Parameters

dwStreamSinkIdentifier

Identifier of the stream to remove. The stream identifier is defined when you call IMFMediaSink::AddStreamSink to add the stream sink.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• E_INVALIDARG: This particular stream sink cannot be removed.
• MF_E_INVALIDSTREAMNUMBER: The stream number is not valid.
• MF_E_NOT_INITIALIZED: The media sink has not been initialized.
• MF_E_SHUTDOWN: The media sink's Shutdown method has been called.
• MF_E_STREAMSINKS_FIXED: This media sink has a fixed set of stream sinks.Stream sinks cannot be removed.

SetPresentationClock()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::SetPresentationClock ( __RPC__in_opt IMFPresentationClock * pPresentationClock )

inlineoverridevirtual

Sets the presentation clock on the media sink.

Parameters

pPresentationClock

Pointer to the IMFPresentationClock interface of the presentation clock, or NULL. If the value is NULL, the media sink stops listening to the presentation clock that was previously set, if any.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• MF_E_CLOCK_NO_TIME_SOURCE: The presentation clock does not have a time source.Call SetTimeSource on the presentation clock.
• MF_E_SHUTDOWN: The media sink's Shutdown method has been called.

During streaming, the media sink attempts to match rates with the presentation clock. Ideally, the media sink presents samples at the correct time according to the presentation clock and does not fall behind. Rateless media sinks are an exception to this rule, as they consume samples as quickly as possible and ignore the clock. If the sink is rateless, the IMFMediaSink::GetCharacteristics method returns the MEDIASINK_RATELESS flag.

The presentation clock must have a time source. Before calling this method, call IMFPresentationClock::SetTimeSource on the presentation clock to set the presentation time source. Some media sinks provide time sources; therefore, the media sink might be the time source for its own presentation clock. Regardless of what object provides the time source, however, the media sink must attempt to match rates with the clock specified in pPresentationClock. If a media sink cannot match rates with an external time source, the media sink's IMFMediaSink::GetCharacteristics method retrieves the MEDIASINK_CANNOT_MATCH_CLOCK flag. In this case, SetPresentationClock will still succeed, but the results will not be optimal. The sink might not render samples quickly enough to match rates with the presentation clock.

If pPresentationClock is non-NULL, the media sink must register for clock state notifications, by calling IMFPresentationClock::AddClockStateSink on the presentation clock. If the method is called again with a new presentation clock, or if pPresentationClock is NULL, the media sink must call IMFPresentationClock::RemoveClockStateSink to deregister itself from the previous clock.

All media sinks must support this method.

Shutdown()

virtual HRESULT STDMETHODCALLTYPE Harlinn::Windows::Media::StreamingMediaSink::Shutdown ( )

inlineoverridevirtual

Shuts down the media sink and releases the resources it is using.

Returns

The method returns an HRESULT. Possible values include, but are not limited to, the following:

• S_OK: The method succeeded.
• MF_E_SHUTDOWN: The media sink was shut down.

If the application creates the media sink, it is responsible for calling Shutdown to avoid memory or resource leaks. In most applications, however, the application creates an activation object for the media sink, and the Media Session uses that object to create the media sink. In that case, the Media Session — not the application — shuts down the media sink. (For more information, see Activation Objects.)

After this method returns, all methods on the media sink return MF_E_SHUTDOWN, except for IUnknown methods and IMFMediaEventGenerator methods. The sink will not raise any events after this method is called.

---

The documentation for this class was generated from the following file:

• HWStreamingMediaSink.h