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:
#include "Keyview_FilterSDK.hpp"
#include "Keyview_IO.hpp"
To use the API, you must create a session:
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:
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:
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:
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:
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:
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:
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.