DirectShow COM Interfaces
`
`Page 455 of 658
`
`notify events. Applications use the IMediaEvent interface on the filter graph manager to
`retrieve these events.
`
`When to Implement
`
`There is no need to implement this method because it is implemented by the filter graph
`manager.
`
`When to Use
`
`Filters use this interface to post event notifications.
`
`Methods in Vtable Order
`!Unknown methods Description
`Queryinterface
`Returns pointers to supported interfaces.
`Add Ref
`Increments the reference count.
`Release
`Decrements the reference count.
`IMediaEventSink methods Description
`.N.o.t.if¥
`Notifies an event.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQl@[.jlj,M l!i.! 11ij
`w QIM !.l ++ Mii.HJ
`
`Topic Contents
`
`l@i§lllMM
`
`Topic Contents •@!§' 1gnw
`
`I Media EventSi n k:: Notify
`
`IMediaEventSink Interface
`
`Notifies an event.
`
`HRESULT Notify(
`long EventCode,
`long EventParam1,
`long EventParam2
`);
`
`Parameters
`
`EventCode
`[in] Identifier of the event.
`EventParam1
`[in] First event parameter.
`EventParam2
`[in] Second event parameter.
`
`846
`
`

`
`DirectShow COM Interfaces
`
`Page 456 of 658
`
`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
`
`The event is queued but not delivered to the application on this thread. For a list of notification
`codes and event parameter values, see Event Notification Codes.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Q'41[.]i!,+ 1 !1·HM Topic Contents
`
`ifflj[§ii!¥M
`
`+Q<@[.]jj,+ 111.11119 Topic Contents 1@1§11!¥+
`
`IMediaFilter Interface
`
`Multimedia components that provide time-based data expose the IMediaFilter interface. This
`interface abstracts an object that processes time-based data streams and represents a
`multimedia device (possibly implemented in software). It controls the active or running state
`of the object and the synchronization of this state with other objects in the system.
`
`This interface inherits the !Persist interface.
`
`When to Implement
`
`Methods on this interface should be implemented as part of any filter. This is typically done by
`using the base class CBaseFilter, which implements IBaseFilter and IMediaFilter.
`
`When to Use
`
`Because the IMediaFilter interface is inherited by the IBaseFilter interface, which adds other
`necessary methods required to be exported by filters, this interface is not normally used
`directly by the filter graph manager or other filters. It can, however, be of use to plug-in
`distributors. For example, the filter graph manager internally exports IMediaFilter; its plug-in
`distributor exports IMediaControl and calls the IMediaFilter methods to implement its own
`methods.
`
`Methods in Vtable Order
`
`847
`
`

`
`DirectShow COM Interfaces
`
`Page 457 of 658
`
`!Unknown methods Description
`Queryinterface
`Returns pointers to supported interfaces.
`AddRef
`Increments the reference count.
`Release
`Decrements the reference count.
`IMediaFilter
`Description
`methods
`Stop
`Pause
`Run
`GetState
`SetSyncSou rce
`
`Informs the filter to transition to the new (stopped) state.
`Informs the filter to transition to the new (paused) state.
`Informs the filter to transition to the new (running) state.
`Determines the state of the filter.
`Identifies the reference clock to which the filter should synchronize
`activity.
`Retrieves the current reference clock (or NULL if there is no clock). Passes
`a time value to synchronize independent streams.
`
`GetSyncSou rce
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`w Q<M [.] +• 111.H5
`MQi§i[.]11,M 11!.HM
`
`Topic Contents •=@• 1gnw
`
`Topic Contents
`
`l@l§il!MM
`
`I Media Filter: :GetState
`
`IMediaFilter Interface
`
`Determines the filter's state.
`
`HRESULT GetState(
`DWORD dwMilliSecsTimeout,
`FILTER_STATE *State
`);
`
`Parameters
`
`dwMilliSecsTimeout
`[in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.
`
`State
`
`[out] Returned state of the filter. States include stopped, paused, running, or
`intermediate (in the process of changing).
`
`Return Values
`
`Returns S_OK if the state is running, paused, or inactive; otherwise, returns
`VFW S STATE INTERMEDIATE if the transition is not complete (the time-out expired). The
`state returned in the latter case is the one being changed to.
`
`848
`
`

`
`DirectShow COM Interfaces
`
`Page 458 of 658
`
`Remarks
`
`Usually, renderer filters will return VFW S STATE INTERMEDIATE until they receive enough
`data to render at least one sample. In some circumstances, a filter will find that it can supply
`data on all of its output streams. This condition usually occurs because of unusual or bad data.
`An example of unusual data might be an MPEG slide show, where video frames occur
`infrequently in the data but audio is continuous. In this case, a video frame in the video
`stream might not be found until a certain spot in the audio stream. If the filter discovers that it
`cannot complete the state change (for this or any other reason), it can return
`VFW S CANT CUE.
`
`When an application calls the filter graph manager's IMediaControl: :GetState method, the filter
`graph manager calls GetState on the filter and continues to poll. If the filter graph manager
`receives VFW S CANT CUE back from the filter, it returns this value to the application from its
`IMediaControl::GetState method.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`MQi§i[.jjj,M 11!.HS
`
`Topic Contents
`
`lmli§lllMM
`
`IMediaFilter::GetSyncSource
`
`IMediaFilter Interface
`
`Retrieves the current reference clock in use by this filter.
`
`HRESULT GetSyncSource(
`IReferenceClock * * pC/ock
`);
`
`Parameters
`
`pC/ock
`[out] Pointer to a reference clock; it will be set to the IReferenceClock interface.
`
`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.
`
`849
`
`

`
`DirectShow COM Interfaces
`
`Page 459 of 658
`
`Remarks
`
`The returned interface (if it is non-NULL) will have a reference added by the IUnknown: :AddRef
`method. The calling application should release the interface by calling the IUnknown:: Release
`method when it has finished with the pointer.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQl@[.jjj,M 111.l:.!j Topic Contents
`
`l@l§i llfttiM
`
`+Qi§i[.jjj,+ 111.],.[j Topic Contents
`
`l@l§lllMM
`
`IMediaFilter::Pause
`
`IMediaFilter Interface
`
`Informs the filter to transition to the new state.
`
`HRESULT Pause(void);
`
`Return Values
`
`Returns S_OK if the transition is complete; otherwise, returns one of the following values.
`Value
`Meaning
`Error value Transition failed.
`S FALSE Transition is not complete, but no error has occurred.
`
`Remarks
`
`The state transition might not be immediate (external mechanical activity might be involved,
`for example). The state method might return before the transition has completed.
`
`© 1997 Microsoft Comoration. All rights reserved. Terms of Use.
`
`+Qi§1H+1 1 !!·Hi Topic Contents
`
`l@l§lllMM
`
`IMediaFilter::Run
`
`IMediaFilter Interface
`
`Informs the filter to transition to the new (running) state. Passes a time value to synchronize
`
`850
`
`

`
`DirectShow COM Interfaces
`
`Page 460 of 658
`
`independent streams.
`
`HRESULT Run(
`REFERENCE_TIME tStart
`);
`
`Parameters
`
`tStart
`Time value of the reference clock.
`
`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
`
`The tStart parameter is the amount to be added to the IMediaSamole time stamp to determine
`the time at which that sample should be rendered according to the reference clock. That is, it
`is the reference time at which a sample with a stream time of zero should be rendered.
`
`For example, the time value for the beginning of the stream is the time at which the first
`sample should appear. If the application restarts from paused mode in midstream, tStart is the
`amount of time paused, plus the start time.
`
`The filter graph provides this information to its filters. An application calling the filter graph
`may pass a start time of zero, in which case the filter graph calculates a time that will begin as
`soon as possible. Filter graphs accept zero to mean as soon as possible; most filters do not.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use .
`
`MQ<§i[.jjj,M 111.],.(9 Topic Contents
`
`lmli§lllMM
`
`MQi§i!!.llj,i 111.J,,[9 Topic Contents 1@1§111$8
`
`I Media Filter: :SetSyncSou rce
`
`IMediaFilter Interface
`
`851
`
`

`
`DirectShow COM Interfaces
`
`Page 461of658
`
`Identifies the reference clock to which the filter should synchronize activity.
`
`HRESULT SetSyncSource(
`IReferenceClock * pC/ock
`);
`
`Parameters
`
`pC/ock
`[in] Pointer to the IReferenceClock interface.
`
`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
`
`This method is of most importance to rendering filters and might not apply to other filters. The
`pC/ock parameter can be NULL, meaning that the filter should run as fast as possible at its
`current quality settings without any attempt to synchronize. For example, a filter graph that is
`doing compression probably runs in this mode. Each filter takes as long as it needs.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQl@[.jlj,M l!i.! 11!j Topic Contents
`l@i§lllMM
`w QIM !.l ++ Mii.HJ Topic Contents •@!§' 1gnw
`
`I Media Filter: :Stop
`
`IMediaFilter Interface
`
`Informs the filter to transition to the new state.
`
`HRESULT Stop(void);
`
`Return Values
`
`852
`
`

`
`DirectShow COM Interfaces
`
`Page 462 of 658
`
`Returns S_OK if the transition is complete; otherwise, returns one of the following values.
`Value
`Meaning
`Error value Transition failed.
`S_FALSE Transition is not complete, but no error has occurred.
`
`Remarks
`
`The state transition might not be immediate (external mechanical activity might be involved,
`for example). The state functions might return before the transition has completed.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`MQi§i[.]11,M '!!·HM Topic Contents
`
`lml!§lllMM
`
`IMediaPosition Interface
`
`Applications communicating with the filter graph can call methods on this interface to set or
`retrieve properties such as the duration of the stream, the start and stop times, the preroll
`time, the rate, and the current position. The filter graph uses these properties on seekable
`filters to control the playback of streams within the graph; where there are multiple streams,
`the filter graph sets them all to play in parallel, beginning at the same position, and will report
`the duration as being the duration of the longest stream. The REFTIME parameters used in this
`interface are double value, representing a fractional number of seconds. Internally, filters will
`store time to an accuracy of 100 nanoseconds.
`
`When to Implement
`
`The filter graph manager exposes the IMediaPosition interface if any of the filters within the
`graph are seekable (can seek to an arbitrary position in the stream). This normally means a
`seekable file source filter. Filters, such as a file source filter, will expose IMediaPosition if
`they can seek their data or if their output pin represents a seekable stream. The renderer filter
`should also expose this interface. Output pins of transform filters expose this interface to pass
`the positioning information upstream from the renderer through each intermediate filter to the
`seekable filter.
`
`Use the CMediaPosition class to help implement this interface on a filter. Use the CPosPassThru
`base class to implement this interface on output pins of transform filters used to pass media
`positioning information upstream. This is enabled by default in the pin base classes.
`
`When to Use
`
`Applications can use this interface to set or retrieve media positioning properties. Most
`commonly, an application will use the methods on this interface to play a media stream for
`some duration starting at some set position in the stream (for example, 10 seconds from the
`start).
`
`Methods in Vtable Order
`
`853
`
`

`
`DirectShow COM Interfaces
`
`Page 463 of 658
`
`!Unknown methods Description
`Queryinterface
`Returns pointers to supported interfaces.
`AddRef
`Increments the reference count.
`Release
`Decrements the reference count.
`I Dispatch
`Description
`methods
`GetTypeI nfoCou nt
`
`Determines whether there is type information available for this
`dis pi nterface.
`Retrieves the type information for this dispinterface if GetTypeinfoCount
`returned successfully.
`Converts text names of properties and methods (including arguments) to
`their corresponding DISPIDs.
`Calls a method or accesses a property in this dispinterface if given a
`DISPID and any other necessary parameters.
`Description
`
`GetTypeinfo
`
`GetI DsOfNa mes
`
`Invoke
`
`I Media Position
`methods
`get Duration
`put CurrentPosition
`get CurrentPosition
`
`Retrieves the total duration of the media stream.
`Sets the time that the media stream begins.
`Retrieves the current position in terms of the total length of the
`media stream.
`Retrieves the position within the media stream at which playback
`should stop.
`Sets the position within the media stream at which playback should
`stop.
`Retrieves the time prior to the start position that the filter graph
`begins any nonrandom access device rolling.
`Sets the time prior to the start position that the filter graph begins
`any nonrandom access device rolling.
`Sets the playback rate, relative to normal playback of the media
`stream.
`Retrieves the playback rate, relative to normal playback of the media
`stream.
`Determines if the current position can be moved forward in the media
`stream.
`Determines if the current position can be moved backward in the
`media stream.
`
`get StopTime
`
`put StopTime
`
`get PrerollTime
`
`put PrerollTime
`
`put Rate
`
`get Rate
`
`Ca nSeekForwa rd
`
`Ca nSeekBackwa rd
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`w Q<M [.] 11,1 Mii.HM Topic Contents •=@• 1gnw
`MQi§1[.]1!,i 1 !!·H¥ Topic Contents
`
`l@l§il!MM
`
`I Media Position: :Ca nSeekBackwa rd
`
`854
`
`

`
`DirectShow COM Interfaces
`
`Page 464 of 658
`
`IMediaPosition Interface
`
`Determines if the current position can be moved backward in the media stream.
`
`H RESULT CanSeekBackward (
`LONG *pCanSeekBackward
`);
`
`Parameters
`
`pCanSeekBackward
`[out] Set to OATRUE if able to seek backward; otherwise set to OAFALSE.
`
`Return Values
`
`Returns an HRESULT value.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Q'41[.]1!,+ 1 !1·HM Topic Contents
`
`ifflj[§ii!¥M
`
`I Media Position: :Ca nSeekForwa rd
`
`IMediaPosition Interface
`
`Determines if the current position can be moved forward in the media stream.
`
`HRESULT CanSeekForward(
`LONG *pCanSeekForward
`);
`
`Parameters
`
`pCanSeekForward
`[out] Set to OATRUE if able to seek forward; otherwise set to OAFALSE.
`
`Return Values
`
`Returns an HRESULT value.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qij[.jlj,M M!i.11119 Topic Contents
`
`i@i§iil¥M
`
`855
`
`

`
`DirectShow COM Interfaces
`
`Page 465 of 658
`
`I Media Position: :get_ Cu rrentPosition
`
`IMediaPosition Interface
`
`Retrieves the current position in terms of the total length of the media stream.
`
`HRESULT get_CurrentPosition(
`REFTIME* pl/Time
`);
`
`Parameters
`
`pl/Time
`[out] Reference time of the current position.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`This is the position that playback has reached. It is a value between zero and the total duration
`of the media (that is, it does not take into account the rate and start time). If the filter graph
`is paused, this is the position at which it will restart.
`
`When the filter graph is stopped or paused, this method returns the position at which playback
`will recommence. When the filter graph is running, the filter graph manager returns the
`position according to the reference clock. If an individual filter implements this, it should
`return the stream time of the sample it is processing (that is, the offset time from the
`beginning) when paused or running. If you implement this using stream time or the reference
`clock, remember to adjust the value you return for start position and playback rate so that the
`value returned is in terms of the media's total duration.
`
`After stopping or pausing, a run command causes playback to begin at the current position.
`This will be where playback stopped or paused, unless there has been an
`IMediaPosition:: put CurrentPosition call in the meantime.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`w Q<M [.] 11,1 Mii.HM Topic Contents •=@• 1gnw
`
`I Media Position: :get_Du ration
`
`IMediaPosition Interface
`
`856
`
`

`
`DirectShow COM Interfaces
`
`Page 466 of 658
`
`Retrieves the total duration of the media stream.
`
`HRESULT get_Duration(
`REFTIME* plength
`);
`
`Parameters
`
`plength
`[out] Returned length of the media stream.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`The duration assumes normal playback speed, and it is therefore unaffected by the rate.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQl@[.jlj,M l!i.! 11ij Topic Contents
`
`l@i§lllMM
`
`I Media Position: :get_Prerol ITi me
`
`IMediaPosition Interface
`
`Retrieves the time prior to the start position that any nonrandom access device should start
`rolling.
`
`HRESULT get_PrerollTime(
`REFTIME* pl/Time
`);
`
`Parameters
`
`pl/Time
`[out] Returned preroll time as a double pointer value.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`Preroll time is the time prior to the start position at which nonrandom access devices, such as
`tape players, should start rolling.
`
`857
`
`

`
`DirectShow COM Interfaces
`
`Page 467 of 658
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`MQi§i[.jjj,M 11!.HS Topic Contents
`
`lml!§I 11$8
`
`IMediaPosition::get_Rate
`
`IMediaPosition Interface
`
`Retrieves the rate of playback relative to normal playback speed.
`
`HRESULT get_Rate(
`double * pdRate
`);
`
`Parameters
`
`pdRate
`[out] Returned rate.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`A rate of 1.0 indicates normal playback speed. A rate of 0.5 indicates half speed. A rate of -1.0
`indicates normal speed in reverse.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`MQ<§i[.jjj,M Ill.HS
`
`Topic Contents
`
`lffll!§M 1gnw
`
`IMediaPosition::get_StopTime
`
`IMediaPosition Interface
`
`Retrieves the time at which the media stream stops.
`
`HRESULT get_StopTime(
`REFTIME* pl/Time
`);
`
`858
`
`

`
`DirectShow COM Interfaces
`
`Page 468 of 658
`
`Parameters
`
`pl/Time
`[out] Returned stop time as a double pointer value.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`The stop time is a position between zero and the duration of the media at which playback
`should stop.
`
`The stop position is applied before the rate and therefore is the position at typical playback
`speed.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qi§i[.]ii,+ '!!·HM Topic Contents
`
`i@l§ii!MM
`
`I Media Position:: put_ Cu rrentPosition
`
`IMediaPosition Interface
`
`Sets the time that the media stream begins.
`
`HRESULT put_CurrentPosition(
`REFTIME I/Time
`);
`
`Parameters
`
`//Time
`[in] Start time expressed as a double value.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`The start time is a position between zero and the duration of the media at which playback
`should begin when the next run command is issued.
`
`If this method is called when the filter graph manager is running, the filter graph manager will
`pause the graph, run the method, and then issue a new run command.
`
`859
`
`

`
`DirectShow COM Interfaces
`
`Page 469 of 658
`
`If called when the filter graph is paused, this method must flush existing data by using
`I Pin:: BeqinFlush and I Pin:: End Flush before pushing the new data (at the new current
`position).
`
`Setting the current position when paused or stopped causes playback to resume from the new
`start position when the run command is issued.
`
`The current position is applied before the rate and therefore is the position at typical playback
`speed.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`w Q<M [.] +• 111.H5 Topic Contents •=@• 1gnw
`
`I Media Position:: put_Prerol ITi me
`
`IMediaPosition Interface
`
`Sets the time prior to the start position that any nonrandom access device should start rolling.
`
`HRESULT put_PrerollTime(
`REFTIME //Time
`);
`
`Parameters
`
`//Time
`[in] Preroll time to be set.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`Preroll time is the time prior to the start position at which nonrandom access devices, such as
`tape players, should start rolling.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`• A Mi[.]"'' I !!·HM Topic Contents
`
`lml!§lllMM
`
`IMediaPosition::put_Rate
`
`860
`
`

`
`DirectShow COM Interfaces
`
`Page 470 of 658
`
`IMediaPosition Interface
`
`Sets the rate of playback relative to normal speed.
`
`HRESULT put_Rate(
`double dRate
`);
`
`Parameters
`
`dRate
`[in] Rate to set.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`This method allows an application to speed up or slow down playback relative to the normal
`default playback speed. A rate of 1.0 indicates normal playback speed. Specifying 2.0 causes
`playback at twice the normal rate: a video created for 10 frames per second (fps) will be
`played back at 20 fps, if resources permit. Audio streams played back at above-normal speed
`increase the pitch rather than drop samples.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`w Q<M [.] +• 111.H5
`
`Topic Contents •=@• 1gnw
`
`I Media Position:: put_StopTi me
`
`IMediaPosition Interface
`
`Sets the time at which the media stream will stop.
`
`HRESULT put_StopTime(
`REFTIME //Time
`);
`
`Parameters
`
`//Time
`[in] Stop time as a double value.
`
`Return Values
`
`861
`
`

`
`DirectShow COM Interfaces
`
`Page 471of658
`
`Returns an HRESULT value.
`
`Remarks
`
`The stop time is a position between zero and the duration of the media at which playback
`should stop.
`
`The stop position is applied before the rate and therefore is the position at typical playback
`speed.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Q'41[.]i!,+ 1 !1·HM Topic Contents
`
`ifflj[§ii!¥M
`
`IMediaPropertyBag Interface
`
`The IMediaPropertyBag interface is an interface that is exposed on filters that need to record
`copyright information. The interface inherits from the IProoertyBaq interface and supports its
`Read and Write methods for properties. It includes one additional method, EnumProperty,
`which retrieves or sets a property and value pair.
`
`You can find more information on the IMediaPropertyBag interface in the COM
`documentation of the Platform SDK.
`
`When to Implement
`
`Implement this interface when you need to expose copyright information on filters
`
`When to Use
`
`Applications should use this interface when they need to copyright the stream name of a
`multimedia file.
`
`Methods in Vtable Order
`!Unknown methods Description
`Ouerylnterface
`Retrieves pointers to supported interfaces.
`AddRef
`Increments the reference count.
`Release
`Decrements the reference count.
`IMediaPropertyBag methods Description
`En u mProperty
`Retrieves or sets a property and value pair.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Q'41H++ 1 11·!:.!M Topic Contents
`
`i@i§ll!¥+
`
`862
`
`

`
`DirectShow COM Interfaces
`
`Page 472 of 658
`
`+Qi§1[.]++ 1 !!·HM Topic Contents
`
`i@l§ii!MM
`
`IMediaPropertyBag::EnumProperty
`
`IMediaPropertyBag Interface
`
`Retrieves or sets a property and value pair.
`
`HRESULT EnumProperty(
`ULONG iProperty,
`VARIANT * pvarPropertyName,
`VARIANT* pvarPropertyValue );
`
`Parameters
`
`iProperty
`[in] Index value of the pair to get or set.
`pvarPropertyName
`[in, out] Property's name.
`pvarPropertyValue
`[in, out] Property's value.
`
`Return Values
`
`This method returns HRESULT_FROM_ WIN32(ERROR_NO_MORE_ITEMS) if the iProperty
`parameter is larger than the number of properties there are (iProperty is zero-based).
`Otherwise, it will return an HRESULT value that depends on the implementation of the
`interface.
`
`Remarks
`
`The pvarPropertyName parameter is always a string; the caller should set the variant type to
`VT_EMPTY or VT_BSTR before calling this function. The pvarPropertyValue parameter can be
`any variant; the caller should set the variant type to VT_EMPTY or what is expected.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`• ; H11·h' I !1.],,[9 Topic Contents
`
`i@l§ii!MM
`
`+Qij[.jjj,+ 111.11119 Topic Contents
`
`i@l§lllMM
`
`IMediaSample Interface
`
`863
`
`

`
`DirectShow COM Interfaces
`
`Page 473 of 658
`
`The IMediaSample interface provides shared memory buffer functionality, holds some
`properties about the data, and holds a pointer to the data itself. It is used by connected pins to
`transport media samples from one pin to another.
`
`The IMediaSamole2 interface extends the functionality of this interface to allow you to set and
`to retrieve media sample properties.
`
`When to Implement
`
`Implement this interface if you are providing an allocator (buffer) to be used for transporting
`media samples between filters. This interface is implemented by the CMediaSamole class in the
`DirectShow™ class library.
`
`When to Use
`
`Filters use methods on this interface to set properties and pass data to another filter.
`Downstream filters use methods on this interface to read the media sample's data and
`properties. Filters can modify the data in a media sample in place or can make a copy of the
`sample, modify the copy, and pass it on.
`
`Methods in Vtable Order
`!Unknown methods Description
`Oueryinterface
`Returns pointers to supported interfaces.
`AddRef
`Increments the reference count.
`Release
`Decrements the reference count.
`IMediaSample
`Description
`methods
`GetPointer
`GetSize
`GetTime
`
`Retrieves a read/write pointer to this buffer's memory.
`Returns the size, in bytes, of the buffer data area.
`Retrieves the stream times at which this sample should begin and
`finish.
`Sets the stream times at which this sample should begin and finish.
`Determines if the beginning of a sample is a synchronization point.
`Sets the synchronization point.
`Indicates a preroll property. If TRUE, this sample is for preroll only
`and should not be displayed.
`Sets the preroll property. If TRUE, this sample is for preroll only and
`should not be displayed.
`Retrieves the data length of the sample.
`Sets the data length of the sample.
`Retrieves the media type of the sample.
`Sets the media type of the sample.
`Indicates a discontinuity property. If S_OK is returned, sample is not
`contiguous with previous sample.
`Sets the discontinuity property. Set to TRUE if sample is new after a
`seek or dropped sample.
`Retrieves the media time stamps for the sample.
`
`SetTime
`IsSyncPoint
`SetSyncPoint
`IsPreroll
`
`SetPreroll
`
`GetActualDatalength
`SetActualDatalength
`GetMediaTyoe
`SetMediaTyoe
`IsDiscontinuity
`
`SetDiscontinuity
`
`GetMediaTime
`
`864
`
`

`
`DirectShow COM Interfaces
`
`Page 474 of 658
`
`SetMediaTime
`
`Sets the media time stamps for the sample.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQij[.jlj,M l!i.! 111j Topic Contents
`
`l!ftli§i l!lltiM
`
`MQ<§i[.jlj,M lh.Hj Topic Contents
`
`i@fa111¥M
`
`IMediaSample::GetActualDatalength
`
`IMediaSample Interface
`
`Retrieves the data length of the sample.
`
`HRESULT GetActualDataLength(void);
`
`Return Values
`
`Returns an HRESULT value that is the length.
`
`Remarks
`
`Note that although this is typed as returning an HRESULT value, it actually returns the length
`in bytes, not an error value.
`
`© 1997 Microsoft Comoration. All rights reserved. Terms of Use.
`
`MQ<§i[.jlj,M 11!.Hj
`
`Topic Contents
`
`i@fai11¥M
`
`IMediaSample: :GetMediaTime
`
`IMediaSample Interface
`
`Retrieves the media time stamps for this sample.
`
`HRESULT GetMediaTime(
`LONGLONG * pTimeStart,
`LONGLONG * pTimeEnd
`);
`
`Parameters
`
`865
`
`

`
`DirectShow COM Interfaces
`
`Page 475 of 658
`
`pTimeStart
`[out] Retrieved beginning media time.
`pTimeEnd
`[out] Retrieved ending media time.
`
`Return Values
`
`Returns NOERROR if the sample contains valid time stamps. Returns
`VFW E MEDIA TIME NOT SET if the time has not been set in the sample.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`w Q<M [.] +• 811.HM
`
`Topic Contents
`
`8ml!§M 8gnw
`
`IMediaSample: :GetMediaType
`
`IMediaSample Interface
`
`Retrieves the media type of the IMediaSample object.
`
`HRESULT GetMediaType(
`AM_MEDIA_TYPE ** ppMediaType
`);
`
`Parameters
`
`ppMediaType
`[in] Pointer to a pointer to the retrieved media type.
`
`Return Values
`
`Returns an HRESULT value. When a sample is received and there is no format change, this
`method returns S FALSE.
`
`Remarks
`
`This method allows for limited in-band format changes. Free the format block with
`FreeMediaType, and then free the entire media type with the Microsoft® Win32®
`CoTaskMemFree function.
`
`© 1997 Microsoft Corporation . All rights reserved . Terms of Use.
`
`w Q<M [.] +• 811.HM Topic Contents 8ml!§M 8gnw
`
`866
`
`

`
`DirectShow COM Interfaces
`
`Page 476 of 658
`
`IMediaSample: :GetPointer
`
`IMediaSample Interface
`
`Retrieves a read/write pointer to this buffer's memory.
`
`HRESULT GetPointer(
`BYTE * * ppBuffer
`);
`
`Parameters
`
`ppBuffer
`[out] Retrieved pointer to the buffer.
`
`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.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`MQi§i[.jjj,M 11!.HS Topic Contents
`
`lml!§lllMM
`
`MQl§i[.jjj,M '!!·HM Topic Contents
`
`i@i§ill@iM
`
`IMediaSample: :GetSize
`
`IMediaSample Interface
`
`Returns the size, in bytes, of the buffer data area.
`
`HRESULT GetSize(void);
`
`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:
`
`867
`
`

`
`DirectShow COM Interfaces
`
`Page 477 of 658
`
`Meaning
`Value
`Failure.
`E FAIL
`Null pointer argument.
`E_ POINTER
`Invalid argument.
`E INVALIDARG
`Method isn't supported.
`E_ NOTIMPL
`S_OK or NOERROR Success.
`
`Remarks
`
`Note that although this is typed as returning an HRESULT value, it actually returns the length
`in bytes, not an error value.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQi@[.jlj,M l!i.! 111M Topic Contents
`
`l@IJll!MM
`
`+Qi§i[.]11,+ 1!1·HM Topic Contents
`
`l@i§il!MM
`
`IMediaSample: :GetTime
`
`IMediaSample Interface
`
`Retrieves the stream times at which this sample should begin and finish.
`
`HRESULT GetTime(
`REFERENCE_ TIME * pTimeStart,
`REFERENCE_ TIME* pTimeEnd
`);
`
`Parameters
`
`pTimeStart
`[out] Retrieved beginning stream time.
`pTimeEnd
`[out] Retrieved ending stream time.
`
`Return Values
`
`Returns NOERROR if the sample contains valid time stamps. Returns
`VFW E MEDIA TIME NOT SET if the time has not been set in the sample.
`
`© 1997 Microsoft Comoration. All rights reserved. Terms of Use.
`
`+Qi§i[.]lj,+ 11!.HM Topic Contents
`
`l@i§il!MM
`
`868
`
`

`
`DirectShow COM Interfaces
`
`Page 478 of 658
`
`IMediaSample::lsDiscontinuity
`
`IMediaSample Interface
`
`Determines if there is discontinuity in the data stream.
`
`HRESULT IsDiscontinuity(void);
`
`Return Values
`
`Returns S_OK if the sample is a discontinuous sample, or S_FALSE if not; otherwise, returns
`an HRESULT error value.
`
`Remarks
`
`Discontinuity occurs when a source filter seeks to a different place in the stream or when a
`filter drops samples for quality control.
`
`Note that while calling Se