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));

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.