File Content Extraction 25.1
Filter SDK C Programming Guide

# KVExtractSubFileArg

This structure defines the input parameters required to extract a subfile. See fpExtractSubFile(). The structure is defined in `kvxtract.h`.

    typedef struct tag_KVExtractSubFileArg
    {
        KVStructHeader;
        int                index;
        KVCharSet          srcCharset;
        KVCharSet          trgCharset;
        int                isMSBLSB;
        DWORD              extractionFlag
        char              *filePath;
        char              *extractDir;
        KVOutputStream    *stream;
    }
    KVExtractSubFileArgRec, *KVExtractSubFileArg;

## Member Descriptions

`KVStructHeader` | The version of the structure. See KVStructHead.
`index` | The index number of the subfile to be extracted.
`srcCharset` | Specifies the source character set of the subfile when the file format’s reader cannot determine the character set. The character sets are enumerated in `KVCharSet` in `kvcharset.h`. See Discussion.
`trgCharset` | If the file type is `KVFileType_Main`, this is the target character set of the extracted file. Otherwise, this is ignored. The character sets are enumerated in `KVCharSet` in `kvcharset.h`. See Discussion. DEPRECATED: Target character encodings other than UTF-8 and UTF-16 are deprecated in File Content Extraction version 24.4. OpenText recommends that you use UTF-8 or UTF-16, which is output in Little Endian byte order. Support for other character encodings is currently available but might be removed in a future release.
`isMSBLSB` | This flag indicates whether the byte order for Unicode text is Big Endian (MSBLSB) or Little Endian (LSBMSB). DEPRECATED: This option is deprecated in File Content Extraction version 24.4. OpenText recommends that you set this value to 0, which outputs UTF-16 text in Little Endian byte order. This option might be removed in a future release.
`extractionFlag` | A bitwise flag that defines additional parameters for file extraction. The following flags are available: `KVExtractionFlag_CreateDir` Set this flag to create the path defined in `filePath` if it does not already exist. If you do not set this flag, the path is not created. When the path does not exist and is not created, extraction fails. `KVExtractionFlag_Overwrite` If you set this flag, and the file being extracted has the same name as a file in the target path, the file in the target path is overwritten without warning. If you do not set this flag, and a subfile has the same name as a file in the target path, the error `KVError_OutputFileExists` is generated. `KVExtractionFlag_ExcludeMailHeader` If you set this flag, header information (`To`, `From`, `Sent`, and so on) in a mail file is not included in the extracted data. If you do not set this flag, the extracted data contains header information and the message’s body text. `KVExtractionFlag_GetFormattedBody` If you set this flag, the formatted version of the message body (HTML or RTF) is extracted from mail files when possible. If neither an HTML nor RTF version of the message body exists in the mail file, it is extracted as plain text. If you do not set this flag, the message body is extracted as plain text when possible. NOTE: When an HTML or RTF message body is extracted, the message’s mail headers (such as "From," "To," and "Subject,") are extracted, saved in the same format, and added to the beginning of the subfile. This applies to PST (MAPI-based reader), MSG, and NSF files only. `KVExtractionFlag_SaveAsMSG` If you set this flag, the mail message is extracted as an MSG file, including all of its attachments. If you do not set this flag, the mail message is extracted as text. This applies to PST files processed using the `pstsr` and `pstxsr` readers only. NOTE: In file mode, when the application sets this flag in fpExtractSubFile(), it must also check the KVSubFileExtractInfo structure’s `filePath` parameter to verify the file name used for extraction. `KVExtractionFlag_SanitizeAbsolutePaths` If you set this flag, File Content Extraction ensures that the file is extracted to a location within the extract directory (`extractDir`), even if an absolute path is supplied using `filePath`. When File Content Extraction sanitizes a path and the resulting directory does not exist, extraction fails unless you instruct File Content Extraction to create the directory, so you might also want to set the flag `KVExtractionFlag_CreateDir`. For more information, see Sanitize Absolute Paths.
`filePath` | A pointer to the suggested path or file name to which the subfile is extracted. This can be a file name, partial path, or full path. You can use this in conjunction with `extractDir` to create the full output path. See Discussion.
`extractDir` | A pointer to the directory to which subfiles are extracted. This directory must exist. If you set this flag, the path specified in `KVOpenFileArg->extractDir` is ignored. You can use this in conjunction with `filePath` to create the full output path.
`stream` | A pointer to an output stream defined by KVOutputStream. See Discussion.

## Discussion

- If the document character set is detected and is also specified in `srcCharset`, the detected character set is overridden by the specified character set. If the source character set is not detected and is not specified, character set conversion does not occur.

- The `KVSubFileExtractInfoFlag_CharsetConverted` flag in the KVSubFileExtractInfo structure indicates whether the character set of the subfile was converted during extraction.

- The following applies when the output is to a file:

  - If `filePath` is a valid absolute path, the file is extracted to the specified path and `extractDir` is ignored. However, if you have set the flag `KVExtractionFlag_SanitizeAbsolutePaths` the output path is modified to ensure it is within the `extractDir`. For more information, see Sanitize Absolute Paths.

  - If `filePath` is a file name or partial path, the target directory specified in either `KVExtractSubFileArg->extractDir` or `KVOpenFileArg->extractDir` is used to create the full path. See KVOpenFileArg.

  - If `filePath` is a full path or partial path, and `createDir` is `TRUE`, the directory is created if it does not already exist.

  - If `filePath` is not specified, a default name and the target directory specified in either `KVExtractSubFileArg->extractDir` or `KVOpenFileArg->extractDir` are used to create a full path.

  - If both `filePath` and `extractDir` are not specified or are invalid, an error is returned.

  - If `filePath` is valid, but `extractDir` is not valid, an error is returned.

- The following applies when the output is to a stream:

  - Set `filePath` and `extractDir` to `NULL`.

  - The file format (`docInfo`) and extraction file path (`filePath`) are not returned in KVSubFileExtractInfo.

  - The `KVExtractionFlag_CreateDir` and `KVExtractionFlag_Overwrite` flags are ignored.

- On Windows, `filePath` and `extractDir` must be in the local Windows code page.

Copyright 1997-2024 Open Text
Version 25.1 | Last updated January 2025

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: File Content Extraction 25.1

Topic Title: KVExtractSubFileArg