소개
이 가이드는 C++용 Aspose.PDF FOSS에서 문서 수준 상태를 읽고 업데이트하는 방법을 보여줍니다 — 페이지에 그려지는 내용이 아니라 문서 자체를 설명하는 PDF 부분입니다. C++용 Aspose.PDF FOSS은 Aspose::Pdf::Document 클래스를 중심으로 하며, 이 클래스는 파일 경로에서 기존 PDF를 로드하고 콘텐츠 편집과 문서 수준 부기 모두에 노출합니다. 문서 수준 부기에는 /Info 사전, XMP 메타데이터 스트림, 뷰어 탐색 패널에 표시되는 북마크(아웃라인) 트리, 내부 링크가 사용하는 명명된 목적지, PDF에 포함된 파일 첨부, 그리고 문서가 정의할 수 있는 사용자 지정 페이지 번호 매김 시퀀스가 포함됩니다.
이 게시물은 각 영역에 대한 API 인터페이스를 단계별로 살펴봅니다: 고전적인 /Info 사전 필드(제목, 저자, 제작자, 주제, 키워드)를 위한 DocumentInfo, XMP 메타데이터 스트림을 위한 Metadata, 북마크 트리를 위한 Outlines 및 OutlineItemCollection, 명명된 링크를 위한 NamedDestinationCollection, 첨부 파일을 위한 EmbeddedFileCollection 및 FileSpecification, 그리고 범위별 페이지 번호 매김을 위한 PageLabelCollection. 각 섹션은 로드된 Document 객체에서 만든 실용적인 예제와 해당 클래스를 짝지어 제공합니다.
C++용 Aspose.PDF FOSS는 MIT 라이선스로 배포되며 C++ 표준 라이브러리 외에는 아무 것도 링크하지 않으므로 여기서 설명하는 모든 작업이 독점적인 PDF 엔진이나 제3자 의존성 없이 실행됩니다. 이 라이브러리는 CMake를 통해 추가된 정적 타깃(aspose_pdf_foss)으로 빌드됩니다.
포함 내용
/Info 사전 — DocumentInfo
Document.Info()는 PDF의 /Info 사전에 바인딩된 DocumentInfo 참조를 반환합니다. 표준 필드에 대한 타입화된 접근자—Title(), Author(), Creator(), Subject(), Keywords(), Producer(), Trapped()—가 각각 대응하는 설정자를 가지고 있으며, 사용자 정의 키를 위한 일반적인 Add(key, value) / Remove(key) 쌍과 키 이름이 표준 필드 중 하나인지 확인하는 IsPredefinedKey(key)도 제공합니다. Document.SetTitle()은 제목을 문서에 바로 기록하는 단축키입니다.
#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
/Info 사전을 넘어서, Document.Metadata()는 문서의 XMP 메타데이터 스트림을 다루는 Metadata 객체를 반환합니다. 이는 항목들의 연관 컨테이너처럼 동작하며: Add(key, value), Contains(key), ContainsKey(key), TryGetValue(key, value), Remove(key), Keys(), Values(), Count()를 제공합니다. 사용자 정의 네임스페이스는 RegisterNamespaceUri(prefix, namespaceUri)로 등록하고, GetNamespaceUriByPrefix()와 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");
}
북마크 및 아웃라인
Document.Outlines()는 뷰어의 탐색 패널에 표시되는 북마크 트리의 루트인 문서의 OutlineCollection을 반환합니다. 컬렉션은 Count(), Add(item), Clear(), Contains(item), Remove(item), Delete(), 그리고 엔드포인트 접근자 First() / Last()를 지원하며, 이들은 OutlineItemCollection 노드를 반환합니다. 각 OutlineItemCollection 노드는 Title(), Bold() / Italic() 표시 플래그, Open() 확장 상태, Destination() 또는 Action(), 그리고 순회 멤버 Next(), Prev(), HasNext(), Level(), Parent()를 포함하여 소유 Outlines 컬렉션으로 돌아갑니다.
#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";
}
}
명명된 목적지
Document.NamedDestinations()는 애플리케이션이 정의한 이름을 문서 내부의 목적지와 매핑하는 NamedDestinationCollection 조회 테이블을 반환합니다. 새 항목은 Add(name, appointment)으로 등록되며, 여기서 appointment는 IAppointment 구현체입니다 — 이는 아웃라인 아이템 목적지와 링크 액션에 사용되는 동일한 인터페이스입니다. 기존 항목은 Remove(name)으로 삭제하고, Count()로 개수를 셀 수 있으며, 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";
}
}
임베디드 파일 및 첨부 파일
Document.EmbeddedFiles()는 PDF 내부에 포함된 FileSpecification 첨부 파일들의 EmbeddedFileCollection을 반환합니다. 파일은 Add(file) 또는 Add(key, file)로 추가하고, FindByName(name)으로 조회하며, Delete(name), DeleteByKey(key), 또는 Delete()로 삭제하고, Count()와 Keys()로 열거합니다. 각 FileSpecification은 Name(), Description(), MIMEType(), AFRelationship()을 보고합니다 — PDF “Associated File” 관계 분류입니다.
#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";
}
}
페이지 레이블
Document.PageLabels()는 뷰어가 물리적 페이지 번호 대신 표시하는 사용자 정의 페이지 번호 시퀀스를 위한 PageLabelCollection을 반환합니다 — 예를 들어 서문은 로마 숫자, 본문은 아라비아 숫자와 같이. GetLabel(pageIndex)는 해당 페이지에 적용되는 PageLabel을 가져오며; PageLabel은 StartingValue(), NumberingStyle() (Aspose::Pdf::NumberingStyle 값, 예: NumeralsArabic 또는 NumeralsRomanLowercase), Prefix()를 노출합니다. UpdateLabel(pageIndex, pageLabel)은 해당 페이지부터 시작되는 라벨을 할당하고, RemoveLabel(pageIndex)는 라벨을 삭제하며, GetPages()는 사용자 정의 라벨이 있는 모든 페이지 인덱스를 나열합니다.
#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");
}
빠른 시작
라이브러리를 CMake 서브디렉터리로 추가하고 aspose_pdf_foss 타깃에 링크합니다:
add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)
문서를 열고 /Info 메타데이터를 읽은 뒤 업데이트하고 결과를 저장합니다:
#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;
}
지원 포맷
| 형식 | 확장자 | 읽기 | 쓰기 |
|---|---|---|---|
| BMP | .bmp | — | ✓ |
| JPEG | .jpg | — | ✓ |
| TIFF | .tiff | — | ✓ |
| Text | .txt | — | ✓ |
| SVG | .svg | ✓ | — |
BMP, JPEG, 및 TIFF는 각각의 디바이스 클래스에서 생성되는 페이지 렌더링 출력이며, 텍스트는 TextAbsorber를 통해 추출됩니다. SVG는 라이브러리의 SVG 로드 경로를 통해 벡터 콘텐츠로 가져옵니다. 위에서 다룬 문서 관리 유형은 포맷 변환기가 아니며 — PDF 구조만 읽고 씁니다.
오픈 소스 & 라이선스
Aspose.PDF FOSS for C++는 MIT 라이선스 하에 배포되며, 전체 소스는 github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp에서 확인할 수 있습니다. 이 라이선스는 별도의 계약 없이 상업적 사용, 수정 및 재배포를 허용합니다.
