id3dev 26.01 An ID3 metadata library

Loading...
Searching...
No Matches
id3v2Types.h File Reference

Definitions for ID3v2.x tag structure, constants, and genre enumeration. More...

`#include "id3v1/id3v1Types.h"`
`#include <stdbool.h>`
`#include <stdint.h>`
`#include <inttypes.h>`
`#include "id3dependencies/LinkedListLib/include/LinkedList.h"`
`#include "id3dependencies/HashTableLib/include/hashTable.h"`
`#include "id3dependencies/ByteStream/include/byteDefines.h"`
Include dependency graph for id3v2Types.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | _Id3v2ExtendedTagHeader
| Optional ID3v2 extended header containing supplementary tag metadata. More...
struct | _Id3v2TagHeader
| ID3v2 tag header containing version and parsing information. More...
struct | _Id3v2FrameHeader
| ID3v2 frame header containing identification and processing flags. More...
struct | _Id3v2ContentContext
| Parsing instructions for a single field within an ID3v2 frame. More...
struct | _Id3v2ContentEntry
| Parsed data field from an ID3v2 frame. More...
struct | _Id3v2Frame
| Complete ID3v2 frame structure with header, parsing contexts, and data. More...
struct | _Id3v2Tag
| Complete ID3v2 tag structure containing header and metadata frames. More...

## Macros
#define | ID3V2_TAG_ID_SIZE 3
| Size in bytes of the ID3v2 tag identifier "ID3" or "3DI" (3 bytes)
#define | ID3V2_TAG_ID_MAGIC_NUMBER_H 0x494433
| Hexadecimal magic number for ID3v2 header tag identifier "ID3" (0x494433)
#define | ID3V2_TAG_ID_MAGIC_NUMBER_F 0x334449
| Hexadecimal magic number for ID3v2 footer tag identifier "3DI" (0x334449)
#define | ID3V2_TAG_VERSION_2 2
| ID3v2.2 major version number (2)
#define | ID3V2_TAG_VERSION_3 3
| ID3v2.3 major version number (3)
#define | ID3V2_TAG_VERSION_4 4
| ID3v2.4 major version number (4)
#define | ID3V2_ENCODING_ISO_8859_1 BYTE_ISO_8859_1
| Latin-1 (ISO-8859-1) character encoding identifier.
#define | ID3V2_ENCODING_UTF16LE BYTE_UTF16LE
| UTF-16 Little Endian character encoding identifier.
#define | ID3V2_ENCODING_UTF16BE BYTE_UTF16BE
| UTF-16 Big Endian character encoding identifier.
#define | ID3V2_ENCODING_UTF8 BYTE_UTF8
| UTF-8 character encoding identifier.
#define | ID3V2_ENCODING_ASCII BYTE_ASCII
| ASCII character encoding identifier.
#define | ID3V2_ENCODING_OTHER BYTE_OTHER_ENCODING
| Unknown or unsupported character encoding identifier.
#define | ID3V2_FRAME_ID_MAX_SIZE 4
| Maximum size in bytes for a frame ID field (4 bytes).
#define | ID3V2_FRAME_FLAG_SIZE 2
| Size in bytes of a frame header's flag section (2 bytes).

## Typedefs
typedef struct _Id3v2ExtendedTagHeader | Id3v2ExtendedTagHeader
| Optional ID3v2 extended header containing supplementary tag metadata.
typedef struct _Id3v2TagHeader | Id3v2TagHeader
| ID3v2 tag header containing version and parsing information.
typedef struct _Id3v2FrameHeader | Id3v2FrameHeader
| ID3v2 frame header containing identification and processing flags.
typedef enum _Id3v2ContextType | Id3v2ContextType
| Context types for parsing and writing ID3v2 frame content fields.
typedef struct _Id3v2ContentContext | Id3v2ContentContext
| Parsing instructions for a single field within an ID3v2 frame.
typedef struct _Id3v2ContentEntry | Id3v2ContentEntry
| Parsed data field from an ID3v2 frame.
typedef struct _Id3v2Frame | Id3v2Frame
| Complete ID3v2 frame structure with header, parsing contexts, and data.
typedef struct _Id3v2Tag | Id3v2Tag
| Complete ID3v2 tag structure containing header and metadata frames.

## Enumerations
enum | _Id3v2ContextType { unknown_context = -1 , noEncoding_context , binary_context , encodedString_context , latin1Encoding_context , numeric_context , precision_context , bit_context , iter_context , adjustment_context }
| Context types for parsing and writing ID3v2 frame content fields. More...

## Detailed Description

Definitions for ID3v2.x tag structure, constants, and genre enumeration.

Author
  Ewan Jones

Version
  26.01

Date
  2023-10-02 - 2026-01-11

Copyright
  Copyright (c) 2023 - 2026

Definition in file id3v2Types.h.

## Macro Definition Documentation

## ◆ ID3V2_ENCODING_ASCII

#define ID3V2_ENCODING_ASCII BYTE_ASCII

ASCII character encoding identifier.

Definition at line 61 of file id3v2Types.h.

## ◆ ID3V2_ENCODING_ISO_8859_1

#define ID3V2_ENCODING_ISO_8859_1 BYTE_ISO_8859_1

Latin-1 (ISO-8859-1) character encoding identifier.

Definition at line 49 of file id3v2Types.h.

## ◆ ID3V2_ENCODING_OTHER

#define ID3V2_ENCODING_OTHER BYTE_OTHER_ENCODING

Unknown or unsupported character encoding identifier.

Definition at line 64 of file id3v2Types.h.

## ◆ ID3V2_ENCODING_UTF16BE

#define ID3V2_ENCODING_UTF16BE BYTE_UTF16BE

UTF-16 Big Endian character encoding identifier.

Definition at line 55 of file id3v2Types.h.

## ◆ ID3V2_ENCODING_UTF16LE

#define ID3V2_ENCODING_UTF16LE BYTE_UTF16LE

UTF-16 Little Endian character encoding identifier.

Definition at line 52 of file id3v2Types.h.

## ◆ ID3V2_ENCODING_UTF8

#define ID3V2_ENCODING_UTF8 BYTE_UTF8

UTF-8 character encoding identifier.

Definition at line 58 of file id3v2Types.h.

## ◆ ID3V2_FRAME_FLAG_SIZE

#define ID3V2_FRAME_FLAG_SIZE 2

Size in bytes of a frame header's flag section (2 bytes).

Frame flags are present in ID3v2.3 and ID3v2.4. ID3v2.2 has no frame flags.

Definition at line 76 of file id3v2Types.h.

## ◆ ID3V2_FRAME_ID_MAX_SIZE

#define ID3V2_FRAME_ID_MAX_SIZE 4

Maximum size in bytes for a frame ID field (4 bytes).

ID3v2.2 uses 3-byte frame IDs and sizes, while ID3v2.3 and ID3v2.4 use 4-byte frame IDs and sizes.

Definition at line 70 of file id3v2Types.h.

## ◆ ID3V2_TAG_ID_MAGIC_NUMBER_F

#define ID3V2_TAG_ID_MAGIC_NUMBER_F 0x334449

Hexadecimal magic number for ID3v2 footer tag identifier "3DI" (0x334449)

Definition at line 37 of file id3v2Types.h.

## ◆ ID3V2_TAG_ID_MAGIC_NUMBER_H

#define ID3V2_TAG_ID_MAGIC_NUMBER_H 0x494433

Hexadecimal magic number for ID3v2 header tag identifier "ID3" (0x494433)

Definition at line 34 of file id3v2Types.h.

## ◆ ID3V2_TAG_ID_SIZE

#define ID3V2_TAG_ID_SIZE 3

Size in bytes of the ID3v2 tag identifier "ID3" or "3DI" (3 bytes)

Definition at line 31 of file id3v2Types.h.

## ◆ ID3V2_TAG_VERSION_2

#define ID3V2_TAG_VERSION_2 2

ID3v2.2 major version number (2)

Definition at line 40 of file id3v2Types.h.

## ◆ ID3V2_TAG_VERSION_3

#define ID3V2_TAG_VERSION_3 3

ID3v2.3 major version number (3)

Definition at line 43 of file id3v2Types.h.

## ◆ ID3V2_TAG_VERSION_4

#define ID3V2_TAG_VERSION_4 4

ID3v2.4 major version number (4)

Definition at line 46 of file id3v2Types.h.

## Typedef Documentation

## ◆ Id3v2ContentContext

typedef struct _Id3v2ContentContext Id3v2ContentContext

Parsing instructions for a single field within an ID3v2 frame.

Specifies how to extract and interpret a data field from frame content. Multiple contexts form a sequence that defines the complete frame structure. Min/max semantics vary by type: for most types they represent byte bounds, for iter_context min=start index and max=iteration count, for bit_context they represent bit counts.

## ◆ Id3v2ContentEntry

typedef struct _Id3v2ContentEntry Id3v2ContentEntry

Parsed data field from an ID3v2 frame.

Generic container for a single extracted field value. Interpretation requires corresponding Id3v2ContentContext from the frame's context list. Separation of data from context metadata enables custom frame definitions.

## ◆ Id3v2ContextType

typedef enum _Id3v2ContextType Id3v2ContextType

Context types for parsing and writing ID3v2 frame content fields.

Defines how each field within a frame should be interpreted during parsing. Context types determine data interpretation, boundary detection, and reading behavior for frame content entries.

## ◆ Id3v2ExtendedTagHeader

typedef struct _Id3v2ExtendedTagHeader Id3v2ExtendedTagHeader

Optional ID3v2 extended header containing supplementary tag metadata.

Provides additional information about tag structure including CRC validation, update flags, and content restrictions. Not required for basic tag parsing. Present in ID3v2.3 and ID3v2.4 when extended header flag is set.

## ◆ Id3v2Frame

typedef struct _Id3v2Frame Id3v2Frame

Complete ID3v2 frame structure with header, parsing contexts, and data.

Combines frame identification (header), parsing instructions (contexts), and extracted data (entries). Contexts and entries lists correspond positionally - each context defines how to interpret its matching entry.

## ◆ Id3v2FrameHeader

typedef struct _Id3v2FrameHeader Id3v2FrameHeader

ID3v2 frame header containing identification and processing flags.

Specifies frame ID, preservation rules, and optional compression/encryption parameters. Determines how frame content should be parsed and whether the frame can be modified or discarded.

## ◆ Id3v2Tag

typedef struct _Id3v2Tag Id3v2Tag

Complete ID3v2 tag structure containing header and metadata frames.

Root structure representing an entire ID3v2 tag parsed from file. Header determines version and parsing behavior. Frames list contains all metadata (title, artist, artwork, etc.). Footer, when present, is not stored separately as it mirrors the header with reversed identifier "3DI".

## ◆ Id3v2TagHeader

typedef struct _Id3v2TagHeader Id3v2TagHeader

ID3v2 tag header containing version and parsing information.

Contains version identifiers, flag bits, and optional extended header. This is the first structure parsed from an ID3v2 tag and determines how the remainder of the tag is interpreted.

## Enumeration Type Documentation

## ◆ _Id3v2ContextType

enum _Id3v2ContextType

Context types for parsing and writing ID3v2 frame content fields.

Defines how each field within a frame should be interpreted during parsing. Context types determine data interpretation, boundary detection, and reading behavior for frame content entries.

Enumerator
unknown_context | Error/invalid context state (-1). Halts frame parsing when encountered. Indicates unrecognized or malformed frame structure.
noEncoding_context | Raw character data with no encoding or null terminator. Fixed-length character sequence without encoding specification.
binary_context | Binary data block with no terminator. Reads until context upper bound or frame end. Used for image data, binary payloads, etc.
encodedString_context | Text string with encoding determined by prior context with the key 'encoding'. Supports Latin-1, UTF-8, and UTF-16 encodings. Requires preceding encoding byte context.
latin1Encoding_context | Latin-1 (ISO-8859-1) null-terminated string. Fixed encoding string terminated by '\0'. No encoding byte required.
numeric_context | Integer values of 8, 16, 32, or 64 bits. Size determined by context min/max bounds.
precision_context | Floating-point values (float or double). Precision type determined by context size specification.
bit_context | Bit-level field (1-8 bits). Identifies 1 to n bits. With this context the current byte being read will not be incremented until 8 sequential bits are read. for example, this means if the following context is a binary_context it will read the same byte twice. If this context is followed by more then one bit_context it will continue reading from the position in which the proceeding context left off. Do note that max and min within the context structure now represent max and min bits instead of bytes.
iter_context | Iterator for repeating context sequences. Executes contexts from index 'min' for 'max' iterations. Min/max semantics differ: min=start index, max=iteration count.
adjustment_context | Dynamic upper bound adjustment based on prior context with key 'adjustment'. Allows runtime modification of context max value using data from previous context labeled 'adjustment'.

Definition at line 162 of file id3v2Types.h.