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.