IStreamSample Interface

The IStreamSample interface provides control over the behavior of stream samples. You can retrieve the media stream that created the sample, set or retrieve sample start and stop times, check the sample's completion status, and perform a developer-specified function on the sample itself.

Implement this interface when you implement a media stream for a new media type. The interface is exposed on sample objects created by media streams.

Use this interface when you want to control data samples created by IMediaStream or its derived interfaces.

Methods in Vtable Order

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

IStreamSample methods Description

GetMediaStream Retrieves a pointer to the media stream object that created the current sample.
GetSampleTimes Retrieves the current sample's start and end times.
SetSampleTimes Sets the current sample's start and end times.
Update Performs a synchronous or an asynchronous update on the current sample.
CompletionStatus Retrieves the status of the current sample's latest asynchronous update. If the update isn't complete, you can force it to complete.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IStreamSample methods	Description
GetMediaStream	Retrieves a pointer to the media stream object that created the current sample.
GetSampleTimes	Retrieves the current sample's start and end times.
SetSampleTimes	Sets the current sample's start and end times.
Update	Performs a synchronous or an asynchronous update on the current sample.
CompletionStatus	Retrieves the status of the current sample's latest asynchronous update. If the update isn't complete, you can force it to complete.

IStreamSample::CompletionStatus

IStreamSample Interface

Retrieves the status of the current sample's latest asynchronous update. If the update isn't complete, you can force it to complete.

Syntax

HRESULT CompletionStatus(
  DWORD dwFlags,
  DWORD dwMilliseconds
  );

Parameters

dwFlags
[in] Value that specifies whether to forcibly complete the update. This value is a combination of one or more of the following flags.

COMPSTAT_NOUPDATEOK (0x01) Force the update to complete as soon as possible, even if the sample update isn't yet complete. If the sample is updating and you didn't set the COMPSTAT_WAIT flag, the method returns MS_S_PENDING. If the sample is waiting to be updated, this method removes it from the queue and returns MS_S_NOTUPDATED.
COMPSTAT_WAIT (0x02) Wait until the sample finishes updating before returning from this method.
COMPSTAT_ABORT (0x04) Forces the update to complete, even if it's currently updating. This leaves the sample data in an undefined state. Combine this value with the COMPSTAT_WAITFORCOMPLETION flag to ensure that the update canceled.

dwMilliseconds
[in] If the dwFlags parameter is COMPSTAT_WAIT, this value is the number of milliseconds to wait for the update to complete. Specify INFINITE to indicate that you want to wait until the sample updates before this call returns.

Return Value

Returns one of the following values.

E_ABORT The update aborted.
MS_S_ENDOFSTREAM The sample wasn't updated because it reached the end of the stream.
MS_S_NOUPDATE The update was forcibly completed; the sample was not updated by the stream.
MS_S_PENDING An asynchronous update is pending.
S_OK Success.

IStreamSample::GetMediaStream

IStreamSample Interface

Retrieves a pointer to the media stream object that created the current sample.

Syntax

HRESULT GetMediaStream(

  IMediaStream **ppMediaStream

  );

Parameters

ppMediaStream
[in] Address of a pointer to an IMediaStream interface that will point to the media stream that created the current sample.

Return Value

Returns S_OK if successful or E_POINTER if ppMediaStream is invalid.

Remarks

If successful, this method increments the reference count of the media stream specified by ppMediaStream.

IStreamSample::GetSampleTimes

IStreamSample Interface

Retrieves the current sample's start and end times. If the sample is updating, this method returns the times after the update completes.

Syntax

HRESULT GetSampleTimes(

  STREAM_TIME *pStartTime,

  STREAM_TIME *pEndTime,

  STREAM_TIME *pCurrentTime

  );

Parameters

pStartTime
[out] Pointer to a STREAM_TIME value that will contain the sample's start time.
pEndTime
[out] Pointer to a STREAM_TIME value that will contain the sample's end time.
pCurrentTime
[out] Pointer to a STREAM_TIME value that will contain the media stream's current media time.

Return Value

Returns S_OK if successful or E_POINTER if one of the parameters is invalid.

Remarks

For streams that have a clock, the start and end times will be relative to the stream's current time. If the stream doesn't have a clock, the times are media-relative and the current time will be zero.
The pCurrentTime parameter enables you to conveniently track the media stream's current time, so you don't have to call IMultiMediaStream::GetTime. Unlike GetTime, however, this method returns S_OK if the stream doesn't have a clock; GetTime returns S_FALSE. The value assigned to pCurrentTime is the same as the value produced by the following code fragment.
pSample->GetMediaStream(&pMediaStream);
pMediaStream->GetMultiMediaStream(&pMultiMediaStream);
pMediaStream->Release();
pMultiMediaStream->GetTime(&pCurrentTime);
pMultiMediaStream->Release();

IStreamSample::SetSampleTimes

IStreamSample Interface

Sets the current sample's start and end times. You can call this method prior to updating the sample.

Syntax

HRESULT SetSampleTimes(

  const STREAM_TIME *pStartTime,

  const STREAM_TIME *pEndTime

  );

Parameters

pStartTime
[in] Pointer to a STREAM_TIME value that contains the sample's new start time.
pEndTime
[in] Pointer to a STREAM_TIME value that contains the sample's new end time.

Return Value

Returns S_OK if successful or E_POINTER if one of the parameters is NULL.

Remarks

For streams that have a clock, the times must be relative to the stream's current time. If the stream doesn't have a clock, the times should be relative to the media.
This method applies only to writable streams.

IStreamSample::Update

IStreamSample Interface

Performs a synchronous or an asynchronous update on the current sample.

Syntax

HRESULT Update(
  DWORD dwFlags,
  HANDLE hEvent,
  PAPCFUNC pfnAPC,
  DWORD dwAPCData
  );

Parameters

dwFlags
[in] Flag that specifies whether the update is synchronous or asynchronous. The SSUPDATE_ASYNC flag specifies an asynchronous update, which you can set if both hEvent and pfnAPC are NULL. Use SSUPDATE_CONTINUOUS to continuously update the sample until you call the IStreamSample::CompletionStatus method.
hEvent
[in] Handle to an event that this method will trigger when the update is complete.
pfnAPC
[in] Pointer to a Win32 asynchronous procedure call (APC) function that this method will call after it completes the sample update.
dwAPCData
[in] Value that this method passes to the function specified by the pfnAPC parameter.

Return Value

Returns one of the following values.

E_ABORT The update aborted.
E_INVALIDARG One of the parameters is invalid.
E_POINTER One of the parameters is invalid.
MS_E_BUSY This sample already has a pending update.
MS_S_ENDOFSTREAM Reached the end of the stream; the sample wasn't updated.
MS_S_PENDING The asynchronous update is pending.
S_OK Success.

Remarks

This method can be used to perform a synchronous or asynchronous update of a sample. If both hEvent and pfnAPC are NULL then the update will be synchronous unless either of the SSUPDATE_ASYNC or SSUPDATE_CONTINUOUS flags is specified. When a synchronous update returns, the result of the function contains the I/O completion status.
You can't specify values for both hEvent and pfnAPC; the method will fail.
Asynchronous updates might complete before the update returns; in that case, the return value is S_OK. If you specify an event and the update returns S_OK, this method sets the event on return. If you specify an APC function and the update returns S_OK, the APC will not be queued and the function will not be called.
Asynchronous updates that don't complete prior to returning will return a value of MS_S_PENDING.
Applications that create multiple streams must read from each of them to avoid having their data blocked.

COMPSTAT_NOUPDATEOK (0x01)	Force the update to complete as soon as possible, even if the sample update isn't yet complete. If the sample is updating and you didn't set the COMPSTAT_WAIT flag, the method returns MS_S_PENDING. If the sample is waiting to be updated, this method removes it from the queue and returns MS_S_NOTUPDATED.
COMPSTAT_WAIT (0x02)	Wait until the sample finishes updating before returning from this method.
COMPSTAT_ABORT (0x04)	Forces the update to complete, even if it's currently updating. This leaves the sample data in an undefined state. Combine this value with the COMPSTAT_WAITFORCOMPLETION flag to ensure that the update canceled.

E_ABORT	The update aborted.
MS_S_ENDOFSTREAM	The sample wasn't updated because it reached the end of the stream.
MS_S_NOUPDATE	The update was forcibly completed; the sample was not updated by the stream.
MS_S_PENDING	An asynchronous update is pending.
S_OK	Success.

E_ABORT	The update aborted.
E_INVALIDARG	One of the parameters is invalid.
E_POINTER	One of the parameters is invalid.
MS_E_BUSY	This sample already has a pending update.
MS_S_ENDOFSTREAM	Reached the end of the stream; the sample wasn't updated.
MS_S_PENDING	The asynchronous update is pending.
S_OK	Success.