IpcfEncryptFile function
Encrypts a file on disk.
Syntax
HRESULT WINAPI IpcfEncryptFile(
_In_ LPCWSTR wszInputFilePath,
_In_ LPCVOID pvLicenseInfo,
_In_ DWORD dwType,
_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 encrypt. 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.
-
pvLicenseInfo [in]
-
A pointer to the license information to use for encryption. The value of this parameter depends on the dwType parameter.
-
dwType [in]
-
The type of license information to use for encryption. For more information, see Encrypt file input type.
-
dwFlags [in]
-
Specifies optional behavior for this function. For more information, see Encrypt 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 encrypted 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.
-
IPCERROR_FILE_ENCRYPT_BLOCKED
-
IPCERROR_FILE_UPDATELICENSE_BLOCKED
-
ERROR_FILE_READ_ONLY
-
IPCERROR_FILE_SYSTEM_FILE
-
IPCERROR_FILE_PROTECTOR_BAD_INSTALL
Remarks
The value of the IPC_LI_DEPRECATED_ENCRYPTION_ALGORITHMS property set on a license handle passed in the pvLicenseInfo parameter is ignored by IpcfEncryptFile.
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, IpcfEncryptFile will fail. In this case, you can either copy the file to the folder in which want the encrypted copy placed and call IpcfEncryptFile without setting the wszOutputFilePath parameter, or you can copy the file to a temporary folder and call IpcfEncryptFile with wszOutputFilePath set to the directory where you want the encrypted file to be placed. In both cases, IpcfEncryptFile will delete the copy of the original, unencrypted file.
PDF files which are signed, linearized, are not supported for native protection and will cause an error.
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 |
|