Crate xdg_thumbnail

Expand description

Freedesktop thumbnail cache primitives.

The library exposes typed helpers for resolving the personal thumbnail cache, constructing canonical original identities, validating existing thumbnails, and atomically installing caller-rendered thumbnail PNGs.

use xdg_thumbnail::{
    PersonalCacheRoot, PersonalThumbnailLookup, ReadablePersonalOriginalIdentity, ThumbnailSize,
};

fn main() -> xdg_thumbnail::Result<()> {
    let root = PersonalCacheRoot::resolve_from_env()?;
    let original = ReadablePersonalOriginalIdentity::from_local_path("/home/alice/Pictures/photo.png")?;

    match root.lookup_thumbnail_png_bytes(&original, ThumbnailSize::Normal)? {
        PersonalThumbnailLookup::Valid(entry) => {
            let _png_bytes = entry.png_bytes();
        }
        PersonalThumbnailLookup::Missing | PersonalThumbnailLookup::Invalid(_) => {}
    }

    Ok(())
}

Owned request types make it straightforward to wrap blocking filesystem work in an async runtime without adding a runtime dependency to this crate. Request constructors perform no filesystem I/O, but local original identity construction does, so build local identities inside the same blocking adapter.

use xdg_thumbnail::{
    PersonalCacheRoot, PersonalThumbnailInstallRequest, ReadablePersonalOriginalIdentity, ThumbnailSize,
};

fn spawn_blocking<F, R>(operation: F) -> R
where
    F: FnOnce() -> R + Send + 'static,
    R: Send + 'static,
{
    operation()
}

fn render_thumbnail_png() -> Vec<u8> {
    unimplemented!("return PNG bytes produced by the caller's renderer")
}

fn main() -> xdg_thumbnail::Result<()> {
    let root = PersonalCacheRoot::resolve_from_env()?;
    let rendered_png = render_thumbnail_png();

    let installed = spawn_blocking(move || {
        let original =
            ReadablePersonalOriginalIdentity::from_local_path("/home/alice/Pictures/photo.png")?;
        let request = PersonalThumbnailInstallRequest::new(
            root,
            original,
            ThumbnailSize::Normal,
            rendered_png,
        );
        request.install_png_bytes()
    })?;
    let _path = installed.path();

    Ok(())
}

Structs§

CacheEntryHandle: A handle for a discovered cache entry.
CacheEntryInspection: Policy-neutral inspection facts for a cache entry.
CacheEntryInspectionParts: Owned parts of CacheEntryInspection.
DisplayThumbnailRgba8LookupEntry: Decoded display RGBA8 pixels from an exact or larger validated cache PNG.
DisplayThumbnailRgba8LookupEntryParts: Owned parts of DisplayThumbnailRgba8LookupEntry.
FailureEntryInspectionRequest: Owned failure-entry inspection request for async or runtime-specific adapters.
FailureEntryInspectionRequestParts: Owned parts of FailureEntryInspectionRequest.
FailureEntryWriteRequest: Owned failure-entry write request for async or runtime-specific adapters.
FailureEntryWriteRequestParts: Owned parts of FailureEntryWriteRequest.
FailureNamespace: A validated direct directory name for failure entries.
InstalledThumbnailPath: Path result of a successful personal-cache install or failure-entry write.
InstalledThumbnailPngBytes: PNG bytes result of a successful personal-cache install or failure-entry write.
InstalledThumbnailPngBytesParts: Owned parts of InstalledThumbnailPngBytes.
MaterializedThumbnailPath: Path result of explicit fallback materialization into the personal cache.
MaterializedThumbnailPathParts: Owned parts of MaterializedThumbnailPath.
MaterializedThumbnailPngBytes: PNG bytes result of explicit fallback materialization into the personal cache.
MaterializedThumbnailPngBytesParts: Owned parts of MaterializedThumbnailPngBytes.
OwnedRawThumbnailImage: Owned raw rendered thumbnail pixels.
OwnedRawThumbnailImageParts: Owned parts of OwnedRawThumbnailImage.
ParsedThumbnailPng: Decoded facts from a thumbnail PNG.
ParsedThumbnailPngParts: Owned parts of ParsedThumbnailPng.
PersonalCacheRoot: Root directory of the personal thumbnail cache, usually $XDG_CACHE_HOME/thumbnails.
PersonalOriginalIdentity: Canonical personal URI plus original freshness and write facts needed for validation and writes.
PersonalOriginalUri: A canonical absolute URI identity for entries in the personal thumbnail cache.
PersonalThumbnailInspectionRequest: Owned personal-cache inspection request for async or runtime-specific adapters.
PersonalThumbnailInspectionRequestParts: Owned parts of PersonalThumbnailInspectionRequest.
PersonalThumbnailInstallRequest: Owned personal-cache install request for async or runtime-specific adapters.
PersonalThumbnailInstallRequestParts: Owned parts of PersonalThumbnailInstallRequest.
PersonalThumbnailLookupRequest: Owned personal-cache lookup request for async or runtime-specific adapters.
PersonalThumbnailLookupRequestParts: Owned parts of PersonalThumbnailLookupRequest.
PersonalThumbnailMaterializationRequest: Owned personal-cache fallback materialization request for async or runtime-specific adapters.
PersonalThumbnailMaterializationRequestParts: Owned parts of PersonalThumbnailMaterializationRequest.
PersonalThumbnailRawInstallRequest: Owned personal-cache raw install request for async or runtime-specific adapters.
PersonalThumbnailRawInstallRequestParts: Owned parts of PersonalThumbnailRawInstallRequest.
RawThumbnailImage: Borrowed raw rendered thumbnail pixels.
ReadablePersonalOriginalIdentity: An original identity whose source has been confirmed readable by the caller.
SharedCacheEntryInspection: Read-only inspection facts for an existing shared thumbnail repository entry.
SharedCacheEntryInspectionParts: Owned parts of SharedCacheEntryInspection.
SharedOriginalFacts: Shared-repository lookup facts, including the metadata acceptance policy.
SharedOriginalMetadata: Policy-neutral original freshness facts for shared-repository validation and inspection.
SharedRelativeOriginalUri: A canonical ./-prefixed URI identity for direct children in shared repositories.
SharedRepositoryContext: Explicit context for read-only shared repository lookup.
SharedThumbnailInspectionRequest: Owned shared-repository inspection request for async or runtime-specific adapters.
SharedThumbnailInspectionRequestParts: Owned parts of SharedThumbnailInspectionRequest.
SharedThumbnailLookupRequest: Owned shared-repository lookup request for async or runtime-specific adapters.
SharedThumbnailLookupRequestParts: Owned parts of SharedThumbnailLookupRequest.
SharedToPersonalThumbnailMaterializationRequest: Owned shared-to-personal fallback materialization request for async adapters.
SharedToPersonalThumbnailMaterializationRequestParts: Owned parts of SharedToPersonalThumbnailMaterializationRequest.
ThumbnailMetadata: Freedesktop thumbnail PNG text metadata.
ThumbnailMetadataProblem: Key-specific thumbnail metadata problem.
ThumbnailPathLookupEntry: A validated cache path and metadata facts.
ThumbnailPathLookupEntryParts: Owned parts of ThumbnailPathLookupEntry.
ThumbnailPngBytesLookupEntry: Exact validated PNG bytes and metadata facts.
ThumbnailPngBytesLookupEntryParts: Owned parts of ThumbnailPngBytesLookupEntry.
ThumbnailRgba8LookupEntry: Decoded tightly packed RGBA8 pixels and metadata facts from a validated cache PNG.
ThumbnailRgba8LookupEntryParts: Owned parts of ThumbnailRgba8LookupEntry.
ThumbnailTimestamps: Timestamp facts captured for a thumbnail cache entry.
UnixMtimeSeconds: Whole Unix epoch seconds used by Thumb::MTime.

Enums§

AccessTimePreservation: Whether access time was preserved while inspecting an entry.
CacheDirectoryProblem: Privacy or type problem found in an existing personal-cache directory.
CacheEntryInspectionOutcome: Validation confidence and validity for policy-neutral cache inspection.
CacheEntryProblem: Policy-neutral problem found while validating or inspecting a cache entry.
CacheNamespace: A successful-thumbnail size namespace or a program failure namespace.
CachePathProblem: Problem found in an explicitly supplied cache entry path.
CacheRootProblem: Problem found in an explicitly supplied cache root path.
NonstandardEntryPolicy: Policy for nonstandard filenames discovered during personal-cache inspection.
OriginalUriIdentity: Original URI identity parsed from a cache entry.
PersonalThumbnailLookup: Result of a validated personal thumbnail cache lookup.
PersonalValidationOutcome: Validation confidence and validity for a personal-cache entry.
RawThumbnailPixelFormat: Explicit raw pixel format accepted by raw thumbnail install APIs.
SharedCacheEntryOutcome: Validation state for a shared cache entry inspection.
SharedThumbnailLookup: Result of a validated shared thumbnail repository lookup.
SharedThumbnailMetadataPolicy: Metadata acceptance policy for shared-repository thumbnail lookups.
SharedValidationOutcome: Validation confidence and validity for a shared-repository entry.
ThumbnailError: Errors returned by thumbnail cache identity and filesystem operations.
ThumbnailMetadataKey: Standard thumbnail metadata key involved in a validation or inspection problem.
ThumbnailMetadataProblemKind: Kind of problem found for a standard thumbnail metadata key.
ThumbnailPngBitDepth: PNG sample bit depth reported by ParsedThumbnailPng.
ThumbnailPngColorType: PNG color type reported by ParsedThumbnailPng.
ThumbnailSize: A standard Freedesktop thumbnail size directory.

Functions§

validate_personal_failure_entry: Validates a personal-cache failure entry PNG against a readable original identity.
validate_personal_thumbnail: Validates a personal-cache successful thumbnail PNG against a readable original identity.
validate_shared_thumbnail: Validates a shared-repository successful thumbnail PNG against explicit shared context and policy-neutral original metadata facts.

Type Aliases§

Result: Result type used by this crate.