Share via


IpcfEncryptFileStream function

Encrypts a file as a byte stream.

Syntax

HRESULT WINAPI IpcfEncryptFileStream(
  _In_      ILockBytes       *pInputFileStream,
  _In_      LPCWSTR          wszInputFilePath,
  _In_      LPCVOID          pvLicenseInfo,
  _In_      DWORD            dwType,
  _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 encrypted.

wszInputFilePath [in]

The path to the file to encrypt. The path must include the file name and, if one exists, the file name extension.

This parameter is only used to 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.

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.

pOutputFileStream [out]

A pointer to get the encrypted bytes as a result of an encryption 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 encryption 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.

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

Remarks

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