IResourceManager Interface

The IResourceManager interface implements a resource manager to resolve contentions for named resources.

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.

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

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

IResourceManager methods Description
Register Registers a single named resource with the resource manager.
RegisterGroup Registers a named resource group with the resource manager.
RequestResource Requests the use of a given registered resource.
NotifyAcquire Notifies the resource manager that an attempt to acquire a resource has completed.
NotifyRelease Notifies the resource manager that a resource consumer has released a resource.
CancelRequest Cancels the request for a resource.
SetFocus Notifies the resource manager that a specified object has been given the focus of the user.
ReleaseFocus 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.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IResourceManager methods	Description
Register	Registers a single named resource with the resource manager.
RegisterGroup	Registers a named resource group with the resource manager.
RequestResource	Requests the use of a given registered resource.
NotifyAcquire	Notifies the resource manager that an attempt to acquire a resource has completed.
NotifyRelease	Notifies the resource manager that a resource consumer has released a resource.
CancelRequest	Cancels the request for a resource.
SetFocus	Notifies the resource manager that a specified object has been given the focus of the user.
ReleaseFocus	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.

IResourceManager::CancelRequest

IResourceManager Interface

Cancels the request for a resource.

Syntax

HRESULT CancelRequest(
    LONG idResource,
    IResourceConsumer *pConsumer
);

Parameters

idResource
[in] Resource identifier of a pending request.
pConsumer
[in] Pointer to the IResourceConsumer interface that made the request.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

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 IResourceManager::NotifyRelease method.

IResourceManager::NotifyAcquire

IResourceManager Interface

Notifies the resource manager that an attempt to acquire a resource has completed.

Syntax

HRESULT NotifyAcquire(
    LONG idResource,
    IResourceConsumer *pConsumer,
    HRESULT hr
);

Parameters

idResource
[in] Token for the registered resource.
pConsumer
[in] Pointer to the IResourceConsumer interface of the object requesting the resource.
hr
[in] Value indicating the success of the acquisition; S_OK if the resource was acquired, or an error value if not.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

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.

IResourceManager::NotifyRelease

IResourceManager Interface

Notifies the resource manager that IResourceConsumer has released a resource.

Syntax

HRESULT NotifyRelease LONG idResource,
    IResourceConsumer *pConsumer,
    BOOL bStillWant
);

Parameters

idResource
[in] Resource token.
pConsumer
[in] Pointer to the object releasing the resource.
bStillWant
[in] Flag that specifies whether the resource is still required. Set to TRUE to indicate that you still want the resource when it is next available, or FALSE if you no longer want the resource.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

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.

IResourceManager::Register

IResourceManager Interface

Registers a single named resource with the resource manager.

Syntax

HRESULT Register(
    LPCWSTR pName,
    LONG cResource,
    LONG *plToken
);

Parameters

pName
[in] Named resource.
cResource
[in] Number of resources.
plToken
[out] Pointer to the returned token identifying the resource to be used in additional calls.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

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.

IResourceManager::RegisterGroup

IResourceManager Interface

Registers a named resource group with the resource manager.

Syntax

HRESULT RegisterGroup(
    LPCWSTR pName,
    LONG cResource,
    LONG *palTokens,
    LONG *plToken
);

Parameters

pName
[in] Named resource group.
cResource
[in] Number of resources in the group.
palTokens
[in, size_is(cResource)] Pointer to an array of resources in the group.
plToken
[out] Pointer to the returned group resource identifier.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

IResourceManager::ReleaseFocus

IResourceManager Interface

Sets the focus object to NULL in the resource manager if the current focus object is the one specified in this method.

Syntax

HRESULT ReleaseFocus(
    IUnknown *pFocusObject
);

Parameters

pFocusObject
[in] Pointer to the focus object.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

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.

IResourceManager::RequestResource

IResourceManager Interface

Requests the use of a given registered resource.

Syntax

HRESULT RequestResource(
    LONG idResource,
    IUnknown *pFocusObject,
    IResourceConsumer *pConsumer
);

Parameters

idResource
[in] Resource token retrieved when the resource was registered.
pFocusObject
[in] Pointer to the IUnknown interface of a focus object associated with a request (typically the filter's IUnknown interface).
pConsumer
[in] Pointer to the IResourceConsumer interface on the object requesting the resource.

Return Value

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.

Requests made with exactly the same object of focus as the last SetFocus method.
Requests whose object of focus shares a common source filter.
Requests whose object of focus shares a common filter graph.
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::CancelRequest method is called, or the IResourceManager::NotifyRelease method is called with the bStillWant parameter set to FALSE.

IResourceManager::SetFocus

IResourceManager Interface

Notifies the resource manager that a specified object has been given the focus of the user.

Syntax

HRESULT SetFocus(
    IUnknown *pFocusObject
);

Parameters

pFocusObject
[in] Pointer to the object that has been given the user's focus.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

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.

Requests made with the focus object specified in the pFocusObject parameter.
Requests whose focus object shares a common source filter.
Requests whose focus object shares a common filter graph.
Requests in the same process as the focus.

After 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 IUnknown 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 QueryInterface for the IBaseFilter interface at least and, if found, will use methods on that interface. It calls methods on IBaseFilter to decide which audio renderer to use if there are two (it will choose the one with a source filter common to the focus object), and also to determine if the two objects are within the same filter graph.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.