Function definitions for ID3v2 frame lifecycle, traversal, serialization, and content management. More...

#include "id3v2Types.h"

Include dependency graph for id3v2Frame.h:

This graph shows which files directly or indirectly include this file:

Functions
Id3v2FrameHeader *	id3v2CreateFrameHeader (uint8_t id[ID3V2_FRAME_ID_MAX_SIZE], bool tagAlter, bool fileAlter, bool readOnly, bool unsync, uint32_t decompressionSize, uint8_t encryptionSymbol, uint8_t groupSymbol)
	Creates an ID3v2 frame header structure with specified flags and metadata.
void	id3v2DestroyFrameHeader (Id3v2FrameHeader **toDelete)
	Frees all memory allocated for a frame header and nullifies the pointer.
Id3v2ContentEntry *	id3v2CreateContentEntry (void *entry, size_t size)
	Creates a content entry structure with a deep copy of the provided data.
void	id3v2DeleteContentEntry (void *toBeDeleted)
	Frees all memory allocated for a content entry structure.
int	id3v2CompareContentEntry (const void first, const void second)
	Compares two content entries byte-by-byte and returns the difference.
char *	id3v2PrintContentEntry (const void *toBePrinted)
	Generates a string representation of a content entry for debugging.
void *	id3v2CopyContentEntry (const void *toBeCopied)
	Creates a deep copy of a content entry.
void	id3v2DeleteFrame (void *toBeDeleted)
	Frees all memory allocated for an ID3v2 frame structure.
int	id3v2CompareFrame (const void first, const void second)
	Performs deep comparison of two ID3v2 frame structures.
char *	id3v2PrintFrame (const void *toBePrinted)
	Generates a string representation of a frame for debugging.
void *	id3v2CopyFrame (const void *toBeCopied)
	Creates a deep copy of an ID3v2 frame structure.
Id3v2Frame *	id3v2CreateFrame (Id3v2FrameHeader header, List context, List *entries)
	Creates an ID3v2 frame structure from provided components.
void	id3v2DestroyFrame (Id3v2Frame **toDelete)
	Frees all memory allocated for an ID3v2 frame structure and nullifies the pointer.
Id3v2Frame *	id3v2CreateEmptyFrame (const char id[ID3V2_FRAME_ID_MAX_SIZE], uint8_t version, HashTable *userPairs)
	Creates an empty frame structure with zero-initialized entries based on context lookup.
bool	id3v2CompareFrameId (const Id3v2Frame *frame, const char id[ID3V2_FRAME_ID_MAX_SIZE])
	Compares a frame's identifier with a provided ID string.
ListIter	id3v2CreateFrameTraverser (Id3v2Tag *tag)
	Creates a list iterator for traversing frames in an ID3v2 tag.
Id3v2Frame *	id3v2FrameTraverse (ListIter *traverser)
	Advances the iterator and returns the next frame in the list.
ListIter	id3v2CreateFrameEntryTraverser (Id3v2Frame *frame)
	Creates a list iterator for traversing content entries within a frame.
void *	id3v2ReadFrameEntry (ListIter traverser, size_t dataSize)
	Reads and returns a deep copy of the current entry's data, advancing the iterator.
char *	id3v2ReadFrameEntryAsChar (ListIter traverser, size_t dataSize)
	Reads a frame entry as a UTF-8 encoded string with escaped special characters, advancing the iterator.
uint8_t	id3v2ReadFrameEntryAsU8 (ListIter *traverser)
	Reads the first byte of the current entry as an 8-bit unsigned integer, advancing the iterator.
uint16_t	id3v2ReadFrameEntryAsU16 (ListIter *traverser)
	Reads the current entry as a 16-bit unsigned integer, advancing the iterator.
uint32_t	id3v2ReadFrameEntryAsU32 (ListIter *traverser)
	Reads the current entry as a 32-bit unsigned integer, advancing the iterator.
bool	id3v2WriteFrameEntry (Id3v2Frame frame, ListIter entries, size_t entrySize, const void *entry)
	Writes data to the entry at the iterator's current position, clamping size to context constraints.
bool	id3v2AttachFrameToTag (Id3v2Tag tag, Id3v2Frame frame)
	Inserts a frame at the end of a tag's frames list.
Id3v2Frame *	id3v2DetachFrameFromTag (Id3v2Tag tag, Id3v2Frame frame)
	Removes a frame from a tag's frames list and returns it to the caller.
uint8_t *	id3v2FrameHeaderSerialize (Id3v2FrameHeader header, uint8_t version, uint32_t frameSize, size_t outl)
	Serializes a frame header to binary format according to the specified ID3v2 version.
char *	id3v2FrameHeaderToJSON (const Id3v2FrameHeader *header, uint8_t version)
	Converts a frame header structure to its JSON representation based on ID3v2 version.
uint8_t *	id3v2FrameSerialize (Id3v2Frame frame, uint8_t version, size_t outl)
	Serializes a complete ID3v2 frame to binary format according to the specified version.
char *	id3v2FrameToJSON (Id3v2Frame *frame, uint8_t version)
	Converts a complete ID3v2 frame structure to its JSON representation.

Detailed Description

Function definitions for ID3v2 frame lifecycle, traversal, serialization, and content management.

Author: Ewan Jones

Version: 26.01

Date: 2024-04-11 - 2026-01-17

Copyright: Copyright (c) 2024 - 2026

Definition in file id3v2Frame.h.

Function Documentation

◆ id3v2AttachFrameToTag()

bool id3v2AttachFrameToTag	(	Id3v2Tag *	tag,
		Id3v2Frame *	frame )

Inserts a frame at the end of a tag's frames list.

Appends the provided frame to the back of the tag's frames list. Validates that the tag structure and frame structure are complete before insertion. Does not create a copy of the frame; the tag takes ownership of the frame pointer. Returns false if the tag is NULL, the frame is NULL, the tag's frames list is NULL, or any of the frame's required components (contexts, entries, header) are NULL.

Parameters

tag	- Tag structure to receive the frame
frame	- Frame to insert. Tag takes ownership of this pointer

Returns: bool - true on successful insertion, false on failure

Definition at line 953 of file id3v2Frame.c.

◆ id3v2CompareContentEntry()

int id3v2CompareContentEntry	(	const void *	first,
		const void *	second )

Compares two content entries byte-by-byte and returns the difference.

Performs lexicographic comparison of entry data up to the smaller of the two sizes. Size differences are ignored for compatibility with various ID3v2 tag writers (Jaikoz, iTunes, Mp3tag, Mp3diag, kid3) which write strings with different padding/termination. This design prioritizes data content over exact size matching.

Parameters

first	- First content entry to compare
second	- Second content entry to compare

Returns: int - 0 if entries are equal up to minimum size, positive if first > second, negative if first < second, or 1 if either parameter is NULL

Definition at line 145 of file id3v2Frame.c.

◆ id3v2CompareFrame()

int id3v2CompareFrame	(	const void *	first,
		const void *	second )

Performs deep comparison of two ID3v2 frame structures.

Compares all frame components including header fields (ID, flags, symbols), content entries, and contexts. Can be used as a callback for list comparison operations.

Parameters

first	- First frame to compare
second	- Second frame to compare

Returns: int - 0 if frames are equal, negative if first < second, positive if first > second

Definition at line 241 of file id3v2Frame.c.

◆ id3v2CompareFrameId()

bool id3v2CompareFrameId	(	const Id3v2Frame *	frame,
		const char	id[ID3V2_FRAME_ID_MAX_SIZE] )

Compares a frame's identifier with a provided ID string.

Performs byte-by-byte comparison of the frame's header ID against the provided ID array. Returns false if frame or frame header is NULL to ensure safe operation.

Parameters

frame	- Frame structure containing the ID to compare
id	- ID string array of ID3V2_FRAME_ID_MAX_SIZE bytes to compare against

Returns: bool - true if IDs match exactly, false if they differ or if frame/header is NULL

Definition at line 501 of file id3v2Frame.c.

◆ id3v2CopyContentEntry()

void * id3v2CopyContentEntry ( const void * toBeCopied )

Creates a deep copy of a content entry.

Duplicates a content entry by creating a new structure with independently allocated data. Can be used as a callback function for list copy operations.

Parameters

toBeCopied - Content entry to copy

Returns: void* - Heap allocated content entry containing a deep copy of the data with id3v2DeleteContentEntry()

Definition at line 196 of file id3v2Frame.c.

◆ id3v2CopyFrame()

void * id3v2CopyFrame ( const void * toBeCopied )

Creates a deep copy of an ID3v2 frame structure.

Duplicates all frame components including header, contexts, and entries with independently allocated memory. Can be used as a callback for list copy operations.

Parameters

toBeCopied - Frame to copy

Returns: void* - Heap allocated frame containing deep copies of all components

Definition at line 364 of file id3v2Frame.c.

◆ id3v2CreateContentEntry()

Id3v2ContentEntry * id3v2CreateContentEntry	(	void *	entry,
		size_t	size )

Creates a content entry structure with a deep copy of the provided data.

Allocates an Id3v2ContentEntry on the heap and performs a deep copy of the provided entry data. Content entries store individual field values within ID3v2 frames (e.g., encoding byte, text strings, binary data). If size is 0, creates an empty entry with NULL data.

Parameters

entry	- Pointer to data to copy into the content entry. Ignored if size is 0
size	- Size of data in bytes. If 0, creates empty entry with NULL data pointer

Returns: Id3v2ContentEntry * - Heap-allocated Id3v2ContentEntry containing a deep copy of the data

Definition at line 115 of file id3v2Frame.c.

◆ id3v2CreateEmptyFrame()

Id3v2Frame * id3v2CreateEmptyFrame	(	const char	id[ID3V2_FRAME_ID_MAX_SIZE],
		uint8_t	version,
		HashTable *	userPairs )

Creates an empty frame structure with zero-initialized entries based on context lookup.

Resolves frame context through cascading lookups: exact ID match in defaults, text frame fallback, URL frame fallback, and user-defined pairings, and finally a generic fallback. Creates entries initialized to single zero bytes according to the resolved context, skipping iterator contexts. Frame header is created with all flags disabled.

Parameters

id	- Frame identifier array of ID3V2_FRAME_ID_MAX_SIZE
version	- ID3v2 version for default context pairing lookup
userPairs	- Optional user-defined ID-to-context mappings

Returns: Id3v2Frame* - Heap allocated frame with zero-initialized entries, or NULL if id is NULL. Caller must free with id3v2DestroyFrame()

Definition at line 435 of file id3v2Frame.c.

◆ id3v2CreateFrame()

Id3v2Frame * id3v2CreateFrame	(	Id3v2FrameHeader *	header,
		List *	context,
		List *	entries )

Creates an ID3v2 frame structure from provided components.

Allocates a frame on the heap and assembles it from a header, contexts list, and entries list. The frame takes ownership of all provided components.

Parameters

header	- Frame header containing ID and flags
context	- List of content contexts defining entry structures
entries	- List of content entries containing frame data

Returns: Id3v2Frame* - Heap allocated Id3v2Frame structure. Caller must free with id3v2DestroyFrame()

Definition at line 391 of file id3v2Frame.c.

◆ id3v2CreateFrameEntryTraverser()

ListIter id3v2CreateFrameEntryTraverser ( Id3v2Frame * frame )

Creates a list iterator for traversing content entries within a frame.

Initializes an iterator for sequential access to content entries within a frame structure. Returns an empty iterator with NULL current pointer if the frame or its entries list is NULL, allowing safe iteration in all cases.

Parameters

frame - Frame structure containing the entries list to iterate over

Returns: ListIter - Iterator positioned at the start of the entries list, or empty iterator if frame/entries is NULL

Definition at line 563 of file id3v2Frame.c.

◆ id3v2CreateFrameHeader()

Id3v2FrameHeader * id3v2CreateFrameHeader	(	uint8_t	id[ID3V2_FRAME_ID_MAX_SIZE],
		bool	tagAlter,
		bool	fileAlter,
		bool	readOnly,
		bool	unsync,
		uint32_t	decompressionSize,
		uint8_t	encryptionSymbol,
		uint8_t	groupSymbol )

Creates an ID3v2 frame header structure with specified flags and metadata.

Allocates and initializes a frame header on the heap. The header contains a frame identifier and control flags for preservation (tag/file alter, read-only) and format (compression, encryption, grouping, unsynchronisation). Format flags are only used in ID3v2.3/2.4; they are ignored in v2.2 but can be set for forward compatibility.

Parameters

id	- Frame identifier array of ID3V2_FRAME_ID_MAX_SIZE. Examples: "TIT2", "TPE1", "APIC"
tagAlter	- Tag alter preservation flag meaning the tag should be preserved
fileAlter	- File alter preservation flag
readOnly	- Read-only flag
unsync	- Frame-level unsynchronisation flag (ID3v2.4 only, false sync signals removed)
decompressionSize	- Original uncompressed size in bytes (0 = no compression, ID3v2.3/2.4 only)
encryptionSymbol	- Encryption method symbol (0 = no encryption, ID3v2.3/2.4 only)
groupSymbol	- Group identifier for related frames (0 = no grouping, ID3v2.3/2.4 only)

Returns: Id3v2FrameHeader* - Heap-allocated Id3v2FrameHeader structure. Caller must free with id3v2DestroyFrameHeader

Definition at line 68 of file id3v2Frame.c.

◆ id3v2CreateFrameTraverser()

ListIter id3v2CreateFrameTraverser ( Id3v2Tag * tag )

Creates a list iterator for traversing frames in an ID3v2 tag.

Initializes an iterator for sequential access to frames within a tag structure. Returns an empty iterator with NULL current pointer if the tag or its frames list is NULL, allowing safe iteration in all cases.

Parameters

tag	- Tag structure containing the frames list to iterate over

Returns: ListIter - Iterator positioned at the start of the frames list, or empty iterator if tag/frames is NULL

Definition at line 524 of file id3v2Frame.c.

◆ id3v2DeleteContentEntry()

void id3v2DeleteContentEntry ( void * toBeDeleted )

Frees all memory allocated for a content entry structure.

Safely deallocates an Id3v2ContentEntry. Frees the internal data buffer if present, then the structure itself. Can be used as a callback for list deletion operations.

Parameters

toBeDeleted - Pointer to Id3v2ContentEntry to be freed

Definition at line 210 of file id3v2Frame.c.

◆ id3v2DeleteFrame()

void id3v2DeleteFrame ( void * toBeDeleted )

Frees all memory allocated for an ID3v2 frame structure.

Wrapper around id3v2DestroyFrame for use as a callback in list operations. Deallocates the frame header, contexts, entries, and the frame structure itself.

Parameters

toBeDeleted - Pointer to Id3v2Frame to be freed

Definition at line 226 of file id3v2Frame.c.

◆ id3v2DestroyFrame()

void id3v2DestroyFrame ( Id3v2Frame ** toDelete )

Frees all memory allocated for an ID3v2 frame structure and nullifies the pointer.

Completely deallocates a frame by freeing its contexts list, entries list, frame header, and the frame structure itself. Sets the pointer to NULL after freeing to prevent use-after-free errors. If the pointer is already NULL, no action is taken.

Parameters

toDelete - Pointer to frame pointer to be freed and nullified

Definition at line 409 of file id3v2Frame.c.

◆ id3v2DestroyFrameHeader()

void id3v2DestroyFrameHeader ( Id3v2FrameHeader ** toDelete )

Frees all memory allocated for a frame header and nullifies the pointer.

Safely deallocates a frame header structure created by id3v2CreateFrameHeader. Sets the pointer to NULL after freeing to prevent use-after-free errors. If the pointer is already NULL, no action is taken.

Parameters

toDelete - Pointer to frame header pointer to be freed and nullified

Definition at line 96 of file id3v2Frame.c.

◆ id3v2DetachFrameFromTag()

Id3v2Frame * id3v2DetachFrameFromTag	(	Id3v2Tag *	tag,
		Id3v2Frame *	frame )

Removes a frame from a tag's frames list and returns it to the caller.

Searches the tag's frames list for a matching frame, removes it from the list, and returns the frame pointer. Does not deallocate the frame; ownership transfers to the caller who must eventually free it with id3v2DestroyFrame(). Returns NULL if the tag is NULL, the frame is NULL, or the frame is not found in the tag's frames list.

Parameters

tag	- Tag structure containing the frame to remove
frame	- Frame to locate and remove from the tag

Returns: Id3v2Frame* - Pointer to the removed frame or NULL on failure

Definition at line 978 of file id3v2Frame.c.

◆ id3v2FrameHeaderSerialize()

uint8_t * id3v2FrameHeaderSerialize	(	Id3v2FrameHeader *	header,
		uint8_t	version,
		uint32_t	frameSize,
		size_t *	outl )

Serializes a frame header to binary format according to the specified ID3v2 version.

Converts a frame header structure into its binary representation following version-specific formats. v2.2 produces a 6-byte header. v2.3 and v2.4 produce 10+ byte headers with optional extended data fields. v2.4 uses syncsafe encoding for the frame size, extended data is conditionally appended when their values are non-zero. Returns NULL and sets outl to 0 if the header is NULL or version is invalid (greater than ID3V2_TAG_VERSION_4).

Parameters

header	- Frame header structure to serialize
version	- ID3v2 version (ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4)
frameSize	- Size of frame content in bytes (excludes header). Encoded as syncsafe in v2.4
outl	- Output parameter receiving the serialized header size in bytes, or 0 on failure

Returns: uint8_t* - Heap allocated binary header data. Caller must free. NULL on failure

Definition at line 1002 of file id3v2Frame.c.

◆ id3v2FrameHeaderToJSON()

char * id3v2FrameHeaderToJSON	(	const Id3v2FrameHeader *	header,
		uint8_t	version )

Converts a frame header structure to its JSON representation based on ID3v2 version.

Serializes frame header metadata into a JSON string with version-specific fields. v2.2 includes only the 3-character frame ID. v2.3 adds preservation flags, compression, encryption, and grouping metadata. v2.4 additionally includes the unsynchronisation flag. Returns an empty JSON object "{}" if the header is NULL or the version is unsupported.

Example outputs:

v2.2: {"id":"TIT"}
v2.3: {"id":"TIT2","tagAlterPreservation":false,"fileAlterPreservation":false,"readOnly":false,"decompressionSize":0,"encryptionSymbol":0,"groupSymbol":0}
v2.4: {"id":"TIT2","tagAlterPreservation":false,"fileAlterPreservation":false,"readOnly":false,"unsynchronisation":false,"decompressionSize":0,"encryptionSymbol":0,"groupSymbol":0}

Parameters

header	- Frame header structure to convert to JSON
version	- ID3v2 version (ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4)

Returns: char* - Heap allocated JSON string. Caller must free. Returns "{}" if header is NULL or version is unsupported

Definition at line 1136 of file id3v2Frame.c.

◆ id3v2FrameSerialize()

uint8_t * id3v2FrameSerialize	(	Id3v2Frame *	frame,
		uint8_t	version,
		size_t *	outl )

Serializes a complete ID3v2 frame to binary format according to the specified version.

Converts a frame structure into its binary representation by serializing the header and processing each content entry according to its context type. Handles encoding conversions (UTF-8, UTF-16LE/BE, Latin-1), null terminator insertion, bit-packing, and size adjustments. The serialization process iterates through frame contexts and applies type-specific transformations: encoded strings are converted to their target encoding with BOM prepending where required, binary/numeric data is written directly, bit contexts are packed into compact byte representations, and adjustment contexts modify data sizes dynamically. Returns NULL and sets outl to 0 if the frame is NULL, version is invalid (greater than ID3V2_TAG_VERSION_4), or memory allocation fails during processing.

Parameters

frame	- Frame structure containing header, contexts, and entries to serialize
version	- ID3v2 version (ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4)
outl	- Output parameter receiving the total serialized frame size in bytes (header + content), or 0 on failure

Returns: uint8_t* - Heap allocated binary frame data ready for writing to file. Caller must free. NULL on failure

This will go on forever until a failure condition is met by a previous context i.e latin1_context detects null

Definition at line 1260 of file id3v2Frame.c.

◆ id3v2FrameToJSON()

char * id3v2FrameToJSON	(	Id3v2Frame *	frame,
		uint8_t	version )

Converts a complete ID3v2 frame structure to its JSON representation.

Serializes frame metadata and content entries into a JSON object with header information and an array of content values. String entries are converted to UTF-8 with escaped special characters, binary data is base64-encoded, numeric values are represented as strings, and floating-point values are formatted with decimal precision. Returns an empty JSON object "{}" if the frame is NULL or version is invalid (greater than ID3V2_TAG_VERSION_4).

Example output for a TIT2 (title) frame in ID3v2.4:

{
  "header": {
    "id":"TIT2",
    "tagAlterPreservation":false,
    "fileAlterPreservation":false,
    "readOnly":false,
    "unsynchronisation":false,
    "decompressionSize":0,
    "encryptionSymbol":0,
    "groupSymbol":0
  },
  "content": [
    {"value":"3","size":1},
    {"value":"Beetlebum","size":9}
  ]
}

Parameters

frame	- Frame structure to convert to JSON
version	- ID3v2 version (ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4)

Returns: char* - Heap allocated JSON string. Caller must free. Returns "{}" if frame is NULL or version is invalid

Definition at line 1843 of file id3v2Frame.c.

◆ id3v2FrameTraverse()

Id3v2Frame * id3v2FrameTraverse ( ListIter * traverser )

Advances the iterator and returns the next frame in the list.

Wrapper around listIteratorNext that advances the iterator position and returns the current frame. Returns NULL when the end of the list is reached, indicating iteration is complete.

Parameters

traverser - List iterator to advance

Returns: Id3v2Frame* - Pointer to the next frame in the list, or NULL if at the end

Definition at line 549 of file id3v2Frame.c.

◆ id3v2PrintContentEntry()

char * id3v2PrintContentEntry ( const void * toBePrinted )

Generates a string representation of a content entry for debugging.

Creates a formatted string displaying the entry's data size and memory address. Can be used as a callback function for list printing operations. Caller must free the returned string.

Parameters

toBePrinted - Content entry to represent as a string

Returns: char* - Heap allocated string in format "Size: <size>, data: <address>\n"

Definition at line 175 of file id3v2Frame.c.

◆ id3v2PrintFrame()

char * id3v2PrintFrame ( const void * toBePrinted )

Generates a string representation of a frame for debugging.

Creates a formatted string displaying memory addresses of the frame's header, contexts, and entries. Can be used as a callback for list printing operations. Caller must free the returned string.

Parameters

toBePrinted - Frame to represent as a string

Returns: char* - Heap allocated string in format "header : <addr>, context : <addr>, entries : <addr>"

Definition at line 341 of file id3v2Frame.c.

◆ id3v2ReadFrameEntry()

void * id3v2ReadFrameEntry	(	ListIter *	traverser,
		size_t *	dataSize )

Reads and returns a deep copy of the current entry's data, advancing the iterator.

Retrieves the content entry at the iterator's current position and creates an independently allocated copy of its data. Advances the iterator to the next entry. Returns NULL and sets dataSize to 0 if the traverser is NULL, the current entry is NULL, or the entry has zero size.

Parameters

traverser	- Iterator positioned at the entry to read
dataSize	- Output parameter receiving the size of returned data in bytes, or 0 on failure

Returns: void* - Heap allocated copy of the entry data. Caller must free. NULL on failure

Definition at line 591 of file id3v2Frame.c.

◆ id3v2ReadFrameEntryAsChar()

char * id3v2ReadFrameEntryAsChar	(	ListIter *	traverser,
		size_t *	dataSize )

Reads a frame entry as a UTF-8 encoded string with escaped special characters, advancing the iterator.

Retrieves the content entry at the iterator's current position, automatically detects its encoding, and converts it to UTF-8. Strips UTF-8 BOM if present and escapes quotes and backslashes for JSON/C std compatibility. Advances the iterator to the next entry. Returns NULL and sets dataSize to 0 if the traverser is NULL, the current entry is NULL, memory allocation fails, or encoding conversion fails.

Parameters

traverser	- Iterator positioned at the entry to read and convert
dataSize	- Output parameter receiving the final escaped string length in bytes, or 0 on failure

Returns: char* - Heap allocated UTF-8 string with escaped quotes and backslashes. Caller must free. NULL on failure

Definition at line 632 of file id3v2Frame.c.

◆ id3v2ReadFrameEntryAsU16()

uint16_t id3v2ReadFrameEntryAsU16 ( ListIter * traverser )

Reads the current entry as a 16-bit unsigned integer, advancing the iterator.

Retrieves the content entry at the iterator's current position and interprets it as a uint16_t. For entries with 2+ bytes, constructs the value from the first two bytes. For single-byte entries, zero-extends the byte to 16 bits. Advances the iterator to the next entry. Returns 0 if the traverser is NULL, the current entry is NULL, or the entry has zero size.

Parameters

traverser - Iterator positioned at the entry to read

Returns: uint16_t - 16-bit unsigned integer value from entry data, or 0 on failure

Definition at line 778 of file id3v2Frame.c.

◆ id3v2ReadFrameEntryAsU32()

uint32_t id3v2ReadFrameEntryAsU32 ( ListIter * traverser )

Reads the current entry as a 32-bit unsigned integer, advancing the iterator.

Retrieves the content entry at the iterator's current position and interprets it as a uint32_t. Entries larger than 4 bytes are clamped to use only the first 4 bytes. Advances the iterator to the next entry. Returns 0 if the traverser is NULL or the current entry is NULL.

Parameters

traverser - Iterator positioned at the entry to read

Returns: uint32_t - 32-bit unsigned integer value from entry data, or 0 on failure

Definition at line 812 of file id3v2Frame.c.

◆ id3v2ReadFrameEntryAsU8()

uint8_t id3v2ReadFrameEntryAsU8 ( ListIter * traverser )

Reads the first byte of the current entry as an 8-bit unsigned integer, advancing the iterator.

Retrieves the content entry at the iterator's current position and extracts the first byte. Advances the iterator to the next entry. Returns 0 if the traverser is NULL, the current entry is NULL, or the entry has zero size. The remaining bytes in multi-byte entries are discarded.

Parameters

traverser - Iterator positioned at the entry to read

Returns: uint8_t - First byte of the entry data, or 0 on failure

Definition at line 748 of file id3v2Frame.c.

◆ id3v2WriteFrameEntry()

bool id3v2WriteFrameEntry	(	Id3v2Frame *	frame,
		ListIter *	entries,
		size_t	entrySize,
		const void *	entry )

Writes data to the entry at the iterator's current position, clamping size to context constraints.

Locates the entry referenced by the iterator within the frame's entries list, finds its corresponding context definition, and replaces the entry's data with a deep copy of the provided data. The written size is clamped to the context's min/max bounds to maintain frame structure integrity. The iterator position is not advanced. Returns false if any parameter is NULL, entrySize is 0, the iterator's current position is invalid, the entry cannot be located, or the corresponding context cannot be found.

Parameters

frame	- Frame containing the entry to modify
entries	- Iterator positioned at the entry to write. Iterator position is not advanced
entrySize	- Desired size of data to write in bytes. Will be clamped to context min/max
entry	- Source data to copy into the entry

Returns: bool - true on successful write, false on failure

Definition at line 865 of file id3v2Frame.c.

Functions

Detailed Description

Function Documentation

◆ id3v2AttachFrameToTag()

◆ id3v2CompareContentEntry()

◆ id3v2CompareFrame()

◆ id3v2CompareFrameId()

◆ id3v2CopyContentEntry()

◆ id3v2CopyFrame()

◆ id3v2CreateContentEntry()

◆ id3v2CreateEmptyFrame()

◆ id3v2CreateFrame()

◆ id3v2CreateFrameEntryTraverser()

◆ id3v2CreateFrameHeader()

◆ id3v2CreateFrameTraverser()

◆ id3v2DeleteContentEntry()

◆ id3v2DeleteFrame()

◆ id3v2DestroyFrame()

◆ id3v2DestroyFrameHeader()

◆ id3v2DetachFrameFromTag()

◆ id3v2FrameHeaderSerialize()

◆ id3v2FrameHeaderToJSON()

◆ id3v2FrameSerialize()

◆ id3v2FrameToJSON()

◆ id3v2FrameTraverse()

◆ id3v2PrintContentEntry()

◆ id3v2PrintFrame()

◆ id3v2ReadFrameEntry()

◆ id3v2ReadFrameEntryAsChar()

◆ id3v2ReadFrameEntryAsU16()

◆ id3v2ReadFrameEntryAsU32()

◆ id3v2ReadFrameEntryAsU8()

◆ id3v2WriteFrameEntry()