FileDrmNotifyEnable

4/8/2010

This function registers an application with the FDRM provider for updates when updated rights are received on the device.

Syntax

HRESULT FileDrmNotifyEnable (
  LPCTSTR pszFileName,
  LPTSTR pszValueName,
  DWORD cchValueLen
);

Parameters

• pszFileName
  [in] Fully qualified path to the file for which notifications are to be received.

• pszValueName
  [out] Pointer to a buffer to be filled with the name of a registry DWORD value that is updated when the rights associated with the object change. The returned string must always be terminated with a NULL character as long as cchValueLen is greater than or equal to one.

• cchValueLen
  [in] Length of the pszValueName buffer. A buffer of size MAX_PATH must always be sufficient to hold the returned string. Passing in a smaller buffer will cause this function to return E_INSUFFICIENT_BUFFER if the buffer is too small to hold the returned string, including the NULL terminator.

  MAX_PATH is a standard Windows constant to indicate the maximum length of the buffer required. If the buffer length that is passed is MAX_PATH then the function will not fail because the buffer is too small, although it may fail for other reasons.

Return Values:

The 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.

Remarks

On success the psValueName is filled in with the name of a registry value that can be monitored by the application. A new registry value may have been created in the registry. These values must be under the registry key HKEY_CURRENT_USER\FDRM\Monitor.

An application that requires notification when a rights renewal update has arrived can use this function with the RegistryNotifyxxxx functions to receive notifications from the FDRM provider.

The FDRM provider uses the passed-in filename to generate the name of a registry value that is used as a proxy for the file. The calling application can then register for registry notifications by using this value. When the FDRM provider changes the rights store it also writes the new FDRRF_* rights value to that proxy registry value. For a table of the FDRRF_* rights, see the FileDrmCommitRights function's dwRight parameter.

The FDRM provider references count calls to FileDrmNotifyEnable and FileDrmNotifyDisable and only stops updating and removes the registry value when the reference count goes to 0. The FDRM provider also monitors processes and removes all outstanding references to the notification upon process exit. Registrations by multiple processes or threads within a single process that refer to the same filename must return the same registry value name to be monitored.

The FDRM provider also monitors calls to DeleteFile and removes any outstanding notifications when a FDRM-protected file is deleted.

Requirements

See Also

Reference

FDRM API Reference
FDRM Functions