Class PackageReaderOptions

Various options to configure the behavior of the EPUB package reader.

Inheritance

object

PackageReaderOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: VersOne.Epub.Options

Assembly: VersOne.Epub.dll

Syntax

public class PackageReaderOptions

Constructors

PackageReaderOptions(EpubReaderOptionsPreset?)

Initializes a new instance of the PackageReaderOptions class.

Declaration

public PackageReaderOptions(EpubReaderOptionsPreset? preset = null)

Parameters

Type	Name	Description
EpubReaderOptionsPreset?	preset	An optional preset to initialize the PackageReaderOptions class with a predefined set of options.

Properties

FallbackEpubVersion

Gets or sets a value indicating whether the package reader should use a fallback EPUB version when the 'version' attribute of the 'package' XML element in the OPF package file is missing or when the attribute's value is set to an unsupported EPUB version.

If this property is set to null and the 'version' attribute is not present, then the "EPUB parsing error: EPUB version is not specified in the package." exception will be thrown. Alternatively, if the attribute's value is set to an unsupported EPUB version, then the "Unsupported EPUB version: ..." exception will be thrown. Those exceptions can be suppressed by setting this property to an explicit fallback EPUB version (e.g. EPUB_3), in which case the rest of the EPUB schema will be parsed according to that EPUB version specification.

Default value is null.

Declaration

public EpubVersion? FallbackEpubVersion { get; set; }

Property type: EpubVersion?

IgnoreMissingManifestNode

Gets or sets a value indicating whether the package reader should ignore the missing 'manifest' XML element in the OPF package file.

If this property is set to false and the 'manifest' XML element is not present, then the "EPUB parsing error: manifest not found in the package." exception will be thrown. This exception can be suppressed by setting this property to true, in which case all properties of the EpubManifest object will be set to the default / empty values. The EPUB manifest contains the list of content files within the EPUB book (HTML and CSS files, images, fonts, and so on), so even if this exception is suppressed, the EPUB book returned by the EpubReader will have no content.

Default value is false.

Declaration

public bool IgnoreMissingManifestNode { get; set; }

Property type: bool

IgnoreMissingMetadataNode

Gets or sets a value indicating whether the package reader should ignore the missing 'metadata' XML element in the OPF package file.

If this property is set to false and the 'metadata' XML element is not present, then the "EPUB parsing error: metadata not found in the package." exception will be thrown. This exception can be suppressed by setting this property to true, in which case all properties of the EpubMetadata object will be set to the default / empty values. Common metadata fields include the book's titles, the authors, and the descriptions, so even if this exception is suppressed, the Title, the Author, and the Description properties will be empty.

Default value is false.

Declaration

public bool IgnoreMissingMetadataNode { get; set; }

Property type: bool

IgnoreMissingPackageFile

Gets or sets a value indicating whether the package reader should ignore the missing OPF package file error.

The path to the OPF package file is defined by the 'rootfile' element in the 'META-INF/container.xml' file. If this property is set to false and the OPF package file is not present, then the "EPUB parsing error: OPF package file not found in the EPUB file." exception will be thrown. This exception can be suppressed by setting this property to true. However, since the OPF package is the main file describing the EPUB book, the EpubReader class methods will return null in this case.

Default value is false.

Declaration

public bool IgnoreMissingPackageFile { get; set; }

Property type: bool

IgnoreMissingPackageNode

Gets or sets a value indicating whether the package reader should ignore the missing 'package' XML element in the OPF package file.

If this property is set to false and the 'package' XML element is not present, then the "EPUB parsing error: package XML element not found in the package file." exception will be thrown. This exception can be suppressed by setting this property to true. However, since 'package' is the top-level XML element in the OPF package file, the EpubReader class methods will return null in this case.

Default value is false.

Declaration

public bool IgnoreMissingPackageNode { get; set; }

Property type: bool

IgnoreMissingSpineNode

Gets or sets a value indicating whether the package reader should ignore the missing 'spine' XML element in the OPF package file.

If this property is set to false and the 'spine' XML element is not present, then the "EPUB parsing error: spine not found in the package." exception will be thrown. This exception can be suppressed by setting this property to true, in which case all properties of the EpubSpine object will be set to the default / empty values. The EPUB spine determines the reading order within the EPUB book so even if this exception is suppressed, the ReadingOrder property will be empty.

Default value is false.

Declaration

public bool IgnoreMissingSpineNode { get; set; }

Property type: bool

IgnoreMissingToc

Gets or sets a value indicating whether the package reader should ignore the missing TOC attribute in the EPUB 2 spine.

If it's set to false and the TOC attribute is not present, then the "Incorrect EPUB spine: TOC is missing." exception will be thrown. This property has no effect if the EPUB version of the book is not EPUB_2 or if the 'spine' XML element is missing in the OPF package file and the IgnoreMissingSpineNode property is set to true.

Default value is false.

Declaration

public bool IgnoreMissingToc { get; set; }

Property type: bool

IgnorePackageFileIsNotValidXmlError

Gets or sets a value indicating whether the package reader should ignore the error when the package file is not a valid XML file.

If it's set to false and an XML parsing error has occurred while trying to open the OPF package file, then the "EPUB parsing error: package file is not a valid XML file." exception will be thrown with the original XmlException available through the InnerException property. This exception can be suppressed by setting this property to true. However, since the OPF package is the main file describing the EPUB book, the EpubReader class methods will return null in this case.

Default value is false.

Declaration

public bool IgnorePackageFileIsNotValidXmlError { get; set; }

Property type: bool

SkipDuplicateManifestHrefs

Gets or sets a value indicating whether the package reader should skip EPUB manifest items that have duplicate 'href' attribute values.

If it's set to false and an item with a duplicate href value was found, then the "Incorrect EPUB manifest: item with href = ... is not unique." exception will be thrown. This exception can be suppressed by setting this property to true, in which case only the first item within each duplicate item set will be added to the Items collection and the others will be skipped.

Default value is false.

Declaration

public bool SkipDuplicateManifestHrefs { get; set; }

Property type: bool

SkipDuplicateManifestItemIds

Gets or sets a value indicating whether the package reader should skip EPUB manifest items that have duplicate ID values.

If it's set to false and an item with a duplicate ID was found, then the "Incorrect EPUB manifest: item with ID = ... is not unique." exception will be thrown. This exception can be suppressed by setting this property to true, in which case only the first item within each duplicate item set will be added to the Items collection and the others will be skipped.

Default value is false.

Declaration

public bool SkipDuplicateManifestItemIds { get; set; }

Property type: bool

SkipInvalidCollections

Gets or sets a value indicating whether the package reader should skip EPUB collections that are missing the required 'role' attribute.

If it's set to false and the required attribute is not present, then the "Incorrect EPUB collection: collection role is missing." exception will be thrown. This exception can be suppressed by setting this property to true, in which case the collections with the missing 'role' attribute will be skipped.

Default value is false.

Declaration

public bool SkipInvalidCollections { get; set; }

Property type: bool

SkipInvalidGuideReferences

Gets or sets a value indicating whether the package reader should skip EPUB guide items that are missing required attributes ('type' and 'href').

If it's set to false and one of the required attributes is not present, then one of the "Incorrect EPUB guide: item ... is missing." exceptions will be thrown. This exception can be suppressed by setting this property to true, in which case the items with the missing attributes will be skipped.

Default value is false.

Declaration

public bool SkipInvalidGuideReferences { get; set; }

Property type: bool

SkipInvalidManifestItems

Gets or sets a value indicating whether the package reader should skip EPUB manifest items that are missing required attributes ('id', 'href', or 'media-type').

If it's set to false and one of the required attributes is not present, then one of the "Incorrect EPUB manifest: item ... is missing." exceptions will be thrown. This exception can be suppressed by setting this property to true, in which case the items with the missing attributes will be skipped.

Default value is false.

Declaration

public bool SkipInvalidManifestItems { get; set; }

Property type: bool

SkipInvalidSpineItems

Gets or sets a value indicating whether the package reader should skip EPUB spine items that are missing the required 'idref' attribute.

If it's set to false and the required attribute is not present, then the "Incorrect EPUB spine: item ID ref is missing." exception will be thrown. This exception can be suppressed by setting this property to true, in which case the items with the missing 'idref' attribute will be skipped.

Default value is false.

Declaration

public bool SkipInvalidSpineItems { get; set; }

Property type: bool