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.
When to Implement
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.
When to Use
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. |
Retrieves the status of the current sample's latest asynchronous update. If the update isn't complete, you can force it to complete.
HRESULT CompletionStatus(
DWORD dwFlags,
DWORD dwMilliseconds
)
Value | Meaning |
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. |
Returns one of the following values.
Value | Meaning |
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. |
Retrieves a pointer to the media stream object that created the current sample.
HRESULT GetMediaStream(
IMediaStream** ppMediaStream
)
Returns S_OK if successful or E_POINTER if ppMediaStream is invalid.
If successful, this method increments the reference count of the media stream specified by ppMediaStream.
Retrieves the current sample's start and end times. If the sample is updating, this method returns the times after the update completes.
HRESULT GetSampleTimes(
STREAM_TIME* pStartTime,
STREAM_TIME* pEndTime,
STREAM_TIME* pCurrentTime
)
Returns S_OK if successful or E_POINTER if one of the parameters is invalid.
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 developers 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();
Sets the current sample's start and end times. You can call this method prior to updating the sample.
HRESULT SetSampleTimes(
const STREAM_TIME* pStartTime,
const STREAM_TIME* pEndTime
)
Returns S_OK if successful or E_POINTER if one of the parameters is NULL.
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 only applies to writable streams.
Performs a synchronous or an asynchronous update on the current sample.
HRESULT Update(
DWORD dwFlags,
HANDLE hEvent,
PAPCFUNC pfnAPC,
DWORD dwAPCData
)
Returns one of the following values.
Value | Meaning |
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. |
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.