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:
#include "Keyview_FilterSDK.hpp"
#include "Keyview_IO.hpp"
To use the SDK, you must create a KeyView session:
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:
session.config().password("myPassword");
You can also chain configuration options:
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:
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));
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.