IpcfDecryptFileStream function
Decrypts a file as a byte stream. This operation requires that the current user has EXTRACT right for the content.
Syntax
HRESULT WINAPI IpcfDecryptFileStream(
_In_ ILockBytes *pInputFileStream,
_In_ LPCWSTR wszInputFilePath,
_In_ DWORD dwFlags,
_In_opt_ PCIPC_PROMPT_CTX pContext,
_Out_ ILockBytes *pOutputFileStream,
_Out_opt_ LPCWSTR *pwszOutputFilePath
);
Parameters
-
pInputFileStream [in]
-
Pointer to the byte stream that represents the file to be decrypted.
-
wszInputFilePath [in]
-
The path to the file to decrypt. The path must include the file name and, if one exists, the file name extension.
This parameter is only used determine the file format, based on the file name extension of the file in the input file stream. Based on this, the suggested output filename is returned via pwszOutputFilePath parameter.
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.
-
pOutputFileStream [out]
-
A pointer to get the decrypted bytes as a result of an decryption operation on a byte stream.
You will need to initialize this interface before calling the API, and free it after the API is done using ILockBytes::Release. For more information on using ILockBytes see, ILockBytes interface.
-
pwszOutputFilePath [out, optional]
-
A pointer to a variable that receives a pointer to the suggested output file path.
The file needs to be saved with the same extension suggested in the parameter for decryption to be possible. If the suggested output file path is same as the one provided via wszInputFilePath, this 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.
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 |
|