EpubPublication
OfficeIMO.Epub
A writable EPUB package retaining unknown XML and entry payloads. Instances are mutable and not thread-safe. Use EpubPublication.Read to project the current publication through the existing extraction owner.
Inheritance
- object
- EpubPublication
Usage
Explore 7 API references to this type
This type appears in these public API surfaces even when no hand-authored example is attached directly to the page.
Returned or exposed by 6
- Method EpubManuscriptResult.RequireValue
- Property EpubManuscriptResult.Publication
- Property EpubManuscriptResult.Value
- Method EpubPublication.Create
- Method EpubPublication.Load
- Method EpubPublication.LoadAsync
Accepted by parameters 1
- Method EpubPublication.CompareTo
Methods
public void AddBibliographyEntry(string manifestId, string listId, string entryId, string entryXhtml, CancellationToken cancellationToken = default) #Appends a formatted XHTML reference to an existing ol/ul directly inside a body section. Entries retain caller order. Citation formatting belongs to the bibliography renderer or publisher; this operation adds EPUB bibliography structure without sorting, numbering citations, or fetching sources.
Parameters
- manifestId string
- listId string
- entryId string
- entryXhtml string
- cancellationToken System.Threading.CancellationToken = default
public EpubManifestItem AddChapter(string id, string containerPath, string title, string xhtmlBody, IEnumerable<string>? stylesheets = null, bool linear = true) #Adds a well-formed XHTML body fragment as a chapter, with a linear spine position and a TOC entry.
Parameters
- id string
- containerPath string
- title string
- xhtmlBody string
- stylesheets System.Collections.Generic.IEnumerable<string>? = null
- linear bool = true
Returns
EpubManifestItempublic void AddCollection(string id, EpubCollectionMetadata collection) #Appends a named series or set with its kind, hierarchical position and sorting name atomically. Existing collections remain intact. Requires EPUB 3 and an unused package identifier.
Parameters
- id string
- collection OfficeIMO.Epub.EpubCollectionMetadata
public void AddContributor(string id, EpubContributorMetadata contributor) #Appends a contributor and its ordered MARC roles, sorting name and language in one package edit. Existing contributors and refinements remain intact. Requires EPUB 3 and an unused package identifier.
Parameters
- id string
- contributor OfficeIMO.Epub.EpubContributorMetadata
public void AddCreator(string id, EpubContributorMetadata creator) #Appends a creator and its ordered MARC roles, sorting name and language in one package edit. Existing creators and refinements remain intact. Requires EPUB 3 and an unused package identifier.
Parameters
- id string
- creator OfficeIMO.Epub.EpubContributorMetadata
public void AddDublinCoreMetadata(string name, string value, string? id = null, string? language = null) #Adds an ordered Dublin Core value; existing unknown metadata remains intact.
Parameters
- name string
- value string
- id string? = null
- language string? = null
public void AddGlossaryEntry(string manifestId, string listId, string termId, string term, string definitionXhtml, CancellationToken cancellationToken = default) #Appends a term and XHTML definition to an existing dl directly inside a section in the document body. Adds glossary semantics while preserving the section heading and existing entries. Term text is escaped; definition links use the receiving document's effective HTML base. Entries remain in caller-supplied order.
Parameters
- manifestId string
- listId string
- termId string
- term string
- definitionXhtml string
- cancellationToken System.Threading.CancellationToken = default
public void AddIdentifier(string id, EpubIdentifierMetadata identifier) #Appends an EPUB 3 identifier with an ONIX type for ISBNs or DOI. ISBN shape and checksums are validated; range assignment and identifier registration are not. The selected package identity is unchanged.
Parameters
- id string
- identifier OfficeIMO.Epub.EpubIdentifierMetadata
public void AddIndexEntry(string manifestId, string listId, string entryId, string term, IReadOnlyList<EpubIndexLocator> locators, string? subentriesId = null, CancellationToken cancellationToken = default) #Appends an index term and up to 1024 labelled links to existing XHTML spine content. The destination ul must be directly inside a body section, or inside an existing index li for subentries. Optional subentriesId creates a nested ul for subsequent calls. Publisher order and labels are preserved; sorting, term extraction and page-number calculation are not inferred. The edit commits atomically.
Parameters
- manifestId string
- listId string
- entryId string
- term string
- locators System.Collections.Generic.IReadOnlyList<OfficeIMO.Epub.EpubIndexLocator>
- subentriesId string? = null
- cancellationToken System.Threading.CancellationToken = default
public EpubManifestItem AddMediaOverlay(string contentManifestId, string overlayId, string containerPath, EpubMediaOverlay overlay, CancellationToken cancellationToken = default) #Atomically adds ordered SMIL narration for one XHTML or SVG document, its manifest association, and exact clip-sum duration metadata. Existing overlays are never replaced. Audio durations are caller declarations; encoded audio and reading-system playback require independent validation.
Parameters
- contentManifestId string
- overlayId string
- containerPath string
- overlay OfficeIMO.Epub.EpubMediaOverlay
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubManifestItempublic void AddMetadataProperty(string property, string value, string? refines = null) #Adds an ordered EPUB 3 property value, including repeatable accessibility declarations.
Parameters
- property string
- value string
- refines string? = null
public void AddNote(EpubNoteOptions options, CancellationToken cancellationToken = default) #Adds an EPUB 3 note and links an existing labelled anchor marker to it, with a return link. Both content documents are committed atomically, including identifier and retention checks. Existing reference labels, document heads, and unrelated content are retained. Full publication validation remains part of Write/Preflight; this operation does not certify accessibility.
Parameters
- options OfficeIMO.Epub.EpubNoteOptions
- cancellationToken System.Threading.CancellationToken = default
public void AddPrintPageMarker(string manifestId, string markerId, string pageLabel, string pageListTitle = "Pages", CancellationToken cancellationToken = default) #Marks an existing empty XHTML span as a print-page boundary and appends its link to the EPUB 3 page list. Supply markers in the source edition's page order; labels may be Roman numerals or other publisher text. Content and navigation are committed atomically. Existing navigation and headings remain intact. This creates source-page references, not screen pagination or a print layout.
Parameters
- manifestId string
- markerId string
- pageLabel string
- pageListTitle string = "Pages"
- cancellationToken System.Threading.CancellationToken = default
public EpubManifestItem AddResource(string id, string containerPath, string mediaType, byte[] data, string? properties = null) #Adds a local manifest resource at a canonical container path. Payloads are copied and never executed.
Parameters
- id string
- containerPath string
- mediaType string
- data byte[]
- properties string? = null
Returns
EpubManifestItempublic EpubSpineItem AddSpineItem(string manifestId, bool linear = true, string? properties = null) #Adds a distinct reading position for an existing manifest resource.
Parameters
- manifestId string
- linear bool = true
- properties string? = null
Returns
EpubSpineItempublic EpubManifestItem AddStylesheet(string id, string containerPath, string css) #Adds a UTF-8 stylesheet resource.
Parameters
- id string
- containerPath string
- css string
Returns
EpubManifestItempublic void AddSubject(string id, EpubSubjectMetadata subject) #Appends an EPUB 3 subject with optional authority and code in one metadata edit.
Parameters
- id string
- subject OfficeIMO.Epub.EpubSubjectMetadata
public void AddTitle(string id, EpubTitleMetadata title) #Appends an EPUB 3 title and its refinements atomically without changing the existing primary title.
Parameters
- id string
- title OfficeIMO.Epub.EpubTitleMetadata
public void ApplyContentEdits(IEnumerable<EpubContentEdit> edits, CancellationToken cancellationToken = default) #Applies up to 10,000 non-overlapping element replacements/deletions atomically. Expected XML detects stale drafts. XHTML targets must be inside body; SVG targets must be below its root. Identifiers and publication references are validated against the complete proposed batch.
Parameters
- edits System.Collections.Generic.IEnumerable<OfficeIMO.Epub.EpubContentEdit>
- cancellationToken System.Threading.CancellationToken = default
public EpubEditionComparison CompareTo(EpubPublication revised, CancellationToken cancellationToken = default) #Compares this baseline with a revised edition without mutation. Resources match by manifest ID; unmanifested payloads match by path. XML comparison is structural, not rendered equivalence.
Parameters
- revised OfficeIMO.Epub.EpubPublication
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubEditionComparisonpublic static EpubPublication Create(string title, string language = "en", string? identifier = null, EpubVersion version = Epub3, EpubPublicationLoadOptions? retentionLimits = null) #Creates a publication with stable identity; newly authored packages need at least one linear chapter.
Parameters
- title string
- language string = "en"
- identifier string? = null
- version OfficeIMO.Epub.EpubVersion = Epub3
- retentionLimits OfficeIMO.Epub.EpubPublicationLoadOptions? = null
Returns
EpubPublicationpublic void DeclareVocabularyPrefix(string prefix, string vocabularyUri) #Declares a custom vocabulary prefix without replacing other declarations.
Parameters
- prefix string
- vocabularyUri string
public void Dispose() #Completes the publication lifecycle without saving or closing caller-owned streams.
public XDocument GetContentXml(string manifestId) #Returns an independent XML content document for targeted editing.
Parameters
- manifestId string
Returns
XDocumentpublic XDocument GetPackageXml() #Returns an independent copy of package XML for inspection.
Returns
XDocumentpublic byte[] GetResourceBytes(string manifestId) #Returns an independent copy of retained resource bytes, including original font-obfuscated bytes.
Parameters
- manifestId string
Returns
byte[]public void LinkBibliographyEntry(string sourceManifestId, string referenceId, string bibliographyManifestId, string entryId, string? backlinkText = null, CancellationToken cancellationToken = default) #Links an existing labelled body anchor to a bibliography entry, with an optional localized return link.
Parameters
- sourceManifestId string
- referenceId string
- bibliographyManifestId string
- entryId string
- backlinkText string? = null
- cancellationToken System.Threading.CancellationToken = default
public void LinkGlossaryTerm(string sourceManifestId, string referenceId, string glossaryManifestId, string termId, string? backlinkText = null, CancellationToken cancellationToken = default) #Links an existing labelled anchor without an href to a glossary dt followed by one dd. An optional localized backlink is appended to that definition. Both documents are committed atomically; call once per occurrence to link multiple passages to one term. This does not request a reader popup.
Parameters
- sourceManifestId string
- referenceId string
- glossaryManifestId string
- termId string
- backlinkText string? = null
- cancellationToken System.Threading.CancellationToken = default
public static EpubPublication Load(Stream stream, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default) #Loads all bounded entries for editing without conflating retained package content with extracted chapters.
Parameters
- stream System.IO.Stream
- options OfficeIMO.Epub.EpubPublicationLoadOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubPublicationpublic static EpubPublication Load(string path, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default) #Loads a file for bounded package editing.
Parameters
- path string
- options OfficeIMO.Epub.EpubPublicationLoadOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubPublicationpublic static async Task<EpubPublication> LoadAsync(Stream stream, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default) #Asynchronously loads a caller-owned stream for editing.
Parameters
- stream System.IO.Stream
- options OfficeIMO.Epub.EpubPublicationLoadOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
Task<EpubPublication>public static async Task<EpubPublication> LoadAsync(string path, EpubPublicationLoadOptions? options = null, CancellationToken cancellationToken = default) #Asynchronously loads a file for editing.
Parameters
- path string
- options OfficeIMO.Epub.EpubPublicationLoadOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
Task<EpubPublication>public void MergeChapters(string firstManifestId, string secondManifestId, string boundaryId, CancellationToken cancellationToken = default) #Merges consecutive compatible reflowable chapters into the first resource. Retains both navigation entries, targets the second chapter's start with boundaryId, and repairs references atomically. Conflicting scaffolding, styles, identifiers and package refinements are rejected.
Parameters
- firstManifestId string
- secondManifestId string
- boundaryId string
- cancellationToken System.Threading.CancellationToken = default
public void MergeChapters(string firstManifestId, string secondManifestId, string boundaryId, EpubChapterMergeOptions options, CancellationToken cancellationToken = default) #Merges consecutive reflowable chapters with explicit style, identifier and document-scope reconciliation. The selected cascade applies to both chapters; unresolved scaffold, identifier and package-refinement conflicts fail atomically.
Parameters
- firstManifestId string
- secondManifestId string
- boundaryId string
- options OfficeIMO.Epub.EpubChapterMergeOptions
- cancellationToken System.Threading.CancellationToken = default
public void MoveSpineItem(int fromIndex, int toIndex) #Moves a reading position while preserving its attributes and repeated references.
Parameters
- fromIndex int
- toIndex int
public EpubPreflightReport Preflight(EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #Checks the current publication using the selected save policy and inspects all retained XHTML/SVG identifiers, root and descendant language declarations, image alternatives and EPUB 3 metadata-link relationships. Schema conformance, comprehensive accessibility and reader presentation remain explicitly unchecked. No file is written and no external process is invoked.
Parameters
- options OfficeIMO.Epub.EpubSaveOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubPreflightReportpublic EpubDocument Read(EpubLoadOptions? options = null, CancellationToken cancellationToken = default) #Projects current authored content through the existing EPUB reader, without executing embedded content.
Parameters
- options OfficeIMO.Epub.EpubLoadOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubDocumentpublic void RemoveResource(string manifestId) #Removes an unreferenced declaration and its payload. Callers must first update content/navigation links.
Parameters
- manifestId string
public void RemoveSpineItem(int index) #Removes one reading position without deleting its resource.
Parameters
- index int
public void RenameResource(string manifestId, string containerPath, CancellationToken cancellationToken = default) #Moves a local resource and repairs standard package, XHTML, SVG, NCX, SMIL and CSS references atomically. Manifest identifiers and spine positions remain unchanged. Requires one rendition, inspectable non-scripted resources and no encrypted resources or XML base declarations.
Parameters
- manifestId string
- containerPath string
- cancellationToken System.Threading.CancellationToken = default
public void ReplaceMediaOverlay(string overlayManifestId, EpubMediaOverlay overlay, CancellationToken cancellationToken = default) #Atomically replaces a single chapter's ordered narration and recalculates duration metadata. Preserves cue and sequence ids for surviving text targets, manifest identity and metadata attributes. Rejects shared or encrypted overlays, unsupported SMIL structures, and referenced cues that would be removed. Audio resources remain unchanged; their durations are caller declarations.
Parameters
- overlayManifestId string
- overlay OfficeIMO.Epub.EpubMediaOverlay
- cancellationToken System.Threading.CancellationToken = default
public EpubWriteReport Save(string path, EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #Atomically saves a completed artifact to a file, preserving an existing destination on validation/cancellation failure.
Parameters
- path string
- options OfficeIMO.Epub.EpubSaveOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubWriteReportpublic EpubWriteReport Save(Stream stream, EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #Writes a staged complete artifact to a caller-owned stream. Seekable streams are replaced and rewound.
Parameters
- stream System.IO.Stream
- options OfficeIMO.Epub.EpubSaveOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubWriteReportpublic async Task<EpubWriteReport> SaveAsync(string path, EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #Asynchronously atomically saves a completed artifact to a file.
Parameters
- path string
- options OfficeIMO.Epub.EpubSaveOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
Task<EpubWriteReport>public async Task<EpubWriteReport> SaveAsync(Stream stream, EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #Asynchronously writes a staged artifact without closing the destination stream.
Parameters
- stream System.IO.Stream
- options OfficeIMO.Epub.EpubSaveOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
Task<EpubWriteReport>public void SetAccessibilityMetadata(EpubAccessibilityMetadata metadata) #Atomically replaces the five publication-level discovery properties in EPUB 3. Other metadata and refined properties remain intact. Existing declarations retain attributes where their positions remain; removing an identified declaration referenced by a refinement is rejected. Vocabulary tokens are supplied by the publisher, not inferred or certified. Null summary and empty sufficient-mode sets remove those properties.
Parameters
- metadata OfficeIMO.Epub.EpubAccessibilityMetadata
public void SetContentXml(string manifestId, XDocument content) #Replaces content XML after validating a supported non-scripted XHTML or SVG root.
Parameters
- manifestId string
- content System.Xml.Linq.XDocument
public void SetContentXml(IReadOnlyDictionary<string, XDocument> documents, CancellationToken cancellationToken = default) #Atomically replaces selected XHTML/SVG documents after validating their identifiers and the resulting publication references. Use one batch when moving targets or repairing cross-document links. A rejected or cancelled batch leaves all retained content unchanged.
Parameters
- documents System.Collections.Generic.IReadOnlyDictionary<string, System.Xml.Linq.XDocument>
- cancellationToken System.Threading.CancellationToken = default
public void SetCoverImage(string manifestId) #Selects a manifest image as the cover, preserving other item properties.
Parameters
- manifestId string
public void SetDocumentMatter(string manifestId, EpubDocumentMatter matter, CancellationToken cancellationToken = default) #Sets the XHTML body's EPUB 3 front/body/back-matter partition, retaining its other semantic tokens. This declares structure; reading order and navigation are controlled independently by the spine and SetNavigation.
Parameters
- manifestId string
- matter OfficeIMO.Epub.EpubDocumentMatter
- cancellationToken System.Threading.CancellationToken = default
public void SetFixedLayoutPage(string manifestId, EpubFixedLayoutPage page, CancellationToken cancellationToken = default) #Atomically configures one EPUB 3 XHTML or SVG spine document's page canvas and fixed-layout presentation overrides. DOM order, identifiers and semantic relationships remain unchanged. Existing content CSS may override the canvas rules; verify rendered output in target readers. SVG replaces width, height and viewBox with a zero-origin viewport without changing artwork coordinates; Regions must be empty. This does not paginate reflowable content or certify accessible reading order.
Parameters
- manifestId string
- page OfficeIMO.Epub.EpubFixedLayoutPage
- cancellationToken System.Threading.CancellationToken = default
public void SetMetadataProperty(string property, string value, string? refines = null) #Sets one EPUB 3 property/refinement without replacing unrelated declarations.
Parameters
- property string
- value string
- refines string? = null
public void SetPrimaryTitle(string id, EpubTitleMetadata title) #Updates the first title and its EPUB 3 refinements atomically. An existing title id must match id; existing unrelated refinements and attributes are retained. Null optional fields retain their values.
Parameters
- id string
- title OfficeIMO.Epub.EpubTitleMetadata
public void SetPublicationDetails(EpubPublicationDetails details) #Atomically updates supplied primary EPUB 3 publisher, description, rights and publication-date values. Null fields retain existing values. Other values, attributes and refinements remain intact.
Parameters
- details OfficeIMO.Epub.EpubPublicationDetails
public void SetRenditionLayout(EpubRenditionLayout layout) #Sets typed package layout metadata. This declares layout; it does not create fixed-page geometry.
Parameters
- layout OfficeIMO.Epub.EpubRenditionLayout
public EpubManifestItem SplitChapter(string manifestId, string boundaryId, string newManifestId, string newContainerPath, string title, CancellationToken cancellationToken = default) #Splits a reflowable XHTML chapter before an identified block, moving that block and following content into a new chapter immediately after it. Clones the head and structural containers, repairs publication references, and adds a sibling TOC entry. Rejects separated local ID references.
Parameters
- manifestId string
- boundaryId string
- newManifestId string
- newContainerPath string
- title string
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubManifestItempublic void UpdateResource(string manifestId, byte[] data) #Replaces one local resource payload. Encrypted/obfuscated bytes require an explicit re-keying implementation.
Parameters
- manifestId string
- data byte[]
public EpubWriteResult Write(EpubSaveOptions? options = null, CancellationToken cancellationToken = default) #Produces a complete bounded ZIP before publication. Unedited imports return their exact original bytes.
Parameters
- options OfficeIMO.Epub.EpubSaveOptions? = null
- cancellationToken System.Threading.CancellationToken = default
Returns
EpubWriteResultInherited Methods
Properties
public string PackagePath { get; } #Selected package document path. Other rootfiles and their payloads are preserved.
public string PackageVersion { get; } #Declared package version, preserved when editing.
public IReadOnlyList<EpubManifestItem> Manifest { get; } #Typed manifest declarations in package order.
public IReadOnlyList<EpubSpineItem> Spine { get; } #Typed reading positions, including repeated resource references.
public IReadOnlyList<string> EntryPaths { get; } #All retained entry paths, including unmanifested extension payloads.
public string? FilePath { get; set; } #Gets or sets the associated native save path without writing the publication.
public string Title { get; set; } #Primary title. Other titles and refinements are retained.
public string Language { get; set; } #Primary language. Chapter-level language declarations are edited independently.
public string Identifier { get; set; } #Selected package identity. Identity changes are rejected for obfuscated/encrypted packages.
public string? Creator { get; set; } #Primary creator, preserving other contributors and refinements.
public string? PageProgressionDirection { get; set; } #Page progression declaration, such as ltr or rtl; null restores the package default.