Share via


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
Ipcfile.h (include Msipc.h)
Library
Msipc.lib
DLL
Msipc.dll

See also

Naming Files, Paths, and Namespaces

IpcGetTemplateList

IpcCreateLicenseFromScratch

IpcCreateLicenseFromTemplateID

IPC_PROMPT_CTX

IpcFreeMemory

Supported File Formats

File API configuration

Setting the API security

AD RMS developer notes

Error codes