IStreamSample::Update method (mmstream.h)

Article
4/26/2023

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

Note This interface is deprecated. New applications should not use it.

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

Syntax

HRESULT Update(
  [in] DWORD     dwFlags,
  [in] HANDLE    hEvent,
  [in] PAPCFUNC  pfnAPC,
  [in] DWORD_PTR dwAPCData
);

Parameters

[in] dwFlags

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.

[in] hEvent

Handle to an event that this method will trigger when the update is complete.

[in] pfnAPC

Pointer to a Win32 asynchronous procedure call (APC) function that this method will call after it completes the sample update.

[in] dwAPCData

Value that this method passes to the function specified by the pfnAPC parameter.

Return value

Returns one of the following values.

Return code	Description
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.
VFW_E_NOT_COMMITTED	Cannot allocate a sample because the allocator is not committed.

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.

If an application creates multiple streams, it must perform an asynchronous update on each stream. Call WaitForMultipleObjects to wait for each stream update to complete, before making the next update. Otherwise, the application might block.

Requirements


Target Platform	Windows
Header	mmstream.h