Using FDRM APIs in DSHOW Filters

  • Article

4/8/2010

DirectShow is a generic multimedia extensibility architecture that allows OEMs to support media formats in addition to the default formats that are supported on the device. OEMs can enhance their DSHOW filters to support file-based Digital Rights Management (FDRM) for additional media formats such as 3rd Generation Partnership Project (3GPP) formats. DSHOW filter providers can then support the Windows Mobile FDRM plug-in model by calling the Windows Mobile FDRM APIs to have the FDRM engine properly manage FDRM content.

Note

The DSHOW filter is responsible for notifying the FDRM engine when to commit rights for the use of FDRM-protected content.

By using the Windows Mobile plug-in FDRM model, applications can support any FDRM engine by calling the same set of generic FDRM APIs. One example of FDRM engines for which DSHOW filters can be FDRM-enabled is an OMA DRM V1.0 engine.

There are special considerations for DSHOW Filters. When you use the FDRM APIs in a DSHOW filter, the following FDRM functions must not be called:

  • FileDrmShowLicenseInfo
  • FileDrmRenewRights

In addition, the following FDRM function must have the FDRVF_NOUI flag specified when it is called:

  • FileDrmVerifyRights

The following steps show how a DSHOW filter is enabled to use FDRM:

  1. The Windows Media Player DSHOW module calls the AddSourceFilter function for the requested URL.

    Note

    In earlier versions, the Windows Media Player DSHOW module called the RenderFile function on the requested media item.

    The source DSHOW filter for FDRM-protected content should return S_OK for all content that it can handle, regardless of FDRM issues. Any error returned by the source DSHOW filter when it is added to the graph is handled in the same way that any format error with no UI is handled.

  2. After a successful call to AddSourceFilter, the Windows Media Player DSHOW module performs a query interface (QI) operation for IFileDrmHandler on the source DSHOW filter. If the interface is not found, then the rest of the FDRM related steps are skipped and the playback is immediately available.

  3. If the QI operation for IFileDrmHandler on the source filter succeeds, then the IsPlayable function is called. The Source Filter should check all FDRM issues for the media item during the IsPlayable function call. Any system errors, such as E_OUTOFMEMORY, that prevent evaluation of the FDRM status should be returned from the IsPlayable function with the *pfRequestUI parameter set to FALSE. These errors are handled without filter specific UI in the same way that errors returned from the AddSourceFilter function are handled.

  4. If an error is returned from the IsPlayable function with the *pfRequestUI parameter set to TRUE, then the Windows Media Player DSHOW module leaves the media clip in the "Opening" state and requests that the Windows Media Player application call back with a window handle that can be used for the UI. The IFileDrmHandler interface HandleError function is then called with the window handle for UI and the original error returned from the IsPlayable function.

  5. The UI presented from the HandleError function should then resolve all FDRM issues and return S_OK or return an error code that the Windows Media Player DSHOW module will use to put the clip into an error state.

On the successful return from HandleError, or if there was no IFileDrmHandler interface present after the AddSourceFilter call, the Windows Media Player DSHOW module will enumerate the output pins on the source filter and call the IGraphBuilder Render function for each output pin in the order in which they were enumerated. On the successful completion of the Render call for at least one output pin, the clip is set to the "Opened" state.

The DSHOW filter must suppress all UI when it calls any FDRM APIs.

Note

You can set the HKEY_LOCAL_MACHINE\Security\System\FDRM\EnableConnectMsg registry key to control suppressing or rendering of the UI from the FDRM engine.

All HRESULT errors that the DSHOW filter receives from calling the Windows Mobile FDRM APIs must be passed to the media player. For more information see DSHOW FDRM Error Handling.

The following illustration shows how the different components that manage FDRM-protected DSHOW media files interact. The shaded items must be provided by the DSHOW Filter provider.

Bb446760.1e5755e0-7008-4b74-970d-bbe7af731f27(en-us,MSDN.10).gif

See Also

Concepts

DSHOW FDRM Error Handling
FDRM Security