Struct OpaqueEntryBuilder 

pub struct OpaqueEntryBuilder { /* private fields */ }

A builder for creating a NormalEntry by writing an opaque byte stream tagged with a declared DataKind.

This is the escape hatch for DataKinds that have no dedicated builder: data written via the Write trait is compressed and encrypted according to the given WriteOptions and stored as-is, with no interpretation of its meaning. It also provides convenience constructors (new_dir(), new_file(), new_symlink(), new_hard_link()) for the kinds defined by the PNA specification, but for those kinds prefer the corresponding kind-specific builder instead (FileEntryBuilder, DirEntryBuilder, SymlinkEntryBuilder, HardLinkEntryBuilder), which encode that kind’s on-wire contract in the type itself. Reach for new() or new_with_options() directly only for kinds the specification does not define, such as private or experimental DataKinds.

Write Trait Behavior

For entries constructed via new() or new_with_options() — writing the opaque byte stream for the declared DataKind — the Write trait is fully functional; the legacy new_file() constructor (which delegates to new_with_options() with DataKind::FILE) behaves the same way. Data written via write_all() or similar methods is automatically compressed and encrypted according to the WriteOptions provided at construction time. The original (uncompressed) size is tracked separately.

For directory entries (new_dir()), the Write trait is implemented but writing data has no effect. Directories do not store data payloads in PNA archives.

For symbolic link and hard link entries, do not use the Write trait. The link target is written internally when the entry is constructed via new_symlink() or new_hard_link(); writing further data onto the builder would corrupt it.

Metadata

Metadata (timestamps, permissions, extended attributes) can be set at any time before calling build(). The order does not matter - you can set metadata before, during, or after writing data.

Compression and Encryption

When data is written:

1. Data is compressed according to WriteOptions compression settings
2. Compressed data is encrypted according to WriteOptions encryption settings
3. Encrypted data is buffered into chunks
4. Chunks are finalized when build() is called

This happens transparently - you just write raw data and the builder handles the rest.

Important Notes

• Each builder can only be built once (build() consumes self)
• Only entries with a DataKind::FILE kind record a raw file size; if no data is written, that size is recorded as zero. For all other kinds, the raw file size is omitted entirely
• Compression and encryption are applied during writes, not at build time
• The build() method finalizes compression/encryption streams
• Building a directory or file without calling write methods is valid

Implementations

impl OpaqueEntryBuilder

pub fn new(name: EntryName, kind: DataKind) -> Result<Self>

Creates a builder for an entry of the given kind that stores its data without compression or encryption.

The entry data is written via the Write trait as an opaque byte stream; its interpretation is left to the application. Prefer the kind-specific builders for the kinds defined by the PNA specification.

Errors

Returns an error if initialization fails.

pub fn new_with_options( name: EntryName, kind: DataKind, option: impl WriteOption, ) -> Result<Self>

Creates a builder for an entry of the given kind with the given write options.

Errors

Returns an error if initialization fails.

pub const fn new_dir(name: EntryName) -> Self

👎Deprecated since 0.36.0:

use DirEntryBuilder::new

Creates a new OpaqueEntryBuilder for a directory entry.

pub fn new_file(name: EntryName, option: impl WriteOption) -> Result<Self>

👎Deprecated since 0.36.0:

use FileEntryBuilder::new_with_options

Creates a new OpaqueEntryBuilder for a file entry with the given write options.

Errors

Returns an error if initialization fails.

pub fn new_symlink(name: EntryName, source: EntryReference) -> Result<Self>

👎Deprecated since 0.36.0:

use SymlinkEntryBuilder::new

Creates a new OpaqueEntryBuilder for a symbolic link entry pointing to the given source.

Errors

Returns an error if initialization fails.

Examples

use libpna::{SymlinkEntryBuilder, EntryName, EntryReference};

let builder = SymlinkEntryBuilder::new(
    EntryName::try_from("path/of/link").unwrap(),
    EntryReference::try_from("path/of/target").unwrap(),
)
.unwrap();
let entry = builder.build().unwrap();

pub fn new_hard_link(name: EntryName, source: EntryReference) -> Result<Self>

👎Deprecated since 0.36.0:

use HardLinkEntryBuilder::new

Creates a new OpaqueEntryBuilder for a hard link entry pointing to the given source.

Errors

Returns an error if initialization fails.

Examples

use libpna::{HardLinkEntryBuilder, EntryName, EntryReference};

let builder = HardLinkEntryBuilder::new(
    EntryName::try_from("path/of/link").unwrap(),
    EntryReference::try_from("path/of/target").unwrap(),
)
.unwrap();
let entry = builder.build().unwrap();

pub fn metadata(&mut self, metadata: Metadata) -> &mut Self

Sets the metadata of the entry, replacing any previously set metadata.

The raw file size and compressed size recorded in the given metadata are ignored; build() computes them.

pub fn created( &mut self, since_unix_epoch: impl Into<Option<Duration>>, ) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the creation timestamp of the entry.

pub fn modified( &mut self, since_unix_epoch: impl Into<Option<Duration>>, ) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the last modified timestamp of the entry.

pub fn accessed( &mut self, since_unix_epoch: impl Into<Option<Duration>>, ) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the last accessed timestamp of the entry.

pub fn permission( &mut self, permission: impl Into<Option<Permission>>, ) -> &mut Self

👎Deprecated since 0.34.0:

the fPRM chunk is superseded by the owner facet chunks; use OpaqueEntryBuilder::metadata with Metadata::with_owner_uid/with_owner_gid/with_owner_user_name/with_owner_group_name/with_permission_mode

Sets the permission of the entry to the given owner, group, and permissions.

pub fn owner_uid(&mut self, value: impl Into<Option<OwnerUid>>) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the owner user id facet (fUId).

pub fn owner_gid(&mut self, value: impl Into<Option<OwnerGid>>) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the owner group id facet (fGId).

pub fn owner_user_name( &mut self, value: impl Into<Option<OwnerUserName>>, ) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the owner user name facet (fONm).

pub fn owner_group_name( &mut self, value: impl Into<Option<OwnerGroupName>>, ) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the owner group name facet (fGNm).

pub fn owner_user_sid( &mut self, value: impl Into<Option<OwnerUserSid>>, ) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the owner user SID facet (fOSi).

pub fn owner_group_sid( &mut self, value: impl Into<Option<OwnerGroupSid>>, ) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the owner group SID facet (fGSi).

pub fn permission_mode( &mut self, value: impl Into<Option<PermissionMode>>, ) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the POSIX permission mode facet (fMOd).

pub fn link_target_type( &mut self, link_target_type: impl Into<Option<LinkTargetType>>, ) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_*

Sets the link target type for link entries.

Combined with DataKind, this determines the link type:

• SymbolicLink + File → file symlink
• SymbolicLink + Directory → directory symlink
• HardLink + File → file hard link
• HardLink + Directory → directory hard link

pub fn file_size(&mut self, store: bool) -> &mut Self

👎Deprecated since 0.36.0:

renamed to store_file_size

Sets whether to store the raw file size in the entry metadata.

When true, the raw file size is recorded; when false, it is omitted.

pub fn store_file_size(&mut self, store: bool) -> &mut Self

Sets whether to store the raw file size in the entry metadata.

The size is recorded only for entries whose data kind is DataKind::FILE. When true (the default), the raw file size is recorded for such entries; when false, it is omitted.

pub fn add_xattr(&mut self, xattr: ExtendedAttribute) -> &mut Self

👎Deprecated since 0.36.0:

use OpaqueEntryBuilder::metadata with Metadata::with_xattrs

Adds an ExtendedAttribute to the entry.

pub fn add_extra_chunk<T: Into<RawChunk>>(&mut self, chunk: T) -> &mut Self

Adds extra chunk to the entry.

pub fn max_chunk_size(&mut self, size: NonZeroU32) -> &mut Self

Sets the maximum chunk size for data written to this entry.

The default is the maximum allowed chunk size (~4GB).

Examples

use std::num::NonZeroU32;
use libpna::{OpaqueEntryBuilder, DataKind, WriteOptions};

let mut builder =
    OpaqueEntryBuilder::new_with_options("data.bin".into(), DataKind::FILE, WriteOptions::store())?;
builder.max_chunk_size(NonZeroU32::new(1024 * 1024).unwrap()); // 1MB chunks
builder.write_all(b"file content")?;
let entry = builder.build()?;

pub fn build(self) -> Result<NormalEntry>

Consumes this builder and returns the constructed NormalEntry.

Errors

Returns an error if an I/O error occurs while building entry into buffer.

Trait Implementations

impl Write for OpaqueEntryBuilder

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.