Function implementation of ID3v2 frame context definitions and parsing configuration. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <limits.h>
#include "id3v2/id3v2Context.h"
#include "id3dependencies/ByteStream/include/byteTypes.h"
#include "id3dependencies/ByteStream/include/byteStream.h"
#include "id3dependencies/ByteStream/include/byteInt.h"

Include dependency graph for id3v2Context.c:

Go to the source code of this file.

Functions
unsigned long	id3v2djb2 (const char *str)
	Computes a DJB2 hash value for a null-terminated string.
Id3v2ContentContext *	id3v2CreateContentContext (Id3v2ContextType type, size_t key, size_t max, size_t min)
	Creates a content context structure defining entry constraints and metadata.
void	id3v2DestroyContentContext (Id3v2ContentContext **toDelete)
	Frees all memory allocated for a content context and nullifies the pointer.
void	id3v2DeleteContentContext (void *toBeDeleted)
	List/Hash API required functions.
int	id3v2CompareContentContext (const void first, const void second)
	Performs comparison of two content context structures.
char *	id3v2PrintContentContext (const void *toBePrinted)
	Generates a string representation of a content context for debugging.
void *	id3v2CopyContentContext (const void *toBeCopied)
	Creates a deep copy of a content context structure.
void	id3v2DeleteContentContextList (void *toBeDeleted)
	Frees all memory allocated for a list of content contexts.
char *	id3v2PrintContentContextList (const void *toBePrinted)
	Generates a string representation of a content context list for debugging.
void *	id3v2CopyContentContextList (const void *toBeCopied)
	Creates a deep copy of a content context list.
List *	id3v2CreateTextFrameContext (void)
	Context list generation.
List *	id3v2CreateUserDefinedTextFrameContext (void)
	Creates a context definition list for user-defined text frames (TXXX).
List *	id3v2CreateURLFrameContext (void)
	Creates a context definition list for standard ID3v2 URL frames.
List *	id3v2CreateUserDefinedURLFrameContext (void)
	Creates a context definition list for user-defined URL frames (WXXX).
List *	id3v2CreateAttachedPictureFrameContext (unsigned int version)
	Creates a context definition list for attached picture frames (APIC/PIC).
List *	id3v2CreateAudioSeekPointIndexFrameContext (void)
	Creates a context definition list for Audio Seek Point Index frames (ASPI).
List *	id3v2CreateAudioEncryptionFrameContext (void)
	Creates a context definition list for Audio Encryption frames (AENC).
List *	id3v2CreateCommentFrameContext (void)
	Creates a context definition list for comment frames (COMM).
List *	id3v2CreateCommercialFrameContext (void)
	Creates a context definition list for commercial frames (COMR).
List *	id3v2CreateEncryptedMetaFrameContext (void)
	Creates a context definition list for encrypted metadata frames (ENCR).
List *	id3v2CreateRegistrationFrameContext (void)
	Creates a context definition list for encryption method registration (ENCR) or group identification (GRID) frames.
List *	id3v2CreateMusicCDIdentifierFrameContext (void)
	Creates a context definition list for music CD identifier frames (MCDI).
List *	id3v2CreatePlayCounterFrameContext (void)
	Creates a context definition list for play counter frames (PCNT).
List *	id3v2CreateEqualizationFrameContext (unsigned int version)
	Creates a context definition list for equalization frames (EQU/EQUA/EQU2).
List *	id3v2CreateEventTimingCodesFrameContext (void)
	Creates a context definition list for event timing codes frames (ETCO).
List *	id3v2CreateGeneralEncapsulatedObjectFrameContext (void)
	Creates a context definition list for general encapsulated object frames (GEOB).
List *	id3v2CreateInvolvedPeopleListFrameContext (void)
	Creates a context definition list for involved people list frames (IPLS) in ID3v2.2 and ID3v2.3.
List *	id3v2CreateLinkedInformationFrameContext (void)
	Creates a context definition list for linked information frames (LINK).
List *	id3v2CreateMPEGLocationLookupTableFrameContext (void)
	Creates a context definition list for MPEG location lookup table frames (MLLT).
List *	id3v2CreateOwnershipFrameContext (void)
	Creates a context definition list for ownership frames (OWNE).
List *	id3v2CreatePopularimeterFrameContext (void)
	Creates a context definition list for popularimeter frames (POPM).
List *	id3v2CreatePositionSynchronisationFrameContext (void)
	Creates a context definition list for position synchronisation frames (POSS).
List *	id3v2CreatePrivateFrameContext (void)
	Creates a context definition list for private frames (PRIV).
List *	id3v2CreateRecommendedBufferSizeFrameContext (void)
	Creates a context definition list for recommended buffer size frames (RBUF).
List *	id3v2CreateRelativeVolumeAdjustmentFrameContext (unsigned int version)
	Creates a context definition list for relative volume adjustment frames (RVA/RVAD/RVA2).
List *	id3v2CreateReverbFrameContext (void)
	Creates a context definition list for reverb frames (RVRB).
List *	id3v2CreateSeekFrameContext (void)
	Creates a context definition list for seek frames (SEEK).
List *	id3v2CreateSignatureFrameContext (void)
	Creates a context definition list for signature frames (SIGN).
List *	id3v2CreateSynchronisedLyricFrameContext (void)
	Creates a context definition list for synchronised lyrics/text frames (SYLT).
List *	id3v2CreateSynchronisedTempoCodesFrameContext (void)
	Creates a context definition list for synchronised tempo codes frames (SYTC).
List *	id3v2CreateUniqueFileIdentifierFrameContext (void)
	Creates a context definition list for unique file identifier frames (UFID).
List *	id3v2CreateTermsOfUseFrameContext (void)
	Creates a context definition list for terms of use frames (USER).
List *	id3v2CreateUnsynchronisedLyricFrameContext (void)
	Creates a context definition list for unsynchronised lyrics/text frames (USLT).
List *	id3v2CreateGenericFrameContext (void)
	Creates a context definition list for generic frames with unknown or unrecognized structure.
HashTable *	id3v2CreateDefaultIdentifierContextPairings (unsigned int version)
	Creates a default mapping of frame identifiers to their corresponding parse contexts for all ID3v2 versions.
bool	id3v2InsertIdentifierContextPair (HashTable identifierContextPairs, char key[ID3V2_FRAME_ID_MAX_SIZE], List context)
	Inserts a new frame identifier and context pairing into an existing frame mapping table.
uint8_t *	id3v2ContextSerialize (Id3v2ContentContext cc, size_t outl)
	Creates a binary representation of a content context structure for serialization.
char *	id3v2ContextToJSON (const Id3v2ContentContext *cc)
	Converts a content context structure to its JSON representation.

Detailed Description

Function implementation of ID3v2 frame context definitions and parsing configuration.

Author: Ewan Jones

Version: 0.1

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

Copyright: Copyright (c) 2024 - 2026

Definition in file id3v2Context.c.

Function Documentation

◆ id3v2CompareContentContext()

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

Performs comparison of two content context structures.

Compares content contexts by sequentially checking type, key, min, and max fields. Uses a non-standard comparison: returns 0 if first field is less than second, otherwise returns the field difference. Can be used as a callback for list comparison operations.

Parameters

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

Returns: int - 0 if contexts are equal or first < second in comparison order, positive if first > second

Definition at line 115 of file id3v2Context.c.

◆ id3v2ContextSerialize()

uint8_t * id3v2ContextSerialize	(	Id3v2ContentContext *	cc,
		size_t *	outl )

Creates a binary representation of a content context structure for serialization.

Converts an Id3v2ContentContext structure into a compact binary format suitable for storage or transmission. The serialization layout consists of: a 1-byte type field identifying the context type, followed by three size_t values (key hash, maximum bytes, minimum bytes) encoded in binary format. The total serialized size is (3 × sizeof(size_t)) + 1 bytes. Uses a ByteStream for structured binary writing and the sttob() utility to convert size_t values to byte arrays in a platform-independent manner. The serialized format enables context structures to be persisted to disk, transmitted over networks, or embedded in other data structures while preserving all essential parsing information.

Parameters

cc	The content context structure to serialize
outl	Output parameter receiving the length of the serialized binary data in bytes

Returns: uint8_t* - Heap allocated byte array containing the serialized context. Returns NULL if cc is NULL (with outl set to 0). Caller must free the returned buffer

Definition at line 1970 of file id3v2Context.c.

◆ id3v2ContextToJSON()

char * id3v2ContextToJSON ( const Id3v2ContentContext * cc )

Converts a content context structure to its JSON representation.

Serializes an Id3v2ContentContext structure into a compact JSON string containing the context's type identifier, key hash value, maximum byte constraint, and minimum byte constraint. The function calculates the exact memory requirement using snprintf with a NULL buffer to determine string length, then allocates and formats the JSON output. For NULL input, returns an empty JSON object string "{}". This JSON format enables context structures to be transmitted via web APIs, stored in configuration files, or logged for debugging purposes while maintaining human readability and standard JSON parser compatibility.

Example output for a text encoding context:

{"type":2,"key":2087083923,"max":255,"min":1}

Example output for NULL input:

{}

Parameters

cc	The content context structure to convert, or NULL for empty object

Returns: char* - Heap allocated null-terminated JSON string. Returns "{}" if cc is NULL. Caller must free the returned string

Definition at line 2033 of file id3v2Context.c.

◆ id3v2CopyContentContext()

void * id3v2CopyContentContext ( const void * toBeCopied )

Creates a deep copy of a content context structure.

Duplicates a content context by creating a new structure with independently allocated memory and copying all fields (type, key, min, max). Can be used as a callback function for list copy operations.

Parameters

toBeCopied - Content context to copy

Returns: void* - Heap allocated content context containing a copy of all fields. Caller must free

Definition at line 174 of file id3v2Context.c.

◆ id3v2CopyContentContextList()

void * id3v2CopyContentContextList ( const void * toBeCopied )

Creates a deep copy of a content context list.

Wrapper around listDeepCopy for use as a callback in hash table copy operations where the stored data is a List structure containing content contexts. Creates a new list with independently allocated copies of all content context elements.

Parameters

toBeCopied - List of content contexts to copy

Returns: void* - Heap allocated list containing deep copies of all content contexts. Caller must free

Definition at line 222 of file id3v2Context.c.

◆ id3v2CreateAttachedPictureFrameContext()

List * id3v2CreateAttachedPictureFrameContext ( unsigned int version )

Creates a context definition list for attached picture frames (APIC/PIC).

Constructs a version-specific list defining the structure of attached picture frames used for album artwork and other images. v2.2 uses a 3-byte fixed format string (e.g., "PNG", "JPG"), while v2.3/v2.4 use a Latin-1 encoded MIME type (e.g., "image/png", "image/jpeg"). The context includes: 1-byte encoding, format identifier, 1-byte picture type (cover front, back, icon, etc.), encoded description string, and binary image data.

Parameters

version - ID3v2 version (ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4) determining format field encoding

Returns: List* - Heap allocated list containing five content contexts: encoding (1 byte), format (3 bytes for v2.2 or 1-UINT_MAX bytes for v2.3/v2.4), picture type (1 byte), description (1-UINT_MAX bytes), and binary image data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 352 of file id3v2Context.c.

◆ id3v2CreateAudioEncryptionFrameContext()

List * id3v2CreateAudioEncryptionFrameContext ( void )

Creates a context definition list for Audio Encryption frames (AENC).

Constructs a list defining the structure of AENC frames used to signal encrypted audio content. The context specifies: a Latin-1 encoded owner identifier (URL or email of the encryption method owner), a 2-byte preview start position indicating where unencrypted preview data begins, a 2-byte preview length, and binary encryption information containing keys or method-specific data.

Returns: List* - Heap allocated list containing four content contexts: owner identifier (1-UINT_MAX bytes), preview start (2 bytes), preview length (2 bytes), and encryption data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 429 of file id3v2Context.c.

◆ id3v2CreateAudioSeekPointIndexFrameContext()

List * id3v2CreateAudioSeekPointIndexFrameContext ( void )

Creates a context definition list for Audio Seek Point Index frames (ASPI).

Constructs a list defining the structure of ASPI frames used for efficient seeking within audio files. The frame contains binary index data that maps file positions to time positions, enabling fast navigation without parsing the entire audio stream. The context specifies a single binary data field.

Returns: List* - Heap allocated list containing one content context: binary index data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 406 of file id3v2Context.c.

◆ id3v2CreateCommentFrameContext()

List * id3v2CreateCommentFrameContext ( void )

Creates a context definition list for comment frames (COMM).

Constructs a list defining the structure of comment frames used for storing user comments and notes. The context specifies: a 1-byte encoding field, a 3-byte ISO-639-2 language code (e.g., "eng", "fra", "deu"), an encoded short content description string (1-UINT_MAX bytes), and the actual comment text (1-UINT_MAX bytes). Multiple COMM frames can coexist with different language/description combinations.

Returns: List* - Heap allocated list containing four content contexts: encoding (1 byte), language code (3 bytes), content description (1-UINT_MAX bytes), and comment text (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 464 of file id3v2Context.c.

◆ id3v2CreateCommercialFrameContext()

List * id3v2CreateCommercialFrameContext ( void )

Creates a context definition list for commercial frames (COMR).

Constructs a list defining the structure of commercial information frames used to describe commercial transactions. The context specifies: a 1-byte encoding field, a price string (1 to UINT_MAX bytes) in latin-1 format, an 8-byte date string (YYYYMMDD), a URL (1 to UINT_MAX bytes) for purchasing, a 1-byte received-as type indicator, a name field (1 to UINT_MAX bytes) in the specified encoding, a description field (1 to UINT_MAX bytes) in the specified encoding, a MIME type format string (1 to UINT_MAX bytes) in latin-1, and finally binary data (1 to UINT_MAX bytes) such as a company logo. This structure enables embedding commercial transaction details and purchase information within ID3v2 tags.

Returns: List* - Heap allocated list containing nine content contexts: encoding (1 byte), price (1-UINT_MAX bytes), date (8 bytes), url (1-UINT_MAX bytes), type (1 byte), name (1-UINT_MAX bytes), description (1-UINT_MAX bytes), format (1-UINT_MAX bytes), and data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 503 of file id3v2Context.c.

◆ id3v2CreateContentContext()

Id3v2ContentContext * id3v2CreateContentContext	(	Id3v2ContextType	type,
		size_t	key,
		size_t	max,
		size_t	min )

Creates a content context structure defining entry constraints and metadata.

Allocates and initializes an Id3v2ContentContext on the heap. Content contexts define the structure, type, and size constraints for individual content entries within ID3v2 frames. Each context specifies how an entry should be interpreted (string, binary, numeric, etc.) and enforces minimum and maximum size bounds. The key field is a DJB2 hash used for context identification and lookup operations.

Parameters

type	- Context type specifying how entry data should be interpreted (e.g., encodedString_context, binary_context, numeric_context)
key	- Hash key for context identification, typically computed via id3v2djb2()
max	- Maximum allowed size in bytes for entries using this context
min	- Minimum required size in bytes for entries using this context

Returns: Id3v2ContentContext* - Heap allocated content context structure. Caller must free

Definition at line 60 of file id3v2Context.c.

◆ id3v2CreateDefaultIdentifierContextPairings()

HashTable * id3v2CreateDefaultIdentifierContextPairings ( unsigned int version )

Creates a default mapping of frame identifiers to their corresponding parse contexts for all ID3v2 versions.

Constructs and populates a hash table that maps frame ID strings to context definition lists used by the parser to interpret frame structures. The mapping varies by ID3v2 version: v2.2 uses 3-character frame IDs (e.g., "TIT", "COM", "PIC"), while v2.3 and v2.4 use 4-character IDs (e.g., "TIT2", "COMM", "APIC"). The function creates context lists for all standard frame types including text frames (T*), URL frames (W*), comment frames, picture frames, and specialized frames like equalization, synchronised lyrics, and encryption registration. Three fallback contexts are provided for unknown or generic frames: "?" handles completely unrecognized frame types, "T" provides generic text frame parsing, and "W" provides generic URL frame parsing. Each context list is temporarily assigned to the hash table then freed, as the table makes its own internal copy. This centralized mapping enables version-specific frame parsing without hardcoding structure definitions throughout the parser.

Parameters

version The ID3v2 tag version (ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4)

Returns: HashTable* - Heap allocated hash table mapping frame ID strings to context definition lists. Contains 60+ standard frame mappings plus fallback contexts. Caller must free with hashTableDestroy()

Definition at line 1416 of file id3v2Context.c.

◆ id3v2CreateEncryptedMetaFrameContext()

List * id3v2CreateEncryptedMetaFrameContext ( void )

Creates a context definition list for encrypted metadata frames (ENCR).

Constructs a list defining the structure of encryption method registration frames. The context specifies: an identifier field (1 to UINT_MAX bytes) in latin-1 format containing the owner identifier (typically an email or URL), a content descriptor field (1 to UINT_MAX bytes) in latin-1 format providing additional encryption method information, and binary data (1 to UINT_MAX bytes) containing method-specific encryption parameters. This structure enables registration and documentation of encryption methods used within the ID3v2 tag.

Returns: List* - Heap allocated list containing three content contexts: identifier (1-UINT_MAX bytes), content (1-UINT_MAX bytes), and data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 559 of file id3v2Context.c.

◆ id3v2CreateEqualizationFrameContext()

List * id3v2CreateEqualizationFrameContext ( unsigned int version )

Creates a context definition list for equalization frames (EQU/EQUA/EQU2).

Constructs a list defining the structure of equalization frames, with format varying by ID3v2 version. For v2.2/v2.3 (EQU/EQUA): specifies a 1-byte adjustment bits field, a 1-bit increment/decrement flag, a 15-bit frequency value, volume adjustment data (1 to UINT_MAX bytes, length dependent on adjustment field), and an iterator context for repeating frequency/volume pairs. For v2.4 (EQU2): specifies a 1-byte interpolation method symbol, an identifier string (1 to UINT_MAX bytes) in latin-1 format describing the equalization curve, a 2-byte volume adjustment value, and an iterator for repeating frequency/volume pairs (minimum 2 bytes). These structures enable storage of frequency-specific volume adjustments for audio equalization.

Parameters

version The ID3v2 version (ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4)

Returns: List* - Heap allocated list containing version-specific content contexts. For v2.2/v2.3: adjustment (1 byte), unary (1 bit), frequency (15 bits), volume (1-UINT_MAX bytes), and iter (1-UINT_MAX bytes). For v2.4: symbol (1 byte), identifier (1-UINT_MAX bytes), volume (2 bytes), and iter (2-UINT_MAX bytes). Caller must free with listFree()

Definition at line 672 of file id3v2Context.c.

◆ id3v2CreateEventTimingCodesFrameContext()

List * id3v2CreateEventTimingCodesFrameContext ( void )

Creates a context definition list for event timing codes frames (ETCO).

Constructs a list defining the structure of event timing codes frames that mark significant moments during audio playback. The context specifies: a 1-byte symbol field indicating the time stamp format (MPEG frames, milliseconds, etc.), a 1-byte event type code identifying the event (intro start, outro start, key change, etc.), a 4-byte time stamp indicating when the event occurs, and an iterator context for repeating type/stamp pairs (1 to UINT_MAX bytes). This structure enables synchronization of events with audio playback at precisely defined moments.

Returns: List* - Heap allocated list containing four content contexts: symbol (1 byte), type (1 byte), stamp (4 bytes), and iter (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 745 of file id3v2Context.c.

◆ id3v2CreateGeneralEncapsulatedObjectFrameContext()

List * id3v2CreateGeneralEncapsulatedObjectFrameContext ( void )

Creates a context definition list for general encapsulated object frames (GEOB).

Constructs a list defining the structure of general encapsulated object frames used to embed arbitrary files within ID3v2 tags. The context specifies: a 1-byte encoding field for text strings, a MIME type format string (1 to UINT_MAX bytes) in latin-1 encoding describing the object type, a filename field (1 to UINT_MAX bytes) in the specified encoding, a content description field (1 to UINT_MAX bytes) in the specified encoding, and binary data (1 to UINT_MAX bytes) containing the actual encapsulated object. This structure enables embedding any file type (documents, images, archives, etc.) directly within the audio file's metadata.

Returns: List* - Heap allocated list containing five content contexts: encoding (1 byte), format (1-UINT_MAX bytes), name (1-UINT_MAX bytes), description (1-UINT_MAX bytes), and data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 783 of file id3v2Context.c.

◆ id3v2CreateGenericFrameContext()

List * id3v2CreateGenericFrameContext ( void )

Creates a context definition list for generic frames with unknown or unrecognized structure.

Constructs a minimal fallback list for handling frames whose structure is not explicitly defined or recognized by the parser. The context specifies a single binary data field (1 to UINT_MAX bytes) that captures the entire frame content without interpretation. This generic context enables the library to preserve and handle unrecognized frame types, experimental frames, or proprietary frame extensions without data loss, allowing the complete tag to be read, modified, and written back even when some frame types are unknown.

Returns: List* - Heap allocated list containing one content context: binary data (1-UINT_MAX bytes) marked with unknown identifier. Caller must free with listFree()

Definition at line 1387 of file id3v2Context.c.

◆ id3v2CreateInvolvedPeopleListFrameContext()

List * id3v2CreateInvolvedPeopleListFrameContext ( void )

Creates a context definition list for involved people list frames (IPLS) in ID3v2.2 and ID3v2.3.

Constructs a list defining the structure of involved people list frames that document individuals involved in the recording and their roles. The context specifies: a 1-byte encoding field for text strings, a name field (1 to UINT_MAX bytes) in the specified encoding describing the involvement or role (e.g., "producer", "engineer", "mixer"), a text field (1 to UINT_MAX bytes) in the specified encoding containing the person's name, and an iterator context for repeating name/text pairs (1 to UINT_MAX bytes). This structure enables documentation of multiple contributors and their specific roles in the production process.

Returns: List* - Heap allocated list containing four content contexts: encoding (1 byte), name (1-UINT_MAX bytes), text (1-UINT_MAX bytes), and iter (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 824 of file id3v2Context.c.

◆ id3v2CreateLinkedInformationFrameContext()

List * id3v2CreateLinkedInformationFrameContext ( void )

Creates a context definition list for linked information frames (LINK).

Constructs a list defining the structure of linked information frames used to reference additional data stored externally or in other locations within the tag. The context specifies: a URL field (1 to UINT_MAX bytes) in latin-1 encoding pointing to the location of the linked information, and a data field (1 to UINT_MAX bytes) containing frame identifier codes and additional identification data for the linked content. This structure enables referencing external resources or creating connections between frames without duplicating large amounts of data within the tag itself.

Returns: List* - Heap allocated list containing two content contexts: url (1-UINT_MAX bytes) and data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 860 of file id3v2Context.c.

◆ id3v2CreateMPEGLocationLookupTableFrameContext()

List * id3v2CreateMPEGLocationLookupTableFrameContext ( void )

Creates a context definition list for MPEG location lookup table frames (MLLT).

Constructs a list defining the structure of MPEG location lookup table frames that provide seek point references for efficient navigation within MPEG audio streams. The context specifies a single binary data field (1 to UINT_MAX bytes) containing reference point information including MPEG frames between references, bytes between references, milliseconds between references, and deviation arrays. Note: This implementation treats the entire frame as binary data without parsing individual subfields, as MLLT frames are rarely used in practice.

Returns: List* - Heap allocated list containing one content context: data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 887 of file id3v2Context.c.

◆ id3v2CreateMusicCDIdentifierFrameContext()

List * id3v2CreateMusicCDIdentifierFrameContext ( void )

Creates a context definition list for music CD identifier frames (MCDI).

Constructs a list defining the structure of Music CD Identifier frames containing CD Table of Contents (TOC) data. The context specifies a single binary data field of exactly 804 bytes, representing the complete CD TOC as defined by the Red Book CD-DA standard. This fixed size accommodates up to 100 tracks with their position information, enabling accurate identification and lookup of audio CDs in online databases such as CDDB/FreeDB.

Returns: List* - Heap allocated list containing one content context: data (804 bytes). Caller must free with listFree()

Definition at line 620 of file id3v2Context.c.

◆ id3v2CreateOwnershipFrameContext()

List * id3v2CreateOwnershipFrameContext ( void )

Creates a context definition list for ownership frames (OWNE).

Constructs a list defining the structure of ownership frames that document the legal ownership of the audio file. The context specifies: a 1-byte encoding field for text strings, a price string (1 to UINT_MAX bytes) in latin-1 format indicating the purchase price with currency code, an 8-byte date string (YYYYMMDD format) in latin-1 encoding indicating the date of purchase, and a seller name field (1 to UINT_MAX bytes) in the specified encoding containing the name of the person or organization from whom the file was purchased. This structure provides a record of legitimate ownership and purchase information.

Returns: List* - Heap allocated list containing four content contexts: encoding (1 byte), price (1-UINT_MAX bytes), date (8 bytes), and name (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 911 of file id3v2Context.c.

◆ id3v2CreatePlayCounterFrameContext()

List * id3v2CreatePlayCounterFrameContext ( void )

Creates a context definition list for play counter frames (PCNT).

Constructs a list defining the structure of play counter frames that track the number of times a file has been played. The context specifies a single binary data field (1 to UINT_MAX bytes) containing the play count stored as integer. The counter starts at zero and increments with each playback. Variable length encoding allows the counter to grow as needed, typically starting with 4 bytes but expandable for very high play counts.

Returns: List* - Heap allocated list containing one content context: data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 642 of file id3v2Context.c.

◆ id3v2CreatePopularimeterFrameContext()

List * id3v2CreatePopularimeterFrameContext ( void )

Creates a context definition list for popularimeter frames (POPM).

Constructs a list defining the structure of popularimeter frames that store user ratings and play count information. The context specifies: an identifier field (1 to UINT_MAX bytes) in latin-1 encoding containing the email address of the user or application providing the rating, a 1-byte rating symbol value (typically 0-255, where higher values indicate better ratings), and a counter data field (1 to UINT_MAX bytes) containing the play count as a big-endian integer. This structure enables multiple users or applications to store independent ratings and play counts by using unique email identifiers.

Returns: List* - Heap allocated list containing three content contexts: identifier (1-UINT_MAX bytes), symbol (1 byte), and data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 947 of file id3v2Context.c.

◆ id3v2CreatePositionSynchronisationFrameContext()

List * id3v2CreatePositionSynchronisationFrameContext ( void )

Creates a context definition list for position synchronisation frames (POSS).

Constructs a list defining the structure of position synchronisation frames used to mark the current playback position when audio has been edited or reorganized. The context specifies: a 1-byte format field indicating the time stamp format (MPEG frames, milliseconds, etc.), and a 4-byte time stamp value indicating the precise playback position within the audio. This structure enables applications to maintain synchronized playback positions across edited versions of the same audio file or after structural modifications.

Returns: List* - Heap allocated list containing two content contexts: format (1 byte) and stamp (4 bytes). Caller must free with listFree()

Definition at line 978 of file id3v2Context.c.

◆ id3v2CreatePrivateFrameContext()

List * id3v2CreatePrivateFrameContext ( void )

Creates a context definition list for private frames (PRIV).

Constructs a list defining the structure of private frames used to store application-specific proprietary data. The context specifies: an identifier field (1 to UINT_MAX bytes) in latin-1 encoding containing the owner identifier (typically an email address or URL) that uniquely identifies the application or organization, and a binary data field (1 to UINT_MAX bytes) containing the private data in any format chosen by the owner. Using unique identifiers prevents conflicts between different applications storing private data within the same tag, enabling custom metadata extensions without standardization.

Returns: List* - Heap allocated list containing two content contexts: identifier (1-UINT_MAX bytes) and data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 1006 of file id3v2Context.c.

◆ id3v2CreateRecommendedBufferSizeFrameContext()

List * id3v2CreateRecommendedBufferSizeFrameContext ( void )

Creates a context definition list for recommended buffer size frames (RBUF).

Constructs a list defining the structure of recommended buffer size frames that provide guidance for optimal streaming buffer sizes. The context specifies: a 3-byte buffer size field indicating the recommended minimum buffer size in bytes for streaming the audio file, a 1-byte flag field where bit 0 indicates whether embedded info is present and bit 1 indicates the next tag location, and an optional 4-byte offset field (0 to 4 bytes) containing the offset to the next tag if the flag indicates its presence. This structure helps streaming applications optimize buffering and locate subsequent tags efficiently.

Returns: List* - Heap allocated list containing three content contexts: buffer (3 bytes), flag (1 byte), and offset (0-4 bytes). Caller must free with listFree()

Definition at line 1034 of file id3v2Context.c.

◆ id3v2CreateRegistrationFrameContext()

List * id3v2CreateRegistrationFrameContext ( void )

Creates a context definition list for encryption method registration (ENCR) or group identification (GRID) frames.

Constructs a list defining the structure of registration frames used for encryption methods or group identifiers. The context specifies: an identifier field (1 to UINT_MAX bytes) in latin-1 format containing the owner identifier (typically an email or URL), a 1-byte symbol field serving as the method or group identifier byte, and binary data (1 to UINT_MAX bytes) containing method-specific or group-specific information. For ENCR frames, this registers encryption methods with their parameters. For GRID frames, this registers group identifiers for organizational purposes.

Returns: List* - Heap allocated list containing three content contexts: identifier (1-UINT_MAX bytes), symbol (1 byte), and data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 590 of file id3v2Context.c.

◆ id3v2CreateRelativeVolumeAdjustmentFrameContext()

List * id3v2CreateRelativeVolumeAdjustmentFrameContext ( unsigned int version )

Creates a context definition list for relative volume adjustment frames (RVA/RVAD/RVA2).

Constructs a simplified list defining the structure of relative volume adjustment frames used to specify recommended playback volume changes. Currently implemented as a single binary data field (1 to UINT_MAX bytes) containing the entire frame structure without parsing individual components. The complete RVA2 structure includes an identification string, channel type bytes, volume adjustment values (typically 2 bytes), bits representing peak volume, and optional peak volume data. This simplified implementation allows reading and preserving RVA frames while deferring detailed parsing to future enhancements or post-processing functions.

Warning: THIS IS A BUMMY IMPLEMENTATION AND NEEDS TO BE UPDATED IN THE FUTURE

Parameters

version The ID3v2 version (currently unused; all versions treated uniformly as binary data)

Returns: List* - Heap allocated list containing one content context: data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 1068 of file id3v2Context.c.

◆ id3v2CreateReverbFrameContext()

List * id3v2CreateReverbFrameContext ( void )

Creates a context definition list for reverb frames (RVRB).

Constructs a list defining the structure of reverb frames that specify recommended reverb effect parameters for audio playback. The context specifies: 2-byte reverb delay values for left and right channels in milliseconds, 1-byte bounce values for left and right channels indicating initial reflection intensity, four 1-byte feedback values defining the cross-channel feedback matrix (left-to-left, left-to-right, right-to-right, right-to-left), and 1-byte premix level values for left and right channels controlling the dry/wet mix. These ten fields provide comprehensive control over stereo reverb characteristics, enabling applications to recreate the intended spatial audio effects during playback.

Returns: List* - Heap allocated list containing ten content contexts: left (2 bytes), right (2 bytes), bounce left (1 byte), bounce right (1 byte), feedback ll (1 byte), feedback lr (1 byte), feedback rr (1 byte), feedback rl (1 byte), p left (1 byte), and p right (1 byte). Caller must free with listFree()

Definition at line 1094 of file id3v2Context.c.

◆ id3v2CreateSeekFrameContext()

List * id3v2CreateSeekFrameContext ( void )

Creates a context definition list for seek frames (SEEK).

Constructs a list defining the structure of seek frames that indicate the location of additional ID3v2 tags within the audio file. The context specifies a single 4-byte offset field containing the minimum number of bytes from the end of the current tag to the beginning of the next tag. This structure enables efficient tag discovery by allowing applications to skip directly to subsequent tags without scanning the entire file, particularly useful for files containing multiple ID3v2 tags at different locations.

Returns: List* - Heap allocated list containing one content context: offset (4 bytes). Caller must free with listFree()

Definition at line 1152 of file id3v2Context.c.

◆ id3v2CreateSignatureFrameContext()

List * id3v2CreateSignatureFrameContext ( void )

Creates a context definition list for signature frames (SIGN).

Constructs a list defining the structure of signature frames used to provide digital signatures for tag authentication and integrity verification. The context specifies: a 1-byte symbol field identifying the group or frame type being signed, and a binary data field (1 to UINT_MAX bytes) containing the actual digital signature. The signature is calculated over specific tag data to ensure authenticity and detect unauthorized modifications. This structure enables verification that tag content has not been altered since the signature was applied by the legitimate owner or authority.

Returns: List* - Heap allocated list containing two content contexts: symbol (1 byte) and data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 1176 of file id3v2Context.c.

◆ id3v2CreateSynchronisedLyricFrameContext()

List * id3v2CreateSynchronisedLyricFrameContext ( void )

Creates a context definition list for synchronised lyrics/text frames (SYLT).

Constructs a list defining the structure of synchronised lyrics or text that display lyrics, captions, or other text synchronized with audio playback. The context specifies: a 1-byte encoding field for text strings, a 3-byte language code in ISO-639-2 format, a 1-byte time stamp format indicator (MPEG frames, milliseconds, etc.), a 1-byte content type symbol identifying the text purpose (lyrics, transcription, movement description, etc.), a content descriptor field (1 to UINT_MAX bytes) in the specified encoding, a text field (1 to UINT_MAX bytes) containing the synchronized text content, a 4-byte time stamp indicating when to display the text, and an iterator context for repeating text/stamp pairs (minimum 5 bytes). This structure enables karaoke-style lyric display and timed caption presentation during playback.

Returns: List* - Heap allocated list containing eight content contexts: encoding (1 byte), language (3 bytes), format (1 byte), symbol (1 byte), description (1-UINT_MAX bytes), text (1-UINT_MAX bytes), stamp (4 bytes), and iter (5-UINT_MAX bytes). Caller must free with listFree()

Definition at line 1207 of file id3v2Context.c.

◆ id3v2CreateSynchronisedTempoCodesFrameContext()

List * id3v2CreateSynchronisedTempoCodesFrameContext ( void )

Creates a context definition list for synchronised tempo codes frames (SYTC).

Constructs a simplified list defining the structure of synchronised tempo codes frames used to specify tempo/BPM changes throughout the audio track. The context specifies: a 1-byte time stamp format field indicating the timing unit (MPEG frames, milliseconds, etc.), and a binary data field (1 to UINT_MAX bytes) containing tempo change events. Currently implemented as binary data without parsing individual tempo entries, each of which would normally consist of a tempo value and corresponding time stamp. This simplified implementation allows reading and preserving SYTC frames while deferring detailed tempo event parsing to future enhancements or post-processing functions.

Warning: THIS IS AN INCOMPLETE IMPLEMENTATION AND NEEDS TO BE UPDATED IN THE FUTURE

Returns: List* - Heap allocated list containing two content contexts: format (1 byte) and data (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 1260 of file id3v2Context.c.

◆ id3v2CreateTermsOfUseFrameContext()

List * id3v2CreateTermsOfUseFrameContext ( void )

Creates a context definition list for terms of use frames (USER).

Constructs a list defining the structure of terms of use frames that specify legal usage conditions and licensing information for the audio file. The context specifies: a 1-byte encoding field for text strings, a 3-byte language code in ISO-639-2 format indicating the language of the terms, and a text field (1 to UINT_MAX bytes) in the specified encoding containing the complete terms of use, copyright restrictions, or licensing conditions. This structure enables content creators and distributors to embed legally binding usage terms directly within the audio file metadata, ensuring users are informed of restrictions and requirements.

Returns: List* - Heap allocated list containing three content contexts: encoding (1 byte), language (3 bytes), and text (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 1317 of file id3v2Context.c.

◆ id3v2CreateTextFrameContext()

List * id3v2CreateTextFrameContext ( void )

Context list generation.

Creates a context definition list for standard ID3v2 text frames.

Constructs a list defining the structure of text information frames (e.g., TIT2, TPE1, TALB). The context specifies a 1-byte encoding field followed by a variable-length encoded text string (1 to UINT_MAX bytes). This pattern is used by all standard text frames that store single text values with encoding specification.

Returns: List* - Heap allocated list containing two content contexts: encoding (1 byte) and text (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 243 of file id3v2Context.c.

◆ id3v2CreateUniqueFileIdentifierFrameContext()

List * id3v2CreateUniqueFileIdentifierFrameContext ( void )

Creates a context definition list for unique file identifier frames (UFID).

Constructs a list defining the structure of unique file identifier frames used to store database-specific identifiers for the audio file. The context specifies: a URL or owner identifier field (1 to UINT_MAX bytes) in latin-1 encoding identifying the database or system (such as "http://www.id3.org/dummy/ufid.html" or "http://musicbrainz.org"), and a binary data field (1 to 64 bytes) containing the unique identifier value assigned by that database. Multiple UFID frames with different owner identifiers enable the file to be tracked across various music databases and services simultaneously.

Returns: List* - Heap allocated list containing two content contexts: url (1-UINT_MAX bytes) and data (1-64 bytes). Caller must free with listFree()

Definition at line 1288 of file id3v2Context.c.

◆ id3v2CreateUnsynchronisedLyricFrameContext()

List * id3v2CreateUnsynchronisedLyricFrameContext ( void )

Creates a context definition list for unsynchronised lyrics/text frames (USLT).

Constructs a list defining the structure of unsynchronised lyrics or text comment frames that contain complete lyrics or text without timing information. The context specifies: a 1-byte encoding field for text strings, a 3-byte language code in ISO-639-2 format indicating the text language, a content descriptor field (1 to UINT_MAX bytes) in the specified encoding providing a brief description of the content, and a text field (1 to UINT_MAX bytes) in the specified encoding containing the full lyrics or extended text. Unlike synchronised lyrics (SYLT), this frame stores text without time stamps, making it suitable for displaying complete lyrics statically or for general text content that doesn't require playback synchronization.

Returns: List* - Heap allocated list containing four content contexts: encoding (1 byte), language (3 bytes), description (1-UINT_MAX bytes), and text (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 1352 of file id3v2Context.c.

◆ id3v2CreateURLFrameContext()

List * id3v2CreateURLFrameContext ( void )

Creates a context definition list for standard ID3v2 URL frames.

Constructs a list defining the structure of URL frames (e.g., WOAR, WOAS, WCOP, WORS). The context specifies a single Latin-1 encoded URL string (1 to UINT_MAX bytes).

Returns: List* - Heap allocated list containing one content context: URL string in Latin-1 encoding (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 295 of file id3v2Context.c.

◆ id3v2CreateUserDefinedTextFrameContext()

List * id3v2CreateUserDefinedTextFrameContext ( void )

Creates a context definition list for user-defined text frames (TXXX).

Constructs a list defining the structure of user-defined text information frames. The context specifies a 1-byte encoding field, followed by a description string (1 to UINT_MAX bytes) identifying the custom field, and finally the text value (1 to UINT_MAX bytes). This pattern allows users to define custom text metadata fields not covered by standard ID3v2 frames.

Returns: List* - Heap allocated list containing three content contexts: encoding (1 byte), description (1-UINT_MAX bytes), and text value (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 268 of file id3v2Context.c.

◆ id3v2CreateUserDefinedURLFrameContext()

List * id3v2CreateUserDefinedURLFrameContext ( void )

Creates a context definition list for user-defined URL frames (WXXX).

Constructs a list defining the structure of user-defined URL frames. The context specifies a 1-byte encoding field, followed by a description string (1 to UINT_MAX bytes) identifying the custom URL field, and finally the URL value as a Latin-1 encoded string (1 to UINT_MAX bytes). This pattern allows users to define custom URL metadata fields not covered by standard ID3v2 URL frames.

Returns: List* - Heap allocated list containing three content contexts: encoding (1 byte), description (1-UINT_MAX bytes), and URL in Latin-1 encoding (1-UINT_MAX bytes). Caller must free with listFree()

Definition at line 318 of file id3v2Context.c.

◆ id3v2DeleteContentContext()

void id3v2DeleteContentContext ( void * toBeDeleted )

List/Hash API required functions.

Frees all memory allocated for a content context structure.

Wrapper around id3v2DestroyContentContext for use as a callback in list operations. Deallocates the content context structure. Can be used as a callback for list deletion operations.

Parameters

toBeDeleted - Pointer to Id3v2ContentContext to be freed

Definition at line 100 of file id3v2Context.c.

◆ id3v2DeleteContentContextList()

void id3v2DeleteContentContextList ( void * toBeDeleted )

Frees all memory allocated for a list of content contexts.

Wrapper around listFree for use as a callback in hash table or list operations where the stored data is itself a List structure. Deallocates the list and all its contained content context elements.

Parameters

toBeDeleted - Pointer to List structure to be freed

Definition at line 194 of file id3v2Context.c.

◆ id3v2DestroyContentContext()

void id3v2DestroyContentContext ( Id3v2ContentContext ** toDelete )

Frees all memory allocated for a content context and nullifies the pointer.

Safely deallocates a content context structure created by id3v2CreateContentContext. 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 content context pointer to be freed and nullified

Definition at line 79 of file id3v2Context.c.

◆ id3v2djb2()

unsigned long id3v2djb2 ( const char * str )

Computes a DJB2 hash value for a null-terminated string.

Implements the DJB2 hash algorithm by Daniel J. Bernstein using the formula hash = hash * 33 + c for each character. Optimized with bit-shifting: (hash << 5) + hash is equivalent to hash * 33. Used internally for frame identifier and context key hashing to enable fast lookups in hash tables. Initial hash value is 5381.

Parameters

str	- Null-terminated string to hash

Returns: unsigned long - DJB2 hash value computed from the input string

Definition at line 32 of file id3v2Context.c.

◆ id3v2InsertIdentifierContextPair()

bool id3v2InsertIdentifierContextPair	(	HashTable *	identifierContextPairs,
		char	key[ID3V2_FRAME_ID_MAX_SIZE],
		List *	context )

Inserts a new frame identifier and context pairing into an existing frame mapping table.

Adds or updates a mapping between a frame ID string and its corresponding parse context definition list in the provided hash table. This function enables extension of the default frame mappings with custom frame types or modification of existing frame parsing behavior. Performs validation to ensure all parameters are non-NULL before insertion. The hash table makes an internal copy of the context list, so the caller retains ownership of the original context parameter. Used to register proprietary frame formats or override default parsing contexts for specific applications.

Parameters

identifierContextPairs	The hash table containing frame ID to context mappings
key	The frame identifier string (3 characters for v2.2, 4 characters for v2.3/v2.4)
context	The context definition list describing the frame structure

Returns: bool - true if the pairing was successfully inserted, false if any parameter is NULL

Definition at line 1942 of file id3v2Context.c.

◆ id3v2PrintContentContext()

char * id3v2PrintContentContext ( const void * toBePrinted )

Generates a string representation of a content context for debugging.

Creates a formatted string displaying the context's type, key hash, minimum size, and maximum size constraints. Can be used as a callback function for list printing operations. Caller must free the returned string.

Parameters

toBePrinted - Content context to represent as a string

Returns: char* - Heap allocated string in format "Type: <type>, Key: <key>, min: <min>, max: <max>\n". Caller must free

Definition at line 151 of file id3v2Context.c.

◆ id3v2PrintContentContextList()

char * id3v2PrintContentContextList ( const void * toBePrinted )

Generates a string representation of a content context list for debugging.

Wrapper around listToString for use as a callback in hash table printing operations where the stored data is a List structure containing content contexts. Creates a formatted string displaying all contexts in the list. Caller must free the returned string.

Parameters

toBePrinted - List of content contexts to represent as a string

Returns: char* - Heap allocated string representation of the list. Caller must free

Definition at line 208 of file id3v2Context.c.

Functions

Detailed Description

Function Documentation

◆ id3v2CompareContentContext()

◆ id3v2ContextSerialize()

◆ id3v2ContextToJSON()

◆ id3v2CopyContentContext()

◆ id3v2CopyContentContextList()

◆ id3v2CreateAttachedPictureFrameContext()

◆ id3v2CreateAudioEncryptionFrameContext()

◆ id3v2CreateAudioSeekPointIndexFrameContext()

◆ id3v2CreateCommentFrameContext()

◆ id3v2CreateCommercialFrameContext()

◆ id3v2CreateContentContext()

◆ id3v2CreateDefaultIdentifierContextPairings()

◆ id3v2CreateEncryptedMetaFrameContext()

◆ id3v2CreateEqualizationFrameContext()

◆ id3v2CreateEventTimingCodesFrameContext()

◆ id3v2CreateGeneralEncapsulatedObjectFrameContext()

◆ id3v2CreateGenericFrameContext()

◆ id3v2CreateInvolvedPeopleListFrameContext()

◆ id3v2CreateLinkedInformationFrameContext()

◆ id3v2CreateMPEGLocationLookupTableFrameContext()

◆ id3v2CreateMusicCDIdentifierFrameContext()

◆ id3v2CreateOwnershipFrameContext()

◆ id3v2CreatePlayCounterFrameContext()

◆ id3v2CreatePopularimeterFrameContext()

◆ id3v2CreatePositionSynchronisationFrameContext()

◆ id3v2CreatePrivateFrameContext()

◆ id3v2CreateRecommendedBufferSizeFrameContext()

◆ id3v2CreateRegistrationFrameContext()

◆ id3v2CreateRelativeVolumeAdjustmentFrameContext()

◆ id3v2CreateReverbFrameContext()

◆ id3v2CreateSeekFrameContext()

◆ id3v2CreateSignatureFrameContext()

◆ id3v2CreateSynchronisedLyricFrameContext()

◆ id3v2CreateSynchronisedTempoCodesFrameContext()

◆ id3v2CreateTermsOfUseFrameContext()

◆ id3v2CreateTextFrameContext()

◆ id3v2CreateUniqueFileIdentifierFrameContext()

◆ id3v2CreateUnsynchronisedLyricFrameContext()

◆ id3v2CreateURLFrameContext()

◆ id3v2CreateUserDefinedTextFrameContext()

◆ id3v2CreateUserDefinedURLFrameContext()

◆ id3v2DeleteContentContext()

◆ id3v2DeleteContentContextList()

◆ id3v2DestroyContentContext()

◆ id3v2djb2()

◆ id3v2InsertIdentifierContextPair()

◆ id3v2PrintContentContext()

◆ id3v2PrintContentContextList()