Introduction
This guide shows how to read and update document-level state in Aspose.PDF FOSS for C++ — the parts of a PDF that describe the document itself rather than what is drawn on its pages. Aspose.PDF FOSS for C++ centers on the Aspose::Pdf::Document class, which loads an existing PDF from a file path and exposes it for both content editing and document-level bookkeeping. Document-level bookkeeping covers the /Info dictionary, the XMP metadata stream, the bookmark (outline) tree shown in a viewer’s navigation panel, named destinations used by internal links, file attachments embedded in the PDF, and the custom page-numbering sequences a document can define.
This post walks through the API surface for each of these areas: DocumentInfo for the classic /Info dictionary fields (title, author, creator, subject, keywords), Metadata for the XMP metadata stream, Outlines and OutlineItemCollection for the bookmark tree, NamedDestinationCollection for named links, EmbeddedFileCollection and FileSpecification for attachments, and PageLabelCollection for per-range page numbering. Each section pairs the relevant class with a working example built from a loaded Document object.
Aspose.PDF FOSS for C++ is released under the MIT license and links against nothing but the C++ standard library, so every operation described here runs without a proprietary PDF engine or third-party dependency. The library builds as a static target (aspose_pdf_foss) added via CMake.
What’s Included
The /Info Dictionary — DocumentInfo
Document.Info() returns a DocumentInfo reference bound to the PDF’s /Info dictionary. It has typed accessors for the standard fields — Title(), Author(), Creator(), Subject(), Keywords(), Producer(), and Trapped() — each with a matching setter, plus a generic Add(key, value) / Remove(key) pair for custom keys and IsPredefinedKey(key) to check whether a key name is one of the standard fields. Document.SetTitle() is a shortcut that writes the title directly on the document.
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/document_info.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& info = doc.Info();
std::cout << "Title: " << info.Title() << "\n";
std::cout << "Author: " << info.Author() << "\n";
info.Author("Demo author");
info.Creator("Aspose.PDF FOSS C++");
info.Add("Generated-By", "document-management sample");
doc.Save("output.pdf");
}
XMP Metadata — Metadata
Beyond the /Info dictionary, Document.Metadata() returns a Metadata object over the document’s XMP metadata stream. It behaves like an associative container of entries: Add(key, value), Contains(key), ContainsKey(key), TryGetValue(key, value), Remove(key), Keys(), Values(), and Count(). Custom namespaces are registered with RegisterNamespaceUri(prefix, namespaceUri) and resolved back and forth with GetNamespaceUriByPrefix() and GetPrefixByNamespaceUri().
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/metadata.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& metadata = doc.Metadata();
metadata.RegisterNamespaceUri("myapp", "http://example.com/myapp/1.0/");
metadata.Add("myapp:BatchId", "2026-07-run-42");
std::cout << "XMP entries: " << metadata.Count() << "\n";
doc.Save("output.pdf");
}
Bookmarks and Outlines
Document.Outlines() returns the document’s OutlineCollection — the root of the bookmark tree shown in a viewer’s navigation panel. The collection supports Count(), Add(item), Clear(), Contains(item), Remove(item), Delete(), and the endpoint accessors First() / Last(), which return OutlineItemCollection nodes. Each OutlineItemCollection node carries a Title(), Bold() / Italic() display flags, an Open() expand state, a Destination() or Action(), and traversal members Next(), Prev(), HasNext(), Level(), and Parent() back to the owning Outlines collection.
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/outlines.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& outlines = doc.Outlines();
std::cout << "Top-level bookmarks: " << outlines.Count() << "\n";
if (outlines.Count() > 0) {
auto& first = outlines.First();
std::cout << "First bookmark: " << first.Title()
<< " (level " << first.Level() << ")\n";
}
}
Named Destinations
Document.NamedDestinations() returns a NamedDestinationCollection, a lookup table mapping application-defined names to destinations inside the document. New entries are registered with Add(name, appointment), where appointment is an IAppointment implementation — the same interface used by outline-item destinations and link actions. Existing entries are removed with Remove(name), counted with Count(), and enumerated with Names().
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/named_destination_collection.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& destinations = doc.NamedDestinations();
std::cout << "Named destinations: " << destinations.Count() << "\n";
for (const auto& name : destinations.Names()) {
std::cout << " " << name << "\n";
}
}
Embedded Files and Attachments
Document.EmbeddedFiles() returns an EmbeddedFileCollection of FileSpecification attachments carried inside the PDF. Files are added with Add(file) or Add(key, file), looked up by FindByName(name), removed with Delete(name), DeleteByKey(key), or Delete(), and enumerated through Count() and Keys(). Each FileSpecification reports its Name(), Description(), MIMEType(), and AFRelationship() — the PDF “Associated File” relationship classification.
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/file_specification.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& files = doc.EmbeddedFiles();
std::cout << "Embedded files: " << files.Count() << "\n";
for (const auto& key : files.Keys()) {
auto spec = files.FindByName(key);
std::cout << " " << spec.Name() << " (" << spec.MIMEType() << ")\n";
}
}
Page Labels
Document.PageLabels() returns a PageLabelCollection for the custom page-numbering sequences a viewer displays in place of physical page numbers — for example, roman numerals for a preface followed by arabic numerals for the body. GetLabel(pageIndex) retrieves the PageLabel in effect for a page; PageLabel exposes StartingValue(), NumberingStyle() (an Aspose::Pdf::NumberingStyle value such as NumeralsArabic or NumeralsRomanLowercase), and Prefix(). UpdateLabel(pageIndex, pageLabel) assigns a label starting at that page, RemoveLabel(pageIndex) deletes one, and GetPages() lists every page index that carries a custom label.
#include <aspose/pdf/document.hpp>
#include <aspose/pdf/page_label.hpp>
#include <aspose/pdf/page_label_collection.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& labels = doc.PageLabels();
for (int pageIndex : labels.GetPages()) {
auto label = labels.GetLabel(pageIndex);
std::cout << "Page " << pageIndex << " prefix: " << label.Prefix()
<< ", starts at " << label.StartingValue() << "\n";
}
auto preface = labels.GetLabel(1);
preface.NumberingStyle(Aspose::Pdf::NumberingStyle::NumeralsRomanLowercase);
preface.StartingValue(1);
labels.UpdateLabel(1, preface);
doc.Save("output.pdf");
}
Quick Start
Add the library as a CMake subdirectory and link against the aspose_pdf_foss target:
add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)
Open a document, read and update its /Info metadata, and save the result:
#include <aspose/pdf/document.hpp>
#include <iostream>
int main() {
Aspose::Pdf::Document doc("input.pdf");
auto& info = doc.Info();
std::cout << "Title: " << info.Title() << "\n";
std::cout << "Author: " << info.Author() << "\n";
doc.SetTitle("Updated Report Title");
info.Author("Report Generator");
info.Add("Generated-By", "Aspose.PDF FOSS for C++");
doc.Save("output.pdf");
return 0;
}
Supported Formats
| Format | Extension | Read | Write |
|---|---|---|---|
| BMP | .bmp | — | ✓ |
| JPEG | .jpg | — | ✓ |
| TIFF | .tiff | — | ✓ |
| Text | .txt | — | ✓ |
| SVG | .svg | ✓ | — |
BMP, JPEG, and TIFF are page-rendering outputs produced by their respective device classes, and text is extracted via TextAbsorber. SVG is imported as vector content through the library’s SVG load path. None of the document-management types covered above are format converters — they read and write PDF structure only.
Open Source & Licensing
Aspose.PDF FOSS for C++ is distributed under the MIT license, with the full source available at github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp. The license permits commercial use, modification, and redistribution without a separate agreement.