DirectShow COM Interfaces
`
`Page 575 of 658
`
`HRESULT get_FramesDrawn(
`int *pcFramesDrawn
`);
`
`Parameters
`
`pcFramesDrawn
`Number of frames drawn since streaming started.
`
`Return Values
`
`Returns an HRESULT value.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQi@[.jjj,M l!i.! 111j
`
`Topic Contents
`
`l@IJll!MM
`
`IQ ua I Prop:: get_Fra mesDroppedI n Renderer
`
`IQualProp Interface
`
`Retrieves the number of frames dropped by the renderer.
`
`HRESULT get_FramesDroppedinRenderer(
`int *pcFrames
`);
`
`Parameters
`
`pcFrames
`Number of frames dropped by the renderer.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`The property page uses this method to retrieve data from the renderer.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQl@[.jjj,M 111.l:.!j Topic Contents
`
`l@i§il!MM
`
`966
`
`

`
`DirectShow COM Interfaces
`
`Page 576 of 658
`
`IQualProp: :get_litter
`
`IQualProp Interface
`
`Expresses the average time between successive frames delivered to the video renderer.
`
`HRESULT get_litter(
`int *piJitter
`);
`
`Parameters
`
`piJitter
`Standard deviation, in milliseconds, of the interframe time.
`
`Return Values
`
`Returns an HRESULT value.
`
`© 1997 Microsoft Corooration . All rights reserved. Terms of Use.
`
`MQ<§i[.jjj,M MB.HS Topic Contents
`
`i@faii!MM
`
`IQueueCommand Interface
`
`The IQueueCommand interface provides a way to defer commands and property changes.
`The deferred command mechanism allows filters themselves to handle deferred commands.
`When they do not, the filter graph manager queues the command until the requested time and
`then calls the method on the filter (this would result in coarse rather than accurate
`synchronization). Note that a filter that does handle deferred commands must make them
`apply to data appearing at that time. Thus, a contrast filter asked to change the contrast at
`time x must ensure that it applies the change when processing data time-stamped to be
`rendered at time x; these samples will be processed by the filter somewhat before time x.
`
`The IQueueCommand interface provides two methods, InvokeAtStreamTime, which queues
`commands at stream time, and InvokeAtPresentationTime, which queues commands at
`presentation time. Both return an IDeferredCommand interface to the queued command, by
`which the application can cancel the command, set a new presentation time for it, or get back
`an estimate of the likelihood of the filter graph manager being able to run the command on
`time.
`
`Both presentation time and stream time commands will run once, and then be removed from
`the queue. Both the queue and the application will hold a reference count on the object
`(represented to the application by the IDeferredCommand interface), and the object will not be
`destroyed until both are released. Similarly, calling IUnknown:: Release on the
`IDeferredCommand interface is not sufficient to cancel the command, because the queue
`also holds a reference count.
`
`967
`
`

`
`DirectShow COM Interfaces
`
`Page 577 of 658
`
`Rather than add optional stream time and presentation time constraints to every method and
`property on every control interface, the application uses !Dispatch to provide a single interface
`where these time parameters can be specified. IQueueCommand provides
`InvokeAtStreamTime and InvokeAtPresentationTime methods that are similar in style to the
`!Dispatch:: Invoke method.
`
`Filters can implement IQueueCommand themselves. In this case, they parse the command
`and queue it for action when the relevant samples arrive or when the reference clock reaches
`the correct point, as appropriate. For filters that do not support this, the filter graph manager
`will run the command when the reference clock reaches the specified time, regardless of the
`samples being processed at the filter.
`
`When to Implement
`
`This method is implemented by the filter graph manager to allow queuing of deferred
`commands.
`
`When to Use
`
`Applications can use this interface, along with the IDeferredCommand interface, to queue
`commands for deferred processing.
`
`Methods in Vtable Order
`!Unknown methods Description
`Queryinterface
`Returns pointers to supported interfaces.
`AddRef
`Increments the reference count.
`Release
`Decrements the reference count.
`IQueueCommand
`Description
`methods
`InvokeAtStreamTime
`
`Queues a method or property change for execution at a specified
`stream time (that is, presentation time relative to the current
`stream time offset).
`InvokeAtPresentationTime Queues a method or property change for execution at a specified
`presentation time.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+;<§1[.]lj,i '!!·!:.!¥ Topic Contents i@i§ll!¥+
`
`+Qi@[.]+• 111.1,.19 Topic Contents
`
`i@i§i i!fttiM
`
`IQueueCommand::InvokeAtPresentationTime
`
`IQueueCommand Interface
`
`968
`
`

`
`DirectShow COM Interfaces
`
`Page 578 of 658
`
`Queues a method or property change for execution at a specified presentation time.
`
`HRESULT InvokeAtPresentationTime(
`IDeferredCommand * pCmd,
`REFTIME time,
`GUID* iid,
`long dispidMember,
`short wF/ags,
`long cArgs,
`VARIANT *pDispParams,
`VARIANT *pvarResult,
`short *puArgErr
`);
`
`Parameters
`
`pCmd
`[out] Pointer to the place to return an interface on the deferred command if it is
`successfully created.
`
`time
`
`iid
`
`[in] Time at which to invoke the command.
`
`[in] Interface to be called.
`dispidMember
`[in] Method or property to call on the interface.
`wF/ags
`[in] Method or property flag.
`cArgs
`[in] Number of arguments on pDispParams.
`pDispParams
`[in] Parameters to this method.
`pvarResult
`[in,out] Return value.
`puArgErr
`[out] Index to the arguments in error.
`
`Return Values
`
`Returns an HRESULT value.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`MQi§i[.jjj,M 11!.HS
`
`Topic Contents
`
`lmli§I 11$8
`
`MQl§i[.jjj,M 111.],.[5
`
`Topic Contents
`
`'ffl!'+* •um•
`
`IQueueCom ma nd: :I nvokeAtStrea mTi me
`
`969
`
`

`
`DirectShow COM Interfaces
`
`Page 579 of 658
`
`IQueueCommand Interface
`
`Queues a method or property change for execution at a specified stream time (that is,
`presentation time relative to the current stream time offset).
`
`HRESULT InvokeAtStreamTime(
`IDeferredCommand * * pCmd,
`REFTIME time,
`GUID *iid,
`long dispidMember,
`short wFlags,
`long cArgs,
`VARIANT *pDispParams,
`VARIANT *pvarResult,
`short *puArgErr
`);
`
`Parameters
`
`pCmd
`[out] Pointer to the place to return an interface on the deferred command if it is
`successfully created.
`
`time
`
`iid
`
`[in] Time at which to invoke the command.
`
`[in] Interface to be called.
`dispidMember
`[in] Method or property to call on the interface.
`wF/ags
`[in] Method or property flag.
`cArgs
`[in] Number of arguments in pDispParams.
`pDispParams
`[in] Para meters to th is method.
`pvarResult
`[in, out] Return value of the called method.
`puArgErr
`[out] Index to the arguments in error.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`Run this command to affect the presentation that occurs after the specified stream time. The
`interface IID is an interface that can be obtained by calling IUnknown: :Queryinterface on this
`same IQueueCommand interface.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQi@[.ji!:M l!i.! 11ij Topic Contents
`
`l@i§i 11111+
`
`970
`
`

`
`DirectShow COM Interfaces
`
`Page 580 of 658
`
`+Qi§1[.]++ 1 !!·HM Topic Contents
`
`i@l§ii!MM
`
`IReferenceClock Interface
`
`The IReferenceClock interface represents a system reference clock to be implemented by a
`filter in the filter graph and used by other filters.
`
`When to Implement
`
`Implement this interface if you are writing a filter that generates a system reference clock.
`Typically, this applies to audio renderer filters because audio sound boards usually contain a
`reference clock. Use the CBaseReferenceClock class to implement this interface.
`
`When to Use
`
`Use this interface on any filter to obtain reference clock notifications for a duration of elapsed
`time (both singular and repetitive), or to retrieve the current time.
`
`Methods in Vtable Order
`!Unknown methods Description
`Returns pointers to supported interfaces.
`Queryinterface
`AddRef
`Increments the reference count.
`Release
`Decrements the reference count.
`Description
`IReferenceClock
`methods
`GetTime
`AdviseTime
`AdvisePeriod ic
`
`Unadvise
`
`Gets the current time.
`Requests an asynchronous notification that a duration has elapsed.
`Requests an asynchronous, periodic notification that a duration
`has elapsed.
`Cancels a request for notification.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`+ Q i§i [.] jj,+ +!!·HM Topic Contents Mttfjl§ii!MM
`
`HQ i§i [.] jj,M I 11.],.[M Topic Contents i@l§ii/¥+
`
`IReferenceClock: :Advise Periodic
`
`IReferenceClock Interface
`
`971
`
`

`
`DirectShow COM Interfaces
`
`Page 581 of 658
`
`Requests an asynchronous, periodic notification that a duration has elapsed.
`
`HRESULT AdvisePeriodic(
`REFERENCE_ TIME rtStartTime,
`REFERENCE_ TIME rtPeriodTime,
`HSEMAPHORE hSemaphore,
`DWORD * pdwAdviseCookie
`);
`
`Parameters
`
`rtStartTime
`[in] Time the notification should begin.
`rtPeriodTime
`[in] Duration between notifications.
`hSemaphore
`[in] Handle of a semaphore through which to advise.
`pdwAdviseCookie
`[out] Used to identify this call to AdvisePeriodic in the future; for example, to cancel it.
`
`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
`
`When the time indicated by rtStartTime is reached, the semaphore whose handle is set as
`hSemaphore will be released. Thereafter, the semaphore will be released repetitively with a
`period of rtPeriodTime.
`
`See Also
`
`I ReferenceC lock: : U nadvise, CBaseReferenceClock: : AdvisePeriod ic
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+;<§1[.]lj,i 111.],.[9 Topic Contents
`
`lttfjl§M IU@+
`
`MQl@[.jlj,M 111.l:.19 Topic Contents
`
`l@i§lllMM
`
`972
`
`

`
`DirectShow COM Interfaces
`
`Page 582 of 658
`
`IReferenceClock: :AdviseTi me
`
`IReferenceClock Interface
`
`Requests an asynchronous notification that a duration has elapsed.
`
`HRESULT AdviseTime(
`REFERENCE_ TIME rtBaseTime,
`REFERENCE_ TIME rtStreamTime,
`HEVENT hEvent,
`DWORD * pdwAdviseCookie
`);
`
`Parameters
`
`rtBaseTime
`[in] Base reference time.
`rtStreamTime
`[in] Stream offset time.
`hEvent
`[in] Handle of an event through which to advise.
`pdwAdviseCookie
`[out] Destination of the token.
`
`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
`
`When the time rtBaseTime+rtStreamTime is reached, the event whose handle is hEvent will be
`set. If the time has already passed, the event will be set immediately.
`
`See Also
`
`IReferenceClock:: Unadvise
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Q'41[.]1!,+ 1 !1·HM Topic Contents i@l§ii!¥M
`
`+Q<@[.]ij,+ 111.11119 Topic Contents 1@1§11!¥+
`
`973
`
`

`
`DirectShow COM Interfaces
`
`Page 583 of 658
`
`IReferenceClock: :GetTime
`
`IReferenceClock Interface
`
`Retrieves the current time. REFERENCE_TIME is a LONGLONG type and loosely represents
`the number of 100-nanosecond units that have elapsed since some fixed start time. See
`Characteristics of a Reference Clock for other requirements on the reference clock.
`
`HRESULT GetTime(
`REFERENCE_ TIME* pTime
`);
`
`Parameters
`
`pTime
`[out] Current time.
`
`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.
`
`+Q'41[.]1!,+ 1 !1·HM Topic Contents
`
`ifflj[§ii!¥M
`
`+Q<@[.]ij,+ 111.11119 Topic Contents 1@1§11!¥+
`
`IReferenceClock:: U nadvise
`
`IReferenceClock Interface
`
`Cancels a request for notification.
`
`HRESULT Unadvise(
`
`974
`
`

`
`DirectShow COM Interfaces
`
`Page 584 of 658
`
`DWORD dwAdviseCookie
`);
`
`Parameters
`
`dwAdviseCookie
`[in] Request to cancel.
`
`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.
`
`See Also
`
`IReferenceClock: :AdviseTime, IReferenceClock: :AdvisePeriodic
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`MQi§i[.]11,M '!!·HM Topic Contents
`• QIM [.] +• I !!·HM Topic Contents l@i§il/¥8
`
`lml!§lll¥M
`
`IRegFilterlnfo Interface
`
`The IRegFilterinfo interface provides access to filters in the registry and allows a registered
`filter to be added to the filter graph.
`
`When to Implement
`
`IRegFilterinfo is implemented by the filter graph manager for use by Automation client
`applications, such as Microsoft® Visual Basic®.
`
`When to Use
`
`Use this interface when it is exposed by an Automation client to query the names of filters in a
`collection of registry filters, and to add specific filters to the filter graph. A collection of
`IRegFilterlnfo interfaces is returned by the IMediaControl: :get RegFilterCollection method.
`
`Methods in Vtable Order
`
`975
`
`

`
`DirectShow COM Interfaces
`
`Page 585 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
`GetTypeinfoCount 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.
`IRegFilterinfo methods Description
`get Name
`Retrieves the name of the filter.
`Filter
`Creates an instance of this filter and adds it to the filter graph.
`
`GetTypeinfo
`
`GetIDsOfNames
`
`Invoke
`
`© 1997 Microsoft Corooration . All rights reserved. Terms of Use.
`
`MQ<§i[.jjj,M MB.HS
`
`Topic Contents
`
`i@fa111¥M
`
`8 4'41[.]1!,M 1!1·H¥
`
`Topic Contents
`
`i@fai11¥M
`
`IRegFilterlnfo:: Filter
`
`IRegFilterinfo Interface
`
`Creates an instance of this filter and adds it to the filter graph.
`
`HRESULT Filter(
`!Dispatch **ppUnk
`);
`
`Parameters
`
`ppUnk
`[out] IFilterinfo interface for the added filter.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`976
`
`

`
`DirectShow COM Interfaces
`
`Page 586 of 658
`
`Use the IReqFilterinfo: :get Name method (Name property in Visual Basic) to find the filter by
`comparing names in a collection of IReqFilterinfo interfaces.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+;<§1[.]jj,i '!!·!:.!¥
`
`Topic Contents
`
`'ffl!'+* •um•
`
`IRegFilterlnfo: :get_Name
`
`IRegFilterinfo Interface
`
`Retrieves the name of the filter.
`
`HRESULT get_Name(
`BSTR * strName
`);
`
`Parameters
`
`strName
`[out, retval] Name of the filter.
`
`Return Values
`
`Returns an HRESULT value.
`
`Remarks
`
`Typically, a Visual Basic application will use the For Each ... Next syntax on a collection of
`IReqFilterinfo interfaces and check the name of each filter in the registry until it finds the one
`it wants to add. It can then add the filter to the filter graph by using the IReqFilterinfo:: Filter
`method.
`
`© 1997 Microsoft Corooration . All rights reserved. Terms of Use.
`
`+;<§1[.]jj,M +II.HM Topic Contents Mttfjl§lllMM
`
`IResourceConsumer Interface
`
`The IResourceConsumer interface implements a resource consumer that requests resources
`from a resource manager that supports the IResourceManager interface.
`
`When to Implement
`
`977
`
`

`
`DirectShow COM Interfaces
`
`Page 587 of 658
`
`Implement this interface on any object that requests resources from a resource manager. (The
`filter graph manager acts as a resource manager for Microsoft® DirectShow™ .) After
`implementing this interface, the object can register resources that it wants to use. It passes a
`pointer to this interface when it does this so that the resource manager can use methods on
`this interface to inform the object that a resource is available, or to release a resource that it is
`using.
`
`When to Use
`
`A resource manager that implements the IResourceManager interface calls methods on this
`interface.
`
`Methods in Vtable Order
`!Unknown methods Description
`Queryinterface
`Returns pointers to supported interfaces.
`AddRef
`Increments the reference count.
`Release
`Decrements the reference count.
`IResourceManager
`Description
`methods
`AcquireResource
`
`ReleaseResource
`
`Notifies the resource consumer that a resource might be
`acquired.
`Requests the resource consumer to release the specified
`resource.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+QH"·h' 111.q9 Topic Contents
`
`1@1§111¥+
`
`+Qij[.jlj,M 111.11119 Topic Contents
`
`1@1§111¥+
`
`IResourceConsumer::AcquireResource
`
`IResourceConsumer Interface
`
`Notifies the resource consumer that a resource might be acquired.
`
`HRESULT AcquireResource(
`LONG idResource
`);
`
`Parameters
`
`idResource
`[in] Resource identifier of the resource to be acquired.
`
`978
`
`

`
`DirectShow COM Interfaces
`
`Page 588 of 658
`
`Return Values
`
`Returns one of the following values.
`Value
`Meaning
`S_OK
`Consumer has successfully acquired the resource.
`S FALSE
`Consumer has not acquired the resource but will use
`IResourceManager:: NotifyAcguire when it does.
`VFW S RESOURCE NOT NEEDED Consumer no longer needs the resource.
`Error Value
`Consumer tried to acquire the resource but failed.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`•;1;1.111,; 11!.i::ii Topic Contents
`
`l@i§I 11111+
`
`MQ<§i[.jjj,M 111.Hj Topic Contents
`
`1@1§111¥+
`
`IResou rceConsu mer:: ReleaseResou rce
`
`IResourceConsumer Interface
`
`Requests the resource consumer to release the specified resource.
`
`HRESULT ReleaseResource(
`LONG idResource
`);
`
`Parameters
`
`idResource
`[in] Resource identifier to be released.
`
`Return Values
`
`Returns S_OK if the consumer has released it and requires it again when it becomes available,
`or S_FALSE if the consumer has not released it but will use IResourceManaqer:: NotifyRelease
`when it does.
`
`© 1997 Microsoft Comoration. All rights reserved. Terms of Use.
`
`MQ<§i[.jjj,M 11!.Hj Topic Contents 1@1§111¥+
`
`IResourceManager Interface
`
`979
`
`

`
`DirectShow COM Interfaces
`
`Page 589 of 658
`
`The IResourceManager interface implements a resource manager to resolve contentions for
`named resources.
`
`When to Implement
`
`Implement this interface on any object that performs the services of a resource manager. The
`filter graph manager acts as a resource manager for Microsoft® DirectShow™ and delegates to
`any existing system-wide resource manager. The filter graph manager implements the
`methods on this interface.
`
`When to Use
`
`Use this interface if your object requires resources that other objects are likely to use. The
`wave renderer uses this interface to resolve contentions for the wave-output device to enable
`sound to follow focus.
`
`An object can use the resource manager supporting this interface to resolve possible
`contention between existing resources. This is carried out by registering the resource with the
`interface and then requesting it from this interface whenever needed.
`
`Use this interface if your object detects user focus changes that might affect resource usage.
`Notifying the resource manager of a change of focus will cause the resource manager to switch
`contended resources to the objects that have the focus of the user.
`
`Methods in Vtable Order
`!Unknown methods Description
`Querylnterface
`Returns pointers to supported interfaces.
`AddRef
`Increments the reference count.
`Decrements the reference count.
`Release
`IResourceManager
`Description
`methods
`Register
`RegisterGroup
`Reg uest Resource
`NotifyAcg u ire
`
`Registers a single named resource with the resource manager.
`Registers a named resource group with the resource manager.
`Requests the use of a given registered resource.
`Notifies the resource manager that an attempt to acquire a resource
`has completed.
`Notifies the resource manager that a resource consumer has
`released a resource.
`Cancels the request for a resource.
`Notifies the resource manager that a specified object has been
`given the focus of the user.
`Sets the focus object to NULL in the resource manager if the object
`of the current focus object is the one specified in this method.
`
`Notify Release
`
`Cancel Request
`SetFocus
`
`ReleaseFocus
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQi@[.jlj,M M!i.!111j Topic Contents
`
`l@i§il!MM
`
`980
`
`

`
`DirectShow COM Interfaces
`
`Page 590 of 658
`
`+Qi§1[.]++ 1 !!·HM Topic Contents
`
`i@l§ii!MM
`
`IResou rceMa nager: :Ca nee I Request
`
`IResourceManager Interface
`
`Cancels the request for a resource.
`
`HRESULT CancelRequest(
`LONG idResource,
`IResourceConsumer* pConsumer
`);
`
`Parameters
`
`idResource
`[in] Resource identifier of a pending request.
`pConsumer
`[in] IResourceConsumer interface that made the request.
`
`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 should be called when the IResourceConsumer object that requested the resource
`has not received it and no longer requires it. If it has already received the resource, it should
`use the IResourceManaqer:: NotifyRelease method.
`
`© 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
`
`981
`
`

`
`DirectShow COM Interfaces
`
`Page 591 of 658
`
`IResourceManager::NotifyAcquire
`
`IResourceManager Interface
`
`Notifies the resource manager that an attempt to acquire a resource has completed.
`
`HRESULT NotifyAcquire(
`LONG idResource,
`IResourceConsumer* pConsumer,
`HRESULT hr
`);
`
`Parameters
`
`idResource
`[in] Token for the registered resource.
`pConsumer
`[in] IResourceConsumer interface of the object requesting the resource.
`
`hr
`
`[in] Success of the acquisition; S_OK if the resource was acquired, or an error value if
`not.
`
`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
`
`Use this method after an IResourceConsumer: :AcquireResource method returns an S FALSE
`value, indicating that the acquisition will be asynchronous (that is, handled by a callback
`mechanism). If the hr parameter is S_OK, the resource manager will assume that the resource
`is now held by the caller. If the hr parameter is anything other than S_OK, the resource
`manager will assume that the attempt to acquire the resource failed and will reassign the
`resource elsewhere.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+Qi§1[.]I!:+ 1 !!·HM Topic Contents
`
`i@l§ii!MM
`
`MQi@[.jlj,M M!i.11119 Topic Contents
`
`i@l§i 11111+
`
`982
`
`

`
`DirectShow COM Interfaces
`
`Page 592 of 658
`
`IResou rceMa nager:: NotifyRelease
`
`IResourceManaqer Interface
`
`Notifies the resource manager that IResourceConsumer has released a resource.
`
`HRESULT NotifyRelease LONG idResource,
`
`IResourceConsumer* pConsumer,
`BOOL bStil/Want
`);
`
`Parameters
`
`idResource
`[in] Resource token.
`pConsumer
`[in] Object releasing the resource.
`bStil/Want
`[in] Flag specifying whether the resource is still required or not.
`
`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
`
`Use this method in response to an IResourceConsumer:: ReleaseResource method, or when you
`have finished using the resource. The bStil/Want parameter should be set TRUE if you still
`want the resource when it is next available, or FALSE if you no longer want the resource.
`
`© 1997 Microsoft Corporation . All rights reserved. Terms of Use.
`
`MQi§i[.jjj,M 11!.HS Topic Contents
`
`lmli§I 11$8
`
`MQl§i[.jjj,M 111.],.[5 Topic Contents
`
`'ffl!'+* •um•
`
`983
`
`

`
`DirectShow COM Interfaces
`
`Page 593 of 658
`
`IResourceManager::Register
`
`IResourceManager Interface
`
`Registers a single named resource with the resource manager.
`
`HRESULT Register(
`LPCWSTR pName,
`LONG cResource,
`LONG* p/Token
`);
`
`Parameters
`
`pName
`[in] Named resource.
`cResource
`[in] Number of resources.
`p/Token
`[out] Returned token identifying the resource to be used in additional calls.
`
`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 registers a named resource, which can contain a number of resources, and
`returns a token to be used when requesting this resource. It is not an error if the resource is
`already registered; if the number in the cResource parameter is less than what is already
`registered, resources will be deallocated to the new count. To unregister the resource, pass a
`count of zero in cResource.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`+;<§1[.]jj,i 111.],.[9 Topic Contents
`
`lttfjl§M IU@+
`
`MQl@[.jjj,M 111.l:.19 Topic Contents
`
`l@i§lllMM
`
`984
`
`

`
`DirectShow COM Interfaces
`
`Page 594 of 658
`
`IResourceManager::RegisterGroup
`
`IResourceManager Interface
`
`Registers a named resource group with the resource manager.
`
`HRESULT RegisterGroup(
`LPCWSTR pName,
`LONG cResource,
`LONG* pa/Tokens,
`LONG* p/Token
`);
`
`Parameters
`
`pName
`[in] Named resource group.
`cResource
`[in] Number of resources in the group.
`pa/Tokens
`[in, size_is(cResource)] Array of resources in the group.
`p/Token
`[out] Returned group resource identifier.
`
`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.
`
`MQl@[.jjj,M 11!.l:.ij Topic Contents
`
`l@i§lllMM
`
`+Qi§i[.jjj,+ 111.],.[j Topic Contents
`
`l@i§lllMM
`
`IResou rceMa nager:: Releasef ocus
`
`IResourceManaqer Interface
`
`985
`
`

`
`DirectShow COM Interfaces
`
`Page 595 of 658
`
`Sets the focus object to NULL in the resource manager if the current focus object is the one
`specified in this method.
`
`HRESULT Releasefocus(
`!Unknown* pFocusObject
`);
`
`Parameters
`
`pFocusObject
`[in] Focus object.
`
`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
`
`Use this method when the object of focus is about to be destroyed to ensure that the focus is
`not still being referenced.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQl@[.jjj,M 11!.l:.ij Topic Contents
`
`l@i§lllMM
`
`+Qi§i[.jjj,+ 111.],.[j Topic Contents
`
`l@bll!MM
`
`IResourceManager::RequestResource
`
`IResourceManaqer Interface
`
`Requests the use of a given registered resource.
`
`HRESULT RequestResource(
`LONG idResource,
`!Unknown* pFocusObject,
`IResourceConsumer* pConsumer
`);
`
`986
`
`

`
`DirectShow COM Interfaces
`
`Page 596 of 658
`
`Parameters
`
`idResource
`[in] Resource token retrieved when the resource was registered.
`pFocusObject
`[in] IUnknown interface of a focus object associated with a request (normally the filter's
`!Unknown interface).
`pConsumer
`[in] IResourceConsumer interface on the object requesting the resource.
`
`Return Values
`
`Returns an HRESULT value. Returns S_OK if the requested resource is returned, or S_FALSE if
`the resource is not available, in which case the resource manager will call the requesting object
`back when the resource becomes available. Any other return is an error.
`
`Remarks
`
`When there is more than one request for the resource, the resource manager will decide the
`priority by using the object of focus passed with each request and comparing it to the object of
`focus passed in the most recent IResourceManager: :SetFocus method.
`
`Requests will be filled in the following order of priority.
`
`1. Requests made with exactly the same object of focus as the last SetFocus method.
`2. Requests whose object of focus shares a common source filter.
`3. Requests whose object of focus shares a common filter graph.
`4. Requests in the same process as the focus.
`
`While checking this priority, the resource manager will use Queryinterface on the focus object
`for IID_IFilter. If found, the resource manager will use IBaseFilter methods to check the filter
`graph and look for common source filters with the current focus object.
`
`A filter should pass the IUnknown interface of the filter in the pFocusObject parameter. The
`filter graph manager matches filters to the filter graph and will attempt to trace filters to
`common source filters when checking objects of focus.
`
`The focus object must be valid for the entire lifetime of the request - until either the
`IResourceManager: :CancelReguest method is called, or the IResourceManager:: NotifyRelease
`method is called with the bStil/Want parameter set to FALSE.
`
`© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
`
`MQi@[.jlj,M l!i.! 111j Topic Contents
`
`l@IJll!MM
`
`+Qi§i!.ll!,1 1 1!·!:.!j Topic Contents
`
`l@i§il!MM
`
`IResou rceMa nager: :Setf ocus
`
`987
`
`

`
`DirectShow COM Interfaces
`
`Page 597 of 658
`
`!ResourceManager Interface
`
`Notifies the resource manager that a specified object has been given the focus of the user.
`
`HRESULT Setfocus(
`!Unknown* pFocusObject
`);
`
`Parameters
`
`pFocusObject
`[in] Object that has been given the focus of the user.
`
`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
`
`In DirectShow, the object given the user's focus is typically a video renderer whose window
`has received the focus. The resource manager gives priority to requests for resources in the
`following order.
`
`1. Requests made with the focus object specified in the pFocusObject parameter.
`2. Requests whose focus object shares a common source filter.
`3. Requests whose focus object shares a common filter graph.
`4. Requests in the same process as the focus.
`
`Once a focus has been set, the resource manager must maintain a focus object until
`ReleaseFocus is called. That is, after calling this method, you must use Releasefocus before
`the !Unknown interface of the focus object becomes invalid, unless you can guarantee that
`Setfocus is called by a different object in the meantime. No reference count is held on the
`focus object.
`
`The resource manager will hold this pointer until replaced or canceled, and will use it to resolve
`resource contention. It will use Ouerylnterface for the !BaseFilter interface at least and, if
`found,