Start Using the Filter API

Create a 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 API, you must create a session:

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

bin_path should be a std::string that holds the location of the 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.

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.