IpcfDecryptFile function
Decrypts the specified file on disk. This operation requires that the current user has ALL right for the content.
Syntax
HRESULT WINAPI IpcfDecryptFile(
_In_ LPCWSTR wszInputFilePath,
_In_ DWORD dwFlags,
_In_opt_ PCIPC_PROMPT_CTX pContext,
_In_opt_ LPCWSTR wszOutputFileDirectory,
_Out_opt_ LPCWSTR *pwszOutputFilePath
);
Parameters
-
wszInputFilePath [in]
-
The path to the file to decrypt. The path must include the file name and, if one exists, the file name extension.
The path is limited to MAX_PATH characters. To extend this limit to 32,767 characters, prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.
-
dwFlags [in]
-
Specifies optional behavior for this function. For more information, see Decrypt file flags.
-
pContext [in, optional]
-
An optional pointer to information that helps the RMS Client 2.1 determine what the user prompt behavior should be. For more information, see IPC_PROMPT_CTX structure.
-
wszOutputFileDirectory [in, optional]
-
An optional pointer to the output file directory. If the parameter is not specified, the output file will be placed in the same directory as the input file. If the parameter is specified, the output file will be placed in the specified folder. The original file will be deleted.
The path is limited to MAX_PATH characters. To extend this limit to 32,767 characters, prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.
-
pwszOutputFilePath [out, optional]
-
A pointer to a variable that receives a pointer to the output file path. If the file is decrypted in place (the output file path does not change), the value will be NULL. If the output file path is returned, it will be an absolute file path. The buffer that contains the output file path is allocated by the File API and must be freed by using IpcFreeMemory.
If native protection is used, the value of pwszOutputFilePath will be NULL when the function returns.
Return value
If the function succeeds, the return value is S_OK. If the function fails, it returns an HRESULT value that indicates the error.
For more information, see Error codes for a description of all RMS SDK 2.1 return values.
Possible values include, but are not limited to, those in the following list.
-
ERROR_FILE_READ_ONLY
-
IPCERROR_FILE_SYSTEM_FILE
-
IPCERROR_FILE_PROTECTOR_BAD_INSTALL
Remarks
[!Important]
The current user must have the EXTRACT right for the content or the function will fail.
If your application is scanning a protected file, you should perform operations against a copy of the protected file, not on the actual file itself. Your application should create a copy of the protected file, unprotect the copy, scan it, re-encrypt it, and then replace the original protected file with the newly re-encrypted one. This should happen in a single transaction. Operating on a copy of the protected file ensures that if re-encryption fails -- for example, because a user opens the file while it is being operated on -- then the original file will not be lost.
If the input file is in a read-only folder, IpcfDecryptFile will fail. In this case, you can either copy the file to the folder in which want the decrypted copy placed and call IpcfDecryptFile without setting the wszOutputFilePath parameter, or you can copy the file to a temporary folder and call IpcfDecryptFile with wszOutputFilePath set to the directory where you want the decrypted file to be placed. In both cases, IpcfDecryptFile will delete the copy of the original, encrypted file.
For supporting information on using the File API part of RMS SDK 2.1 see, Supported File Formats, File API configuration and Setting the API security mode in the AD RMS developer notes topic.
Requirements
| Minimum supported client |
Windows Vista with SP2 |
| Minimum supported server |
Windows Server 2008 |
| Header |
|
| Library |
|
| DLL |
|