id3lib  3.8.3
Public Member Functions | Protected Member Functions | List of all members
ID3_Field Class Referenceabstract

The representative class of an ID3v2 field. More...

#include <id3/field.h>

Inheritance diagram for ID3_Field:
ID3_FieldImpl

Public Member Functions

virtual void Clear ()=0
 
virtual size_t Size () const =0
 Returns the size of a field. More...
 
virtual size_t BinSize () const =0
 
virtual size_t GetNumTextItems () const =0
 
virtual ID3_Fieldoperator= (uint32 val)=0
 A shortcut for the Set method. More...
 
virtual void Set (uint32)=0
 
virtual uint32 Get () const =0
 Returns the value of the integer field. More...
 
virtual ID3_Fieldoperator= (const char *s)=0
 Shortcut for the Set operator. More...
 
virtual size_t Set (const char *)=0
 
virtual size_t Get (char *, size_t) const =0
 
virtual size_t Get (char *, size_t, size_t) const =0
 
virtual const char * GetRawText () const =0
 
virtual const char * GetRawTextItem (size_t) const =0
 
virtual size_t Add (const char *)=0
 
virtual ID3_Fieldoperator= (const unicode_t *s)=0
 Shortcut for the Set operator. More...
 
virtual size_t Set (const unicode_t *)=0
 
virtual size_t Get (unicode_t *buffer, size_t) const =0
 
virtual size_t Get (unicode_t *buffer, size_t, size_t) const =0
 
virtual const unicode_tGetRawUnicodeText () const =0
 
virtual const unicode_tGetRawUnicodeTextItem (size_t) const =0
 
virtual size_t Add (const unicode_t *)=0
 
virtual size_t Set (const uchar *, size_t)=0
 
virtual size_t Get (uchar *, size_t) const =0
 
virtual const ucharGetRawBinary () const =0
 
virtual void FromFile (const char *)=0
 
virtual void ToFile (const char *sInfo) const =0
 
virtual ID3_Fieldoperator= (const ID3_Field &)=0
 
virtual bool InScope (ID3_V2Spec spec) const =0
 
virtual ID3_FieldID GetID () const =0
 
virtual ID3_FieldType GetType () const =0
 
virtual bool SetEncoding (ID3_TextEnc enc)=0
 
virtual ID3_TextEnc GetEncoding () const =0
 
virtual bool IsEncodable () const =0
 
virtual void Render (ID3_Writer &) const =0
 
virtual bool Parse (ID3_Reader &)=0
 
virtual bool HasChanged () const =0
 

Protected Member Functions

virtual ~ID3_Field ()
 
 ID3_Field ()
 

Detailed Description

The representative class of an ID3v2 field.

As a general rule, you need never create an object of this type. id3lib uses them internally as part of the id3_frame class. You must know how to interact with these objects, though, and that's what this section is about.

The ID3_Field contains many overloaded methods to provide these facilities for four different data types: integers, ASCII strings, Unicode strings, and binary data.

An integer field supports the Get(), Set(uint32), and operator=(uint32) methods.

Both types of strings support the GetNumTextItems() method.

An ASCII string field supports the Get(char*, size_t, size_t)), Set(const char*), Add(const char*), and operator=(const char*) methods.

A Unicode field also supports Get(unicode_t*, size_t, size_t), Set(const unicode_t*), Add(const unicode_t*), and operator=(const unicode_t*). Without elaborating, the Unicode methods behave exactly the same as their ASCII counterparts, taking unicode_t pointers in place of char pointers.

All strings in id3lib are handled internally as Unicode. This means that when you set a field with an ASCII source type, it will be converted and stored internally as a Unicode string. id3lib will handle all necessary conversions when parsing, rendering, and retrieving. If you set a field as an ASCII string, then try to read the string into a unicode_t buffer, id3lib will automatically convert the string into Unicode so this will function as expected. The same holds true in reverse. Of course, when converting from Unicode to ASCII, you will experience problems when the Unicode string contains characters that don't map to ISO-8859-1.

A binary field supports the Get(uchar*, size_t), Set(const uchar*, size_t), FromFile(const char*), and ToFile(const char*) methods. The binary field holds miscellaneous data that can't easily be described any other way, such as a JPEG image.

As a general implementation note, you should be prepared to support all fields in an id3lib frame, even if all fields in the id3lib version of the frame aren't present in the id3v2 version. This is because of frames like the picture frame, which changed slightly from one version of the id3v2 standard to the next (the IMAGEFORMAT format in 2.0 changed to a MIMETYPE in 3.0). If you support all id3lib fields in a given frame, id3lib can generate the correct id3v2 frame for the id3v2 version you wish to support. Alternatively, just support the fields you know will be used in, say, 3.0 if you only plan to generate 3.0 tags.

Author
Dirk Mahoney
Version
Id
field.cpp,v 1.47 2002/11/03 00:41:27 t1mpy Exp
See also
ID3_Tag
ID3_Frame
ID3_Err

Definition at line 36 of file field.h.

Constructor & Destructor Documentation

◆ ~ID3_Field()

virtual ID3_Field::~ID3_Field ( )
inlineprotectedvirtual

Definition at line 90 of file field.h.

◆ ID3_Field()

ID3_Field::ID3_Field ( )
inlineprotected

Definition at line 93 of file field.h.

Member Function Documentation

◆ Add() [1/2]

virtual size_t ID3_Field::Add ( const char *  )
pure virtual

Implemented in ID3_FieldImpl.

◆ Add() [2/2]

virtual size_t ID3_Field::Add ( const unicode_t )
pure virtual

Implemented in ID3_FieldImpl.

◆ BinSize()

virtual size_t ID3_Field::BinSize ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ Clear()

virtual void ID3_Field::Clear ( )
pure virtual

Implemented in ID3_FieldImpl.

◆ FromFile()

virtual void ID3_Field::FromFile ( const char *  )
pure virtual

Implemented in ID3_FieldImpl.

◆ Get() [1/6]

uint32 ID3_Field::Get ( ) const
pure virtual

Returns the value of the integer field.

uint32 picType = myFrame.GetField(ID3FN_PICTURETYPE)->Get();
@ ID3FN_PICTURETYPE
Picture type field.
Definition: globals.h:210
Returns
The value of the integer field

Implemented in ID3_FieldImpl.

◆ Get() [2/6]

virtual size_t ID3_Field::Get ( char *  ,
size_t   
) const
pure virtual

Implemented in ID3_FieldImpl.

◆ Get() [3/6]

virtual size_t ID3_Field::Get ( char *  ,
size_t  ,
size_t   
) const
pure virtual

Implemented in ID3_FieldImpl.

◆ Get() [4/6]

virtual size_t ID3_Field::Get ( uchar ,
size_t   
) const
pure virtual

Implemented in ID3_FieldImpl.

◆ Get() [5/6]

virtual size_t ID3_Field::Get ( unicode_t buffer,
size_t   
) const
pure virtual

Implemented in ID3_FieldImpl.

◆ Get() [6/6]

virtual size_t ID3_Field::Get ( unicode_t buffer,
size_t  ,
size_t   
) const
pure virtual

Implemented in ID3_FieldImpl.

◆ GetEncoding()

virtual ID3_TextEnc ID3_Field::GetEncoding ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ GetID()

virtual ID3_FieldID ID3_Field::GetID ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ GetNumTextItems()

virtual size_t ID3_Field::GetNumTextItems ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ GetRawBinary()

virtual const uchar* ID3_Field::GetRawBinary ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ GetRawText()

virtual const char* ID3_Field::GetRawText ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ GetRawTextItem()

virtual const char* ID3_Field::GetRawTextItem ( size_t  ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ GetRawUnicodeText()

virtual const unicode_t* ID3_Field::GetRawUnicodeText ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ GetRawUnicodeTextItem()

virtual const unicode_t* ID3_Field::GetRawUnicodeTextItem ( size_t  ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ GetType()

virtual ID3_FieldType ID3_Field::GetType ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ HasChanged()

virtual bool ID3_Field::HasChanged ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ InScope()

virtual bool ID3_Field::InScope ( ID3_V2Spec  spec) const
pure virtual

Implemented in ID3_FieldImpl.

◆ IsEncodable()

virtual bool ID3_Field::IsEncodable ( ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ operator=() [1/4]

ID3_Field & ID3_Field::operator= ( const char *  data)
pure virtual

Shortcut for the Set operator.

Parameters
dataThe string to assign to this field
See also
Set(const char*)

Implemented in ID3_FieldImpl.

◆ operator=() [2/4]

virtual ID3_Field& ID3_Field::operator= ( const ID3_Field )
pure virtual

Implemented in ID3_FieldImpl.

◆ operator=() [3/4]

ID3_Field & ID3_Field::operator= ( const unicode_t s)
pure virtual

Shortcut for the Set operator.

Performs similarly as operator=(const char*), taking a unicode_t string as a parameter rather than an ascii string.

See also
Set(const unicode_t*)
Parameters
stringThe string to assign to the field

Implemented in ID3_FieldImpl.

◆ operator=() [4/4]

ID3_Field & ID3_Field::operator= ( uint32  val)
pure virtual

A shortcut for the Set method.

myFrame.GetField(ID3FN_PICTURETYPE)->= 0x0B;
Parameters
valThe data to assign to this field
See also
Set(uint32)

Implemented in ID3_FieldImpl.

◆ Parse()

virtual bool ID3_Field::Parse ( ID3_Reader )
pure virtual

Implemented in ID3_FieldImpl.

◆ Render()

virtual void ID3_Field::Render ( ID3_Writer ) const
pure virtual

Implemented in ID3_FieldImpl.

◆ Set() [1/4]

virtual size_t ID3_Field::Set ( const char *  )
pure virtual

Implemented in ID3_FieldImpl.

◆ Set() [2/4]

virtual size_t ID3_Field::Set ( const uchar ,
size_t   
)
pure virtual

Implemented in ID3_FieldImpl.

◆ Set() [3/4]

virtual size_t ID3_Field::Set ( const unicode_t )
pure virtual

Implemented in ID3_FieldImpl.

◆ Set() [4/4]

virtual void ID3_Field::Set ( uint32  )
pure virtual

Implemented in ID3_FieldImpl.

◆ SetEncoding()

virtual bool ID3_Field::SetEncoding ( ID3_TextEnc  enc)
pure virtual

Implemented in ID3_FieldImpl.

◆ Size()

size_t ID3_Field::Size ( ) const
pure virtual

Returns the size of a field.

The value returned is dependent on the type of the field. For ASCII strings, this returns the number of characters in the field, not including any NULL-terminator. The same holds true for Unicode—it returns the number of characters in the field, not bytes, and this does not include the Unicode BOM, which isn't put in a Unicode string obtained by the Get(unicode_t*, size_t, size_t) method anyway. For binary and integer fields, this returns the number of bytes in the field.

size_t howBig = myFrame.GetField(ID3FN_DATA)->Size();
@ ID3FN_DATA
Data field.
Definition: globals.h:203
Returns
The size of the field, either in bytes (for binary or integer fields) or characters (for strings).

Implemented in ID3_FieldImpl.

◆ ToFile()

virtual void ID3_Field::ToFile ( const char *  sInfo) const
pure virtual

Implemented in ID3_FieldImpl.


The documentation for this class was generated from the following files: