NAV Navigation
C++

TITUS Metadata SDK 2019.1

The TITUS Metadata SDK enables software developers to implement read/write metadata capabilities that do not use a TITUS user interface.

Package Contents

The SDK package contains the following files:

File or Folder Applicable Platform Description
setup.sh Ubuntu A bash file you can use to install the TITUS Metadata SDK prerequisites on Ubuntu environments.
libMetadataSDK.so.Ubuntu.1.x.x Ubuntu The TITUS Metadata SDK shared object for Ubuntu.
libMetadataSDK.so.CentOS.1.x.x CentOS The Metadata SDK shared object for CentOS.
libMetadataSDK.so.RHEL.1.x.x RHEL The Metadata SDK shared object for Red Hat Enterprise Linux.
libMetadataSDK.1.x.x.macOS.dylib macOS The TITUS Metadata SDK dynamic library for macOS.
MetadataSDK.lib Windows The TITUS Metadata SDK library for Windows.
samples All This folder contains sample code that shows how the TITUS Metadata SDK can be used.
headers All The public headers for the TITUS Metadata SDK.

See Quick Start or Including the SDK in your Project for information about using these files.

Compatibility

TITUS Administration Console

The TITUS Metadata SDK supports metadata generated by TITUS Administration Console 2019.1.

The TITUS Administration Console is used to build and publish your metadata Schema. See The Metadata Schema for more information.

Platforms

The TITUS Metadata SDK is supported on the following platforms at runtime:

Operating System Versions
Ubuntu 16.04 x64
Windows Windows 10 x64
RHEL 7.5 x64
CentOS 7.5-1804 x64
macOS 10.14

Supported File Types

Type File Types Metadata Written Metadata Read
(see Order of Operations)
Open Packaging Convention (OPC) The TITUS Metadata Adapter can interact with any file that follows the Open Packaging Convention.
The following file types have been tested:

Microsoft Office File Types
Word: DOCX, DOTX, DOCM, DOTM
PowerPoint: PPTX, PPSX, PPTM, PPSM, POTM
Excel: XLSX, XLTX
Visio: VSDX, VSTX, VSSX

AutoCAD File Types: DWFX

Other: XPS
  • Document Properties
  • Embedded Metadata
  • Document Properties
  • Embedded Metadata
PDF PDF (up to 1.7)
  • Custom Properties
  • Keywords
  • Embedded Metadata
  • Embedded Metadata

See Metadata for descriptions of each Metadata type.

PDF Support Restrictions

The Metadata Schema

A Metadata Schema is a list of Fields and Values you can write as file metadata using the TITUS Metadata SDK.

You may be given a Metadata Schema to use with the TITUS Metadata SDK, or you can use the TITUS Administration Console to build your own Schema.

Supported Schema features

For information about creating a Metadata Schema in the TITUS Administration Console, see the TITUS Administration Console Guide.

Publishing a Metadata Schema

The metadata Schema is published as a JSON file.

  1. In the TITUS Administration Console, on the Configurations tab, select the Configuration you want to use.
  2. In the Publish to area, click JSON - Metadata SDK.

The file is saved to a location on your computer.

Using the Metadata Schema

The contents of the Metadata Schema JSON file must be passed to unlockComponent when the SDK is called.

Metadata Schema Validation

The TITUS Metadata SDK validates the Metadata Schema in up to three places:

  1. When the Schema is loaded by unlockComponent, the JSON structure is validated.
  2. When metadata is written to a file using setProperties, the SDK validates that the Field being written exists.
  3. When metadata is written to a file using setProperties, the SDK validates that the Value being written exists in the Field. This check is only performed if Restrict to Value List was set on the Field being written.

See Error Reporting for the error codes that can be raised during validation.

No validation is performed when metadata is read from a file.

Metadata

The TITUS Metadata SDK writes metadata in multiple formats to ensure that they can be read by multiple tools and platforms. See Supported File Types to see the types of metadata that are written for each file type.

The TITUS Metadata SDK then reads metadata from file types in a specific order to ensure that metadata is read from the most up-to-date source.

The order in which metadata is read is determined by the way other TITUS products like TITUS Classification for Office write metadata to files. See Order of Operations for the order in which TITUS reads metadata applied to files.

Metadata Types

The following types of metadata are written for each file type:

File Types Metadata Type Description
OPC Document Properties Following the Office Open XML (OOXML) standard.
OPC
PDF		 Embedded Metadata Following the Extensible Metadata Platform (XMP) standard.
PDF Custom Properties Following the PDF standard. See PDF Custom Property Restrictions for more information.
PDF Keywords Name-value pairs following the PDF keyword standard.

PDF Custom Property Restrictions

The TITUS Metadata SDK only supports the following characters in PDF Custom Property tag names:

A-Z, a-z, 0-9, '_', '-'

Custom Property tag names represent Fields in your metadata Schema. If a Field in your metadata contains any characters not listed above (e.g. * or !), that Field-Value pair or set is skipped.
Valid Fields and their Values are still written as Custom Properties. All Fields and Values are written as Embedded Metadata and keywords.

The TITUS Metadata SDK does not read Custom Properties. This restriction may impact your organization if you read Custom Properties using another application or service.

Order of Operations

See below for the order in which metadata is read for each file type.

OPC Files

The TITUS Metadata SDK reads metadata from OPC files in the following order:

PDF

Only Embedded Metadata is read.

See Metadata Types for more information about each metadata type.

Getting Started

Quick Start

  1. Install the TITUS Metadata SDK and its prerequisites:

    On Ubuntu:

    sudo ./setup.sh -i -d

    Other Platforms:

    See Installing the SDK Prerequisites and Installing the SDK for platform-specific instructions.

  2. Include the following files in your project:

    • The public headers (found in the headers folder)

    • The SDK library, dynamic library, or shared object:

      Platform Filename
      Ubuntu, RHEL, CentOS libMetadataSDK.‌so‌.[platform].1.x.x
      macOS libMetadataSDK.1.x.x.macOS.dylib
      Windows MetadataSDK.lib

    On Linux and macOS platforms, the library must also be distributed to the client where the TITUS Metadata SDK will run.

Prerequisites

To develop using the TITUS Metadata SDK, ensure that your development environment meets the following prerequisites.

Prerequisite Platform Description
C++ compiler All To use the TITUS Metadata SDK, you need a C++ compiler.

Ubuntu: GCC 5.4.0
RHEL or CentOS: GCC 4.9.2
macOS: Apple LLVM version 10.0.1
Windows: See IDE, below.
IDE All Ubuntu, RHEL, CentOS, macOS: The SDK is compatible with any IDE that uses a compatible C++ compiler (see above).
Windows: The TITUS Metadata SDK supports Visual Studio 2015 or higher, using the Visual Studio 2015 v140 platform toolset or higher.
Perl All except Windows ExifTool requires Perl to run.
Most supported platforms should already have Perl installed. Type perl -v on a command line to confirm.
Homebrew macOS To install the prerequisites using the instructions below, you must install the Homebrew package manager.
If you do not want to use a package manager to install the prerequisites, you can also install the ExifTool package directly. See the ExifTool website for detailed instructions.
ExifTool All To compile the TITUS Metadata SDK, you must have the ExifTool Perl library installed. ExifTool is used to write metadata to PDFs.
This is installed using the bash script on Ubuntu platforms.
Compress::Zlib CentOS and RHEL CentOS and RHEL also require the Compress::Zlib Perl module to support ExifTool.

See Installing the SDK Prerequisites for more information.

Prerequisites in the Installer

TITUS provides a bash script that can install the following prerequisites on Ubuntu. The script also installs the TITUSMetadataSDK shared object.

Prerequisite Description
ExifTool To compile the TITUS Metadata SDK, you must have the ExifTool Perl library installed. ExifTool is used to write metadata to PDFs.

See To Install the SDK on Ubuntu for information about using this script.

Installing the SDK Prerequisites

See the topics below for information about installing the prerequisites on your platform:

To Install the SDK Prerequisites on Ubuntu

TITUS provides a bash script that can install the Metadata SDK prerequisites.

The script also installs the TITUSMetadataSDK shared object.

See To Install the SDK on Ubuntu for information about using this script.

To Install the SDK Prerequisites on RHEL

You must enable EPEL Repository before you can install and use ExifTool on RHEL. Follow the steps below as root user:

  1. Enable and install EPEL:

    yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

    yum install epel-release

  2. Install ExifTool:

    yum install perl-Image-ExifTool.noarch

  3. Install Compress::Zlib:

    yum install perl-IO-Zlib.noarch

To install the SDK Prerequisites on CentOS

You must enable EPEL Repository before you can install and use ExifTool on CentOS. Follow the steps below as root user:

  1. Enable and install EPEL:

    yum install epel-release

  2. Install ExifTool:

    yum install perl-Image-ExifTool.noarch

  3. Install Compress::Zlib:

    yum install perl-IO-Zlib.noarch

To install the SDK Prerequisites on macOS

  1. Install Homebrew:

    ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null

  2. Install ExifTool:

    brew install exiftool

To Install the SDK Prerequisites on Windows

ExifTool

  1. Download the newest version of the ExifTool Windows executable from the ExifTool home page.
  2. Extract exiftool(-k).exe from the ZIP file.
  3. Rename exiftool(-k).exe to exiftool.exe.
  4. Move exiftool.exe to the C:\WINDOWS directory, or any other directory in your PATH.

Installing the SDK

See the topics below for information about installing the SDK on your platform:

To Install the SDK on Ubuntu

TITUS provides a bash script that can install the Metadata SDK prerequisites.

The script also installs the TITUSMetadataSDK shared object. When the shared object is installed, soft links to the shared object are also created.

The script accepts the following flags:

Flag Description
-h or --help Display the help.
-i or --install Run the TITUS Metadata SDK installer.
-u or --uninstall Run the uninstall process.
-d or --dependencies Include the TITUS Metadata SDK dependencies in the install or uninstall.

To run the script, you need the following:

Sample Command

sudo ./setup.sh -i -d

To Install the SDK on RHEL or CentOS

To Install the SDK on macOS

To Install the SDK on Windows

See Including the SDK in your Project.

Including the SDK in your Project

Linux Distros (RHEL, CentOS, Ubuntu)

Include the following files in your project:

The shared object must also be distributed to the shared libraries on the client where the TITUS Metadata SDK will run.

macOS

Include the following files in your project:

The dynamic library must also be added to the dynamic libraries on the client where the TITUS Metadata SDK will run.

Windows (Visual Studio)

To use the TITUS Metadata SDK library, make the following changes in your Visual Studio project's properties:

  1. In the C/C++ > General properties, edit the Additional Include Directories. Select the headers folder from the TITUS Metadata SDK package.
  2. In the Linker > General properties, edit the Additional Library Directories. Select the path to the MetadataSDK.lib file. Do not include the file name.
  3. In the Linker > Input properties, edit the Additional Dependencies. Add the full name of the LIB file (e.g. MetadataSDK.lib).

Sample Code

Below are some samples of how you can implement the TITUS Metadata SDK. These samples are also available in the samples folder of the SDK package.

Consume the TITUS Metadata Schema or License

You must pass the TITUS Metadata Schema and TITUS license to unlockComponent to use the TITUS Metadata SDK. You can copy the contents of these files into your code, or you can use a method like the one below to read the contents of each file into a string. This method is referenced in the following samples:

string_t LoadContentFromFile(const string_t filenameAndPath) {
	std::ifstream t(filenameAndPath);
    string_t str;

    t.seekg(0, std::ios::end);
    str.reserve(static_cast(t.tellg()));
    t.seekg(0, std::ios::beg);

    str.assign((std::istreambuf_iterator(t)),
                std::istreambuf_iterator());
    return str;
}

Read and Write Metadata

In this sample, the code is performing the following operations:

getUpdatableMetadata can be used when you want to read metadata from a file and then write metadata to the file based on the metadata you read. getUpdatableMetadata is the most optimized way for reading and writing metadata. readAllMetadata together with writeAllMetadata reads metadata twice while getUpdatableMetadata reads metadata only once.

In this example, all paths can be relative or absolute.

#include "TitusMetadataSDK.h"

TitusMetadataSDK sdk;
string_t licenseContent = LoadContentFromFile(/*license file path*/)
string_t metadataSchema = LoadContentFromFile(/*metadata Schema file path*/)
sdk.unlockComponent(licenseContent, metadataSchema);

string_t filePath = "I am a file.";
std::unique_ptr result(sdk.getUpdatableMetadata(filePath));

// Read Metadata
key_value_t props = result->getProperties();

// Set Metadata
key_value_t properties;
properties["Classification"] = "Secret";
result->setProperties(properties);

// Save the file
result->save();

Read Metadata

In this sample, the code is performing the following operations:

In this example, all paths can be relative or absolute.

#include "TitusMetadataSDK.h"

TitusMetadataSDK sdk;
string_t licenseContent = LoadContentFromFile(/*license file path*/)
string_t metadataSchema = LoadContentFromFile(/*metadata Schema file path*/)
sdk.unlockComponent(licenseContent, metadataSchema);

string_t filePath = "I am a file.";

// Read Metadata
std::unique_ptr result(sdk.readAllMetadata(filePath));
key_value_t properties = result->getProperties();

Write Metadata

In this sample, the code is loading the license and metadata Schema from a file, unlocking the SDK, and writing metadata to the file at the path provided.

In this example, all paths can be relative or absolute.

When you use writeAllMetadata to write metadata, metadata is read so new metadata can be written in the correct location. If you are planning on reading metadata before writing new metadata, consider using getUpdatableMetadata instead. See Read and Write Metadata for an example.

#include "TitusMetadataSDK.h"

TitusMetadataSDK sdk;
string_t licenseContent = LoadContentFromFile(/*license file path*/)
string_t metadataSchema = LoadContentFromFile(/*metadata Schema file path*/)
sdk.unlockComponent(licenseContent, metadataSchema);

string_t filePath = "I am a file.";
key_value_t properties;
properties["Classification"] = "Secret";

// Write and Save Metadata
std::unique_ptr result(sdk.writeAllMetadata(filePath, properties));

Determine the Metadata SDK Version

In this sample, the code is retrieving the version of the TITUS Metadata SDK from TitusMetadataSDK.h.

std::cout << "The TITUS Metadata SDK version is: " << TITUSMETADATASDK_VERSION << std::endl;

Error Reporting

The errors produced by the TITUS Metadata SDK can be accessed through getErrors, which returns a vector of errors. Each call into the TITUS Metadata SDK which can fail will return a boolean representing whether the call was successful.

Errors can be produced even if the result is a success. One example is when no metadata is found in the provided file. The NoMetadataFound error is produced, but the metadata read is not necessarily a failure.

Below is a list of errors that can be returned using the TITUS Metadata SDK.

Error Code Description
LicenseError 1 An invalid license has been provided to unlockComponent.
NoMetadataFound 2 The file provided contained no metadata to be read.
ComponentLocked 3 The unlockComponent call was not made. This call must be made before using the TITUS Metadata SDK.
FileEmpty 4 The file provided contains no data, so metadata cannot be read. This error may occur if the file is locked or the file name is missing from the path provided.
UnknownError 5
InvalidMetadataSchema 6 An invalid metadata Schema has been provided to unlockComponent. This error may occur if the JSON is malformed.
UnknownFileAdapter 7 The file provided is not supported by the current version of the TITUS Metadata SDK. This error may occur in the following cases:
  • The file is not found.
  • The file name is missing from the path provided.
  • The file is encrypted or password protected.
  • The file is a corrupted OPC file.
  • The SDK is attempting to write to a locked file.
  • The SDK is attempting to read from a locked file (Windows platforms only).
  • The SDK is attempting to write to an empty OPC file.
FileLoadFailed 8 Access has been denied or the file cannot be opened. This error may occur when the SDK is attempting to read from a corrupted PDF.
EmbeddedNotFound 9 Embedded Metadata was not found within the file provided.
This error may occur when the SDK is attempting to read from a corrupted PDF.
CustomPropertiesNotFound 10 Custom Properties were not found in the file provided.
EmbeddedMetadataReadSkipped 11 Embedded Metadata read was skipped since it was not necessary. This means metadata was read in a different location, such as the Document Properties.
FileWriteFailed 12 Cannot edit the file provided. Please verify file exists and check file permissions. This error may occur in the following cases:
  • The file is open (Windows platforms only).
  • The file is read only.
  • The file is a corrupted PDF.
MetadataWriteFailed 13 Cannot save metadata to the file provided. Please verify that the file exists and check file permissions. This error may occur in the following cases:
  • The file is open (Windows platforms only).
  • The file is read only.
  • The file is a corrupted PDF.
SoftLinkOrShortcutsNotSupported 14 Unable to access the file. Soft links or shortcuts are not supported for this adapter. Please provide a hard or direct link to the file.
Invalid Field 1000+ The metadata field "[fieldname]" does not exist. See Errors for Invalid Metadata.
Invalid Value 1000+ The metadata value "[value]" does not exist for field "[fieldname]". See Errors for Invalid Metadata

Errors for Invalid Metadata

Metadata error codes and messages are generated dynamically when errors occur. Error codes start at 1000 and increment every time a unique error occurs.

If the same error occurs (e.g. the same invalid Field is passed to the SDK), the same error code is used.

See Metadata Schema Validation for information about when the metadata Schema is validated.

C++