FileDrmVerifyRightsEx

  • Article

4/8/2010

This function enables an application to verify that an object has the required rights before it uses FDRM-protected content and enables the user to filter content by its intended use.

Syntax

HRESULT FileDrmVerifyRightsEx (
  HWND hwndParent,
  LPCTSTR pszFileName,
  DWORD dwRight,
  DWORD dwFlags,
  PDWORD pdwRightsStatus
  LPGUID pGuidFilter
);

Parameters

  • hwndParent
    [in] Handle to the window that owns any UI elements such as windows, dialog boxes, or message boxes displayed by this function.
  • pszFileName
    [in] Path to the file that contains the FDRM-protected content.

  • dwRight
    [in] The FDRM right to be used when opening the FDRM-protected content. This is the right specified by the application. Use the bitmask to specify only one right at a time. The following table shows the possible values for dwRight.

    Flag Bitmask Description

    FDRRF_PLAY

    0x00000001

    Play audio/video content.

    FDRRF_DISPLAY

    0x00000002

    Display images.

    FDRRF_EXECUTE

    0x00000004

    Execute applications.

    FDRRF_PRINT

    0x00000008

    Print content.

    FDRRF_FORWARD

    0x00000010

    Content can be forwarded.

  • dwFlags
    [in] Flags to control the behavior of FDRM_VerifyRightsEx. This is a bitmask of FDRVF_* flag values. The following table shows the possible values for dwFlags.

    Flag Bit mask Description

    FDRVF_NOUI

    0x00000001

    Do not display any UI.

    This enables the calling application to ensure that this call will not block waiting for user input.

    FDRVF_NORENEW

    0x00000002

    No rights renewal.

    Does not attempt to update the rights associated with a piece of content, either through user interaction or automatically.

    FDRVF_VERIFY_CONTINUE

    0x00000004

    Verify the continued use of the content.

    Specified when FileDrmCommitRights has been called and returned success for a piece of content and the consuming application of the content is still consuming the same instance of the content but needs to re-verify rights. For example, a media player might begin playing a song but be interrupted by a phone call. Once the phone call is completed the media player will call FileDrmVerifyRightsEx to verify that it still has rights to continue playing that content. This flag may allow content to continue being used even if there are no longer valid rights. For example, if the content has restrictions on the number of times it can be used, and that usage count went to zero in the last call to FileDrmCommitRights, then the user should still be allowed to use that content until is has been completely consumed.

  • pdwRightsStatus
    [out] Status of rights. The following table shows the possible values for dwRight.

    Flag Bitmask Description

    FDRVS_USER_CAN_UPDATE

    0x00000001

    Rights are invalid but the user can update them.

    FDRVS_UPDATE_PENDING

    0x00000002

    A rights update is pending.

    FDRVS_EXPIRABLE

    0x00000004

    Rights are currently valid but can expire.

  • pGuidFilter
    [in] Indicates the intended purpose of the content. If the content pointed to by pszFileName is DRM protected, this filter value is checked as well as the rights associated with the content to determine if the content can be used.

    The following table shows the filter Identifiers for the FileDrmVerifyRightsEx function.

    Filter GUID

    FDRMFT_NONE

    5A3A54DD-209F-48e6-91DB-6A49F9238413

    FDRMFT_RINGTONES

    35AB44BA-B7D0-4548-9C3B-6864E9D08281

    FDRMFT_WALLPAPER

    B7EADA14-F373-4e12-BF17-0722B64362D5

Return Value

This function can return any HRESULT and the application should use the SUCCEEDED and FAILED macros to check the results. The following table shows additional HRESULT values that may be returned.

Value Description

S_FDRM_NOPROVIDER

Success, but no FDRM provider found.

S_FDRM_NOTDRMOBJECT

Success, but the target is not a FDRM object.

E_FDRM_FILEDELETED

Unable to verify rights. The file is deleted.

E_FDRM_CANCELLED

Unable to verify rights. The operation is cancelled.

E_FDRM_LICENSEPENDING

Unable to verify rights. The license is pending.

E_FDRM_NOTALLOWED

Unable to verify rights. The operation not allowed.

Remarks

Before an application can use FDRM-protected content it must call either this function or FileDrmVerifyRights to ensure that the object can be used as intended. This function verifies that the object has the appropriate rights and, if necessary, prompts the user to verify that they want to consume rights or renew expired rights.

Note

When you use the FDRM API in a DSHOW filter you must have the FDRVF_NOUI flag specified when you call the FileDrmVerifyRightsEx function.

The FileDrmVerifyRightsEx function takes the FileDrmVerifyRights function parameteres plus the pGuidFilter filter identifier parameter. The pGuidFilter parameter enables applications to filter content based on the intended use of the content. The filter identifier parameter provides a mechanism for the FDRM engine to filter content. This provides the ability to switch to a different FDRM scheme and the ability for you to customize the device.

Each GUID represents each filter and specifies the intended use of the content, for example, a ring tone. If the content has valid rights but does not meet the FDRM engine defined criteria for using the content in the intended manner then FileDrmVerifyRightsEx returns failure, E_FDRM_NOTALLOWED. Passing FDRMFT_NONE causes no filtering of the results. A filter not recognized by the FDRM engine returns FDRMFT_NONE.

Requirements

Header fdrm.h
Library aygshell.lib
Windows Embedded CE Windows Embedded CE 6.0 and later
Windows Mobile Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

See Also

Reference

FDRM API Reference
FDRM Functions
FileDrmVerifyRights