FileDrmCreateFile

4/8/2010

This function enables a FDRM-enabled application to open FDRM-protected content. This function is used in place of the standard Win32 CreateFile function.

Syntax

HRESULT FileDrmCreateFile (
  LPCTSTR pszFileName,
  DWORD dwDesiredAccess,
  DWORD dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD dwCreationDisposition,
  DWORD dwFlagsAndAttributes,
  HANDLE hTemplateFile,
  PHANDLE phFile
);

Parameters

• pszFileName
  [in] The fully qualified path to the file to be opened.

• dwDesiredAccess
  [in] Type of access to the object.

• dwShareMode
  [in] Share mode for the object.

• lpSecurityAttributes
  [in] Ignored, set to NULL.

• dwCreationDisposition
  [in] How to handle existing and new files.

• dwFlagsAndAttributes
  [in] File attributes for the file.

• hTemplateFile
  [in] Ignored, set to NULL.

• phFile
  [out] Pointer to a handle variable that contains the file handle if the call is successful.

Return Value

In addition to the HRESULT return code, the value pointed to by phFile must be set to INVALID_HANDLE_VALUE if an error is returned.

The function may 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

Use the CloseHandle function to close the handle returned from this function.

This function is used to replace the standard Win32 CreateFile API for applications that are FDRM enabled. FileDrmCreateFile returns any error that occurs during the call as the HRESULT created by HRESULT_FROM_WIN32 called on the value returned from GetLastError(). FileDrmCreateFile behaves the same way as CreateFile with the following exceptions:

Case 1: When FileDrmCreateFile opens FDRM content for use under the following conditions:

• An FDRM provider is installed.
• The file being created already exists and contains FDRM-protected content.
• The dwDesiredAccess parameter is set to GENERIC_READ.
• The dwCreationDisposition parameter is set to OPEN_EXISTING.
  In this case FileDrmCreateFile opens the file in such a way that subsequent calls to ReadFile return the unencrypted version of the file's content such that it can be used by the application.

Case 2: When FileDrmCreateFile attempts to open FDRM content for write access under the following conditions:

• An FDRM provider is installed.
• The file being created already exists and contains FDRM-protected content.
• The dwDesiredAccess parameteris set to GENERIC_WRITE.
  In this case FileDrmCreateFile will fail to open the file to prevent applications from inadvertently overwriting protected content.

Case 3: When FileDrmCreateFile attempts to delete or truncate FDRM content under the following conditions:

• An FDRM provider is installed.
• The file being created already exists and contains FDRM-protected content.
• The dwCreationDisposition parameter is set to CREATE_ALWAYS or TRUNCATE_EXISTING.
  In this case FileDrmCreateFile will fail to open the file in order to prevent applications from inadvertently overwriting protected content.

Requirements

See Also

Reference

FDRM API Reference
FDRM Functions