Using Document Objects
OpenText recommends that you create a Document object for each document that you want to process, as described in Start Using KeyView. The document object provides access to the data within a document, including its format, metadata, text, and subfiles.
This topic provides some additional guidance about using document objects in your code.
A Document
must be created and used on the same thread that created the parent session.
A Document
object maintains a reference to the input object, so cannot be used after the input object has been destroyed.
Document Objects and Session Configuration
Changing session configuration options can change the data that is returned by methods of a document object, even if you created the document object before changing the configuration.
Changing your session configuration will also invalidate references previously returned by document object methods.
Consider the following example. You have a document with embedded images but no subfiles and you run the following code:
auto session = keyview::Session{license, bin_path};
session.config().extract_images(false);
InputFile input(path_to_doc);
Document doc = session.open(input);
doc.subfiles().size(); // Returns 0
session.config().extract_images(true);
doc.subfiles().size(); // Returns 3
Password Protected Documents
When you have a Document
object (named protected_doc
in this example), you might find that it is password protected. For instance, protected_doc.info().encrypted()
may be true
, or protected_doc.filter()
may throw a keyview::password_protected_error
. If you know the password, you can configure the session to use that password and then use the existing Document
object to access the document's contents, as in the following code sample.
auto session = keyview::Session{license, bin_path};
session.config().password("");
InputFile input(path_to_protected_doc);
Document protected_doc = session.open(input);
OutputFile output(path_to_output);
// protected_doc.filter(output); - would throw
session.config().password(password);
protected_doc.filter(output); // does not throw