Small, caller-owned EXIF documents and borrowed metadata views. More...
Data Structures | |
| struct | exif_value |
| Borrowed bytes plus enough type information for safe interpretation. More... | |
| struct | exif_view |
| Borrowed view of a validated APP1 payload. More... | |
| struct | exif_item |
| Writer bookkeeping for one field inside the document's value storage. More... | |
| struct | exif_document |
| Caller-owned bounded writer with no heap allocation. More... | |
Macros | |
| #define | EXIF_MAX_PAYLOAD 65533U |
| APP1 payload ceiling: the JPEG length includes its own two bytes. | |
| #define | EXIF_MAX_ENTRIES 48U |
| Writer entry budget, including the standard initialization tags. | |
Typedefs | |
| typedef bool(* | exif_tag_selector) (void *context, enum exif_directory directory, uint16_t tag) |
| Caller policy for additional, directory-local fields to import. | |
Functions | |
| int | exif_parse (struct exif_view *view, const unsigned char *payload, size_t size) |
| Validate an EXIF APP1 payload and create a borrowed view. | |
| bool | exif_get (const struct exif_view *view, enum exif_directory directory, uint16_t tag, struct exif_value *value) |
| Look up a directory-local tag without copying its bytes. | |
| bool | exif_value_unsigned (const struct exif_value *value, size_t index, uint32_t *result) |
| Decode one BYTE, SHORT or LONG component without an unaligned load. | |
| bool | exif_value_rational (const struct exif_value *value, size_t index, double *result) |
| Decode one unsigned or signed rational component as a double. | |
| size_t | exif_text_length (const struct exif_value *value) |
| Count text bytes after trimming trailing NUL padding only. | |
| void | exif_document_init (struct exif_document *document) |
| Start a fresh upright sRGB/Y-Cb-Cr document with EXIF 2.32 defaults. | |
| bool | exif_document_get (const struct exif_document *document, enum exif_directory directory, uint16_t tag, struct exif_value *value) |
| Borrow a field from the current writable document. | |
| int | exif_document_import (struct exif_document *document, const struct exif_view *view) |
| Rebuild a writable document from supported Sensoraia fields. | |
| int | exif_document_import_custom (struct exif_document *document, const struct exif_view *view, exif_tag_selector select, void *context) |
| Import standard fields plus additional tags selected by the caller. | |
| int | exif_document_remove (struct exif_document *document, enum exif_directory directory, uint16_t tag) |
| Remove a tag and reclaim its packed value storage. | |
| unsigned char * | exif_document_reserve (struct exif_document *document, enum exif_directory directory, uint16_t tag, enum exif_format format, uint32_t count) |
| Create or replace a field with zeroed, bounded value storage. | |
| int | exif_document_ascii (struct exif_document *document, enum exif_directory directory, uint16_t tag, const char *text) |
| Replace an ASCII field, including its terminating NUL byte. | |
| int | exif_document_rational (struct exif_document *document, enum exif_directory directory, uint16_t tag, uint32_t numerator, uint32_t denominator) |
| Store an unsigned measurement as an exact numerator/denominator pair. | |
| void | exif_encode_short (unsigned char *data, uint16_t value) |
| Encode a 16-bit value in the writer's little-endian representation. | |
| void | exif_encode_long (unsigned char *data, uint32_t value) |
| Encode a 32-bit value in the writer's little-endian representation. | |
| int | exif_serialize (const struct exif_document *document, unsigned char *payload, size_t capacity, size_t *size) |
| Serialize a document into one complete EXIF APP1 payload. | |
| int | exif_read_jpeg (const char *filename, unsigned char *payload, size_t capacity, size_t *size) |
| Read the single EXIF APP1 segment before the first JPEG scan. | |
| int | exif_read_stream (FILE *input, unsigned char *payload, size_t capacity, size_t *size) |
| Read capture EXIF from an already-open JPEG without reopening its path. | |
| int | exif_jpeg_dimensions (FILE *input, uint32_t *width, uint32_t *height, unsigned *components) |
| Inspect the frame header without allocating or decoding image pixels. | |
| int | exif_rewrite_jpeg (FILE *input, FILE *output, const unsigned char *payload, size_t size) |
| Stream a JPEG with one new EXIF segment instead of its old EXIF records. | |
| int | exif_update_jpeg (FILE *file, const unsigned char *payload, size_t size) |
| Replace EXIF in a regular JPEG file without a temporary file. | |
Detailed Description
Small, caller-owned EXIF documents and borrowed metadata views.
Use separate storage for concurrent operations. The core has no mutable global state; sharing a document or stream still needs caller-side synchronization. File publication and path ownership belong to image_exif.c.
Macro Definition Documentation
◆ EXIF_MAX_ENTRIES
| #define EXIF_MAX_ENTRIES 48U |
◆ EXIF_MAX_PAYLOAD
| #define EXIF_MAX_PAYLOAD 65533U |
Typedef Documentation
◆ exif_tag_selector
| typedef bool(* exif_tag_selector) (void *context, enum exif_directory directory, uint16_t tag) |
Enumeration Type Documentation
◆ exif_directory
| enum exif_directory |
◆ exif_format
| enum exif_format |
TIFF field-type numbers used by Sensoraia's metadata.
These are wire-format identifiers; do not renumber them. RATIONAL and SRATIONAL each store a numerator and denominator, not a floating value.
| Enumerator | |
|---|---|
| EXIF_BYTE | |
| EXIF_ASCII | |
| EXIF_SHORT | |
| EXIF_LONG | |
| EXIF_RATIONAL | |
| EXIF_UNDEFINED | |
| EXIF_SLONG | |
| EXIF_SRATIONAL | |
◆ exif_tag
| enum exif_tag |
Standard tag identifiers used by the current applications.
GPS identifiers deliberately reuse small numbers: the directory argument distinguishes GPS tags from primary and camera tags.
Function Documentation
◆ exif_document_ascii()
| int exif_document_ascii | ( | struct exif_document * | document, |
| enum exif_directory | directory, | ||
| uint16_t | tag, | ||
| const char * | text ) |
Replace an ASCII field, including its terminating NUL byte.
- Parameters
-
[in,out] document Initialized writable document. [in] directory Destination directory. [in] tag Directory-local ASCII tag identifier. [in] text Accessible NUL-terminated text outside the document storage.
- Returns
- Zero on success, otherwise -1 with errno set to EINVAL or ENOSPC.
Scanning and copying are bounded by the APP1 limit. This stores bytes; callers are responsible for supplying text appropriate to an ASCII EXIF tag.
◆ exif_document_get()
| bool exif_document_get | ( | const struct exif_document * | document, |
| enum exif_directory | directory, | ||
| uint16_t | tag, | ||
| struct exif_value * | value ) |
Borrow a field from the current writable document.
- Parameters
-
[in] document Initialized document that remains unchanged during the read. [in] directory Directory containing the desired tag. [in] tag Directory-local tag identifier. [out] value Borrowed little-endian field descriptor.
- Returns
- True when the field is available, otherwise false.
- Warning
- Copy needed source bytes elsewhere before any document mutation.
◆ exif_document_import()
| int exif_document_import | ( | struct exif_document * | document, |
| const struct exif_view * | view ) |
Rebuild a writable document from supported Sensoraia fields.
- Parameters
-
[out] document Caller-owned destination; previous contents are replaced. [in] view Validated borrowed view with nonoverlapping backing storage.
- Returns
- Zero on success, otherwise -1 with errno set to EINVAL.
Import starts from standard defaults, copies only the supported tag set and normalizes numeric byte order. It intentionally drops thumbnails, MakerNotes and unknown fields instead of promising unsafe vendor preservation.
- Note
- Invalid arguments leave the document untouched. If copying has begun and fails, the document is reset to defaults, not left partially imported.
◆ exif_document_import_custom()
| int exif_document_import_custom | ( | struct exif_document * | document, |
| const struct exif_view * | view, | ||
| exif_tag_selector | select, | ||
| void * | context ) |
Import standard fields plus additional tags selected by the caller.
- Parameters
-
document Destination with the same ownership/rollback rules as exif_document_import. view Validated source with nonoverlapping backing storage. select Optional selector for additional fields; NULL uses standard policy only. context Borrowed selector state, or NULL.
- Returns
- Zero on success, otherwise -1; an interrupted import resets to defaults.
Numeric values are normalized to little-endian; opaque bytes are unchanged. The caller owns custom tag meaning and relocation safety. Do not select vendor pointer structures or MakerNotes containing hidden TIFF offsets. There is no registration, global policy or retained callback state.
◆ exif_document_init()
| void exif_document_init | ( | struct exif_document * | document | ) |
Start a fresh upright sRGB/Y-Cb-Cr document with EXIF 2.32 defaults.
- Parameters
-
[out] document Caller-owned writer storage; NULL is ignored.
Standard housekeeping tags help ordinary EXIF readers interpret the result. Initialization deliberately invents no camera pose, capture time or image dimensions. Set actual dimensions and component configuration from the JPEG header before publication; grayscale needs a one-component configuration.
- Warning
- Reinitialization discards previous tags and invalidates borrowed values.
◆ exif_document_rational()
| int exif_document_rational | ( | struct exif_document * | document, |
| enum exif_directory | directory, | ||
| uint16_t | tag, | ||
| uint32_t | numerator, | ||
| uint32_t | denominator ) |
Store an unsigned measurement as an exact numerator/denominator pair.
- Parameters
-
[in,out] document Initialized writable document. [in] directory Destination directory. [in] tag Directory-local RATIONAL tag identifier. [in] numerator Unsigned numerator in the tag's chosen units. [in] denominator Nonzero scale, such as 1000 for millimeter precision.
- Returns
- Zero on success, otherwise -1 with errno set to EINVAL or ENOSPC.
Keeping the integer pair avoids an unnecessary floating-point round trip. Use reservation plus integer encoders for signed rational fields.
◆ exif_document_remove()
| int exif_document_remove | ( | struct exif_document * | document, |
| enum exif_directory | directory, | ||
| uint16_t | tag ) |
Remove a tag and reclaim its packed value storage.
- Parameters
-
[in,out] document Initialized writable document. [in] directory Directory containing the tag. [in] tag Directory-local identifier to remove.
- Returns
- Zero on removal or an absent tag, otherwise -1 with errno set to EINVAL.
Compaction avoids storage growth when applications repeatedly replace provenance records. Treat earlier borrowed pointers as invalid afterwards.
◆ exif_document_reserve()
| unsigned char * exif_document_reserve | ( | struct exif_document * | document, |
| enum exif_directory | directory, | ||
| uint16_t | tag, | ||
| enum exif_format | format, | ||
| uint32_t | count ) |
Create or replace a field with zeroed, bounded value storage.
- Parameters
-
[in,out] document Initialized writable document. [in] directory Destination directory. [in] tag Directory-local tag; structural directory pointers are reserved. [in] format TIFF representation for the value. [in] count Positive component count, not a byte length.
- Returns
- Writable value bytes, or NULL with errno set to EINVAL or ENOSPC.
Capacity is checked before removing the old field, so an ordinary capacity failure retains it. Fill numeric components in little-endian order, terminate ASCII and supply nonzero rational denominators before serialization.
- Warning
- Reservation can move existing values. Do not use old borrowed bytes as a source afterwards. The returned pointer is borrowed until the next mutation.
- See also
- exif_encode_short
- exif_encode_long
◆ exif_encode_long()
| void exif_encode_long | ( | unsigned char * | data, |
| uint32_t | value ) |
Encode a 32-bit value in the writer's little-endian representation.
- Parameters
-
[out] data At least four writable bytes, normally reserved field storage. [in] value Unsigned value or the bit representation of a signed component.
- Precondition
- The caller has already checked the pointer and available capacity.
Signed rational callers may convert int32_t to uint32_t before encoding; that conversion preserves the required modulo-2^32 representation.
◆ exif_encode_short()
| void exif_encode_short | ( | unsigned char * | data, |
| uint16_t | value ) |
Encode a 16-bit value in the writer's little-endian representation.
- Parameters
-
[out] data At least two writable bytes, normally reserved field storage. [in] value Unsigned value to encode.
- Precondition
- The caller has already checked the pointer and available capacity.
Byte stores work on unaligned addresses and on either host byte order.
◆ exif_get()
| bool exif_get | ( | const struct exif_view * | view, |
| enum exif_directory | directory, | ||
| uint16_t | tag, | ||
| struct exif_value * | value ) |
Look up a directory-local tag without copying its bytes.
- Parameters
-
[in] view View returned by exif_parse(), with unchanged backing storage. [in] directory Directory in which to look for the tag. [in] tag Standard tag identifier within that directory. [out] value Borrowed field descriptor; use it only when true is returned.
- Returns
- True when a valid value is available, otherwise false.
Lookup accepts unsorted input directories because external camera metadata need not share our writer's ordering. Missing tags are normal.
◆ exif_jpeg_dimensions()
| int exif_jpeg_dimensions | ( | FILE * | input, |
| uint32_t * | width, | ||
| uint32_t * | height, | ||
| unsigned * | components ) |
Inspect the frame header without allocating or decoding image pixels.
- Parameters
-
[in,out] input Readable stream positioned at the JPEG start-of-image marker. [out] width Actual frame width in pixels, zero on failure with valid arguments. [out] height Actual frame height in pixels, zero on failure with valid arguments. [out] components Actual frame component count, from one through four.
- Returns
- Zero on success, otherwise -1 with errno set to EINVAL or EFBIG.
Frame dimensions, not old EXIF tags, describe the compressed image. Buffered reads may advance past the inspected header; rewind before reuse.
- Precondition
- Use distinct output variables; all must be valid writable pointers.
- Note
- No scan data is decoded. Delayed-height frames are outside this interface.
◆ exif_parse()
| int exif_parse | ( | struct exif_view * | view, |
| const unsigned char * | payload, | ||
| size_t | size ) |
Validate an EXIF APP1 payload and create a borrowed view.
- Parameters
-
[out] view Destination view; cleared on failure when non-NULL. [in] payload Complete APP1 payload starting with the six-byte EXIF signature. [in] size Accessible payload bytes, at most EXIF_MAX_PAYLOAD.
- Returns
- Zero on success, otherwise -1 with errno set to EINVAL.
Validation happens before exposing a usable view. This rejects invalid offsets, duplicate tags, overlapping directory tables, malformed ASCII and zero rational denominators. Thumbnail and vendor pointers are not followed: they add complexity without serving Sensoraia's metadata needs.
- Precondition
- The destination view must not overlap the source payload.
- Note
- Structural validity does not establish the physical meaning of a tag.
- See also
- exif_get
◆ exif_read_jpeg()
| int exif_read_jpeg | ( | const char * | filename, |
| unsigned char * | payload, | ||
| size_t | capacity, | ||
| size_t * | size ) |
Read the single EXIF APP1 segment before the first JPEG scan.
- Parameters
-
[in] filename NUL-terminated path to a readable JPEG. [out] payload Caller-owned writable payload buffer. [in] capacity Available bytes in the payload buffer. [out] size Payload length on success, otherwise zero when non-NULL.
- Returns
- Zero on success, otherwise -1 with errno describing the failure.
Metadata lookup stops before compressed image data to keep reads cheap. Duplicate EXIF is rejected rather than guessing which record is authoritative. Header work is bounded by marker and segment-byte limits.
- Precondition
- The size output must not overlap the payload buffer.
- Note
- ENODATA means no EXIF; ENOSPC means insufficient output space. Structural errors use EINVAL and excessive segment bytes use EFBIG. File errors are also possible.
- Warning
- This extracts bytes, not a validated TIFF view or a fully validated JPEG. Call exif_parse() before interpreting the payload; ignore its contents on failure.
◆ exif_read_stream()
| int exif_read_stream | ( | FILE * | input, |
| unsigned char * | payload, | ||
| size_t | capacity, | ||
| size_t * | size ) |
Read capture EXIF from an already-open JPEG without reopening its path.
- Parameters
-
input Borrowed readable stream positioned at SOI; position changes. payload Caller-owned bounded output, nonoverlapping with size. capacity Available payload bytes. size Payload length on success; zero on failure when writable.
- Returns
- Zero on success; -1 with errno, including ENODATA for absent EXIF.
The caller owns rewind, file-identity checks and closing.
◆ exif_rewrite_jpeg()
| int exif_rewrite_jpeg | ( | FILE * | input, |
| FILE * | output, | ||
| const unsigned char * | payload, | ||
| size_t | size ) |
Stream a JPEG with one new EXIF segment instead of its old EXIF records.
- Parameters
-
[in,out] input Readable stream positioned at JPEG start-of-image. [in,out] output Distinct writable stream for the replacement JPEG. [in] payload Complete, valid EXIF APP1 payload outside both stream buffers. [in] size Accessible payload byte count, at most EXIF_MAX_PAYLOAD.
- Returns
- Zero on successful streaming, otherwise -1 with errno set to EINVAL or EIO.
Unrelated segments, marker fill bytes and compressed bytes are retained. Framing is checked through end-of-image without a full-image buffer, so entropy decoding, pixel validity and camera-specific metadata are intentionally separate.
- Precondition
- Input and output must refer to different underlying files as well as different streams.
- Warning
- Failure can leave partial output: discard it, never publish it. Success does not flush, sync, close or rename the destination; publication belongs to the caller.
- See also
- image_exif_write_complete
◆ exif_serialize()
| int exif_serialize | ( | const struct exif_document * | document, |
| unsigned char * | payload, | ||
| size_t | capacity, | ||
| size_t * | size ) |
Serialize a document into one complete EXIF APP1 payload.
- Parameters
-
[in] document Initialized, fully populated writable document. [out] payload Writable storage outside the document, starting at the EXIF signature. [in] capacity Available bytes in payload.[out] size Published payload length; zero on failure with valid, distinct storage.
- Returns
- Zero on success, otherwise -1 with errno set to EINVAL or ENOSPC.
Validation and sizing finish before output bytes are written. Directory overhead and alignment must fit APP1 too, not just the document's value storage. Input entries are not reordered; a bounded index table controls wire ordering.
- Precondition
- The size output must not overlap the document or payload. Invalid alias arguments are rejected without clearing that output, to avoid corrupting input.
◆ exif_text_length()
| size_t exif_text_length | ( | const struct exif_value * | value | ) |
Count text bytes after trimming trailing NUL padding only.
- Parameters
-
[in] value ASCII or UNDEFINED field descriptor.
- Returns
- Trimmed byte length, or zero for absent/unsupported values.
Embedded NULs and the UserComment encoding prefix are retained. This is a byte-length helper, not a character decoder or strlen replacement.
◆ exif_update_jpeg()
| int exif_update_jpeg | ( | FILE * | file, |
| const unsigned char * | payload, | ||
| size_t | size ) |
Replace EXIF in a regular JPEG file without a temporary file.
- Parameters
-
[in,out] file Read/write binary stream positioned at byte zero. [in] payload Complete valid EXIF APP1 payload outside the stream buffers. [in] size Accessible payload byte count, at most EXIF_MAX_PAYLOAD.
- Returns
- Zero on success, otherwise -1 with errno set.
The entire framing is validated before mutation. Bounded block moves retain compressed bytes, unrelated markers and trailing data. Equal-size spans are not rewritten. No JPEG-sized memory or disk copy is created.
- Precondition
- The caller exclusively owns the file and any hard-linked aliases.
- Warning
- Not atomic: write failures or interruption after mutation starts can leave a damaged JPEG. Success flushes but does not sync or close the file.
◆ exif_value_rational()
| bool exif_value_rational | ( | const struct exif_value * | value, |
| size_t | index, | ||
| double * | result ) |
Decode one unsigned or signed rational component as a double.
- Parameters
-
[in] value RATIONAL or SRATIONAL field descriptor. [in] index Zero-based rational index; each rational occupies eight bytes. [out] result Numerator divided by denominator; unchanged on failure.
- Returns
- True for a valid component with a nonzero denominator, otherwise false.
Signed conversion handles the full 32-bit range without relying on implementation-defined unsigned-to-signed integer casts.
◆ exif_value_unsigned()
| bool exif_value_unsigned | ( | const struct exif_value * | value, |
| size_t | index, | ||
| uint32_t * | result ) |
Decode one BYTE, SHORT or LONG component without an unaligned load.
- Parameters
-
[in] value Borrowed field descriptor from a lookup. [in] index Zero-based component index, not a byte offset. [out] result Decoded unsigned value; unchanged on failure.
- Returns
- True for a supported, in-bounds component, otherwise false.