Microsoft DirectX 8.1 (C++)

IResourceManager::RequestResource

The RequestResource method 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:

  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 whose object of focus shares a common filter graph.
  3. 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.

See Also