fpExtractSubFile()

This function extracts a subfile from a container file to a user-defined path or output stream. This call returns file format information when file is extracted to a path.

Syntax

int (pascal *fpExtractSubFile)  (
	            void                          *pFile, 
		    KVExtractSubFileArg            extractArg,
		    KVSubFileExtractInfo          *extractInfo);

Arguments

pFile The identifier of the file. This is a file handle returned from fpOpenFile() or fpOpenFileFromFilterSession().
extractArg

A KVExtractSubFileArg. Use this structure to specify the subfile that you want to extract, and how you want to extract it.

Before you initialize the KVExtractSubFileArg structure, use the macro KVStructInit to initialize the KVStructHead structure.

extractInfo On success, this KVSubFileExtractInfo points to a newly allocated structure, which provides information about the extracted subfile.

Returns

  • If the subfile is extracted from the container file, the return value is KVERR_Success.
  • If the subfile is not extracted from the container file, the return value is an error code.

Lifetime and Memory Management

Discussion

  • Before extracting the subfile, you must get the main file information by calling fpGetMainFileInfo().

  • If the subfile is embedded in the main file as a link and is stored externally, extractInfo->infoFlag is set to KVSubFileExtractInfoFlag_External.

    For example, the subfile might be an object that was embedded in a Word document by using "Link to File," or an attachment that is referenced in an MBX message. This type of subfile cannot be extracted. The path and file name of the linked file are given in extractInfo->filePath or extractInfo->fileName. See KVSubFileExtractInfo.

Example

KVExtractSubFileArgRec extractArg;
KVStructInit(&extractArg);
extractArg.index = index;
extractArg.extractionFlag =
    KVExtractionFlag_CreateDir |
    KVExtractionFlag_Overwrite |
    KVExtractionFlag_GetFormattedBody |
    KVExtractionFlag_SanitizeAbsolutePaths;
extractArg.filePath = outputFilename;

KVSubFileExtractInfo extractInfo = NULL;
error = extractInterface->fpExtractSubFile(fileContext, &extractArg, &extractInfo);