KeyView 24.4
KeyView Filter SDK C++ Programming Guide

# Start Using KeyView

## Create a KeyView Session

To use the C++ Filter SDK, link the library built in Build the C++ API, and include the following headers in your code:

Copy

    #include "Keyview_FilterSDK.hpp"
    #include "Keyview_IO.hpp"

To use the SDK, you must create a KeyView session:

Copy

    auto session = keyview::Session{license, bin_path};

`bin_path` should be a `std::string` that holds the location of the KeyView Filter SDK binaries.

The `Session` class allows you to create a `Document` object from your input file. A `Document` object provides access to the data within your file; the format, text, metadata, and subfiles. The `Session` class also maintains a configuration state that can affect the behavior of the other API methods.

## Configure the Session

You can set additional optional configuration options by using the `config()` method of the `Session` object, which returns a reference to the active configuration. The following example provides a password for filtering password-protected files:

Copy

    session.config().password("myPassword");

You can also chain configuration options:

Copy

    session.config().password("myPassword").hidden_text(true).header_and_footer(true);

The full set of configuration options are documented in The Configuration Class.

## Open a Document

A `Document` object provides access to the data within your file. Create a document object using the `open()` method on your `Session` object. For example:

Copy

    auto myinput = keyview::io::InputFile{ std::string("InputFile.docx") };
    auto doc = session.open(myinput);

NOTE: A `Document` object maintains a reference to the input object, so cannot be used after the input object has been destroyed.

## Determine the Format of a Document

You can find the format of a document by using the info method on a `Document` object. For example:

Copy

    std::cout << "Format:\t" << static_cast<int>(doc.info().format()) << "\n";
    std::cout << "Description:\t" << doc.info().description() << "\n";
    std::cout << "Version:\t" << doc.info().version() << "\n";
    std::cout << "Category:\t" << static_cast<int>(doc.info().category()) << "\n";
    std::cout << "Category Name:\t" << doc.info().category_name() << "\n";
    std::cout << "Encrypted:\t" << std::boolalpha << doc.info().encrypted() << "\n";

## Filter a Document

You can write the text filtered from a document to an output file using the filter method on a `Document` object. For example:

Copy

    auto myoutput = keyview::io::OutputFile{output_path};
    doc.filter(myoutput);

Alternately, you can read this text from a `std::istream` returned by the `text` method. For example:

Copy

    char output[1000] = { 0 };
    doc.text().read(output, sizeof(output));

For more information about streaming filtered text, see Streaming Filtered Text.

## Access Metadata

You can access a document’s metadata by using the metadata method on a `Document` object. For example:

Copy

    for(const auto& [key, elem] : doc.metadata())
    {
        std::cout << key << ": " << elem.convert_to_string() << std::endl;
    }

## Extract Subfiles

You can iterate over subfile information using the subfiles method on a `Document` object. Each element returned by the iterator contains information about the subfile, and a method that you can use to extract it:

Copy

    for (const auto& subfile : doc.subfiles())
    {
        auto myoutput = keyview::io::OutputFile{ subfile.rawname() };
        subfile.extract(myoutput);
    }

NOTE: This very simple example does not account for folders within container files. For a more complete example, see the extract sample program.

NOTE: The `subfiles` method actually returns an instance of the `keyview::Container` class, defined in `Keyview_Container.hpp` (see The Container Class for more information). This provides access to information about the container, and access to each subfile. Please note that the container maintains a reference to the input file, so cannot be used after the input file has been destroyed.

For more guidance about using document objects, see Using Document Objects.

Copyright 1997-2024 Open Text
Version 24.4 | Last updated September 2024

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: IDOL KeyView 24.4

Topic Title: Start Using KeyView