Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members   File Members  

ID3_Field Class Reference

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

#include <id3/field.h>

Inheritance diagram for ID3_Field::

ID3_FieldImpl List of all members.

Public Methods

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_Field& operator= (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_Field& operator= (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, index_t) const=0
virtual const char* GetRawText () const=0
virtual const char* GetRawTextItem (index_t) const=0
virtual size_t Add (const char *)=0
virtual ID3_Field& operator= (const unicode_t *s)=0
 Shortcut for the Set operator. Performs similarly as operator=(const char *), taking a unicode_t string as a parameter rather than an ascii string. 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, index_t) const=0
virtual const unicode_t* GetRawUnicodeText () const=0
virtual const unicode_t* GetRawUnicodeTextItem (index_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 uchar* GetRawBinary () const=0
virtual void FromFile (const char *)=0
virtual void ToFile (const char *sInfo) const=0
virtual ID3_Field& operator= (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 Methods

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, index_t)), Set(const char*), Add(const char*), and operator=(const char *) methods.

A Unicode field also supports Get(unicode_t*, size_t, index_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.42 2001/09/08 21:33:18 shadrack Exp
See also:
ID3_Tag , ID3_Frame , ID3_Err

Definition at line 36 of file field.h.

Constructor & Destructor Documentation

ID3_Field::~ID3_Field ( ) [inline, protected, virtual]
 

Definition at line 90 of file field.h.

ID3_Field::ID3_Field ( ) [inline, protected]
 

Definition at line 93 of file field.h.

Member Function Documentation

size_t ID3_Field::Add ( const unicode_t * data ) [pure virtual]
 

Parameters:
data  

Reimplemented in ID3_FieldImpl.

size_t ID3_Field::Add ( const char * data ) [pure virtual]
 

Parameters:
data  

Reimplemented in ID3_FieldImpl.

size_t ID3_Field::BinSize ( ) const [pure virtual]
 

Reimplemented in ID3_FieldImpl.

Referenced by parseFrames().

void ID3_Field::Clear ( ) [pure virtual]
 

Reimplemented in ID3_FieldImpl.

void ID3_Field::FromFile ( const char * info ) [pure virtual]
 

Parameters:
info  

Reimplemented in ID3_FieldImpl.

size_t ID3_Field::Get ( uchar * buffer,
size_t max_bytes ) const [pure virtual]
 

Parameters:
buffer  
max_bytes  

Reimplemented in ID3_FieldImpl.

size_t ID3_Field::Get ( unicode_t * buffer,
size_t maxLength,
index_t itemNum ) const [pure virtual]
 

Parameters:
buffer  
maxLength  
itemNum  

Reimplemented in ID3_FieldImpl.

size_t ID3_Field::Get ( unicode_t * buffer,
size_t maxLength ) const [pure virtual]
 

Parameters:
buffer  
maxLength  

Reimplemented in ID3_FieldImpl.

size_t ID3_Field::Get ( char * buf,
size_t maxLen,
index_t index ) const [pure virtual]
 

Parameters:
buf  
maxLen  
index  

Reimplemented in ID3_FieldImpl.

size_t ID3_Field::Get ( char * buffer,
size_t maxLength ) const [pure virtual]
 

Parameters:
buffer  
maxLength  

Reimplemented in ID3_FieldImpl.

uint32 ID3_Field::Get ( ) const [pure virtual]
 

Returns the value of the integer field. 

   uint32 picType = myFrame.GetField(ID3FN_PICTURETYPE)->Get();

Returns:
The value of the integer field

Reimplemented in ID3_FieldImpl.

Referenced by ID3_GetString(), ID3_GetSyncLyricsInfo(), parseFields(), and renderFields().

ID3_TextEnc ID3_Field::GetEncoding ( ) const [pure virtual]
 

Reimplemented in ID3_FieldImpl.

Referenced by ID3_GetString().

ID3_FieldID ID3_Field::GetID ( ) const [pure virtual]
 

Reimplemented in ID3_FieldImpl.

Referenced by ID3_FrameImpl::_InitFields(), parseFields(), and renderFields().

size_t ID3_Field::GetNumTextItems ( ) const [pure virtual]
 

Reimplemented in ID3_FieldImpl.

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

Reimplemented in ID3_FieldImpl.

Referenced by ID3_GetSyncLyrics(), and parseFrames().

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

Reimplemented in ID3_FieldImpl.

Referenced by ID3_TagImpl::Find().

const char * ID3_Field::GetRawTextItem ( index_t index ) const [pure virtual]
 

Parameters:
index  

Reimplemented in ID3_FieldImpl.

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

Reimplemented in ID3_FieldImpl.

Referenced by ID3_TagImpl::Find().

const unicode_t * ID3_Field::GetRawUnicodeTextItem ( index_t index ) const [pure virtual]
 

Parameters:
index  

Reimplemented in ID3_FieldImpl.

ID3_FieldType ID3_Field::GetType ( ) const [pure virtual]
 

Reimplemented in ID3_FieldImpl.

Referenced by parseFields().

bool ID3_Field::HasChanged ( ) const [pure virtual]
 

Reimplemented in ID3_FieldImpl.

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

Parameters:
spec  

Reimplemented in ID3_FieldImpl.

Referenced by parseFields(), and renderFields().

bool ID3_Field::IsEncodable ( ) const [pure virtual]
 

Reimplemented in ID3_FieldImpl.

bool ID3_Field::Parse ( ID3_Reader & reader ) [pure virtual]
 

Parameters:
reader  

Reimplemented in ID3_FieldImpl.

Referenced by parseFields().

void ID3_Field::Render ( ID3_Writer & writer ) const [pure virtual]
 

Parameters:
writer  

Reimplemented in ID3_FieldImpl.

Referenced by renderFields().

size_t ID3_Field::Set ( const uchar * buf,
size_t size ) [pure virtual]
 

Parameters:
buf  
size  

Reimplemented in ID3_FieldImpl.

size_t ID3_Field::Set ( const unicode_t * data ) [pure virtual]
 

Parameters:
data  

Reimplemented in ID3_FieldImpl.

size_t ID3_Field::Set ( const char * data ) [pure virtual]
 

Parameters:
data  

Reimplemented in ID3_FieldImpl.

void ID3_Field::Set ( uint32 val ) [pure virtual]
 

Parameters:
val  

Reimplemented in ID3_FieldImpl.

Referenced by ID3_AddAlbum(), ID3_AddArtist(), ID3_AddComment(), ID3_AddGenre(), ID3_AddLyricist(), ID3_AddLyrics(), ID3_AddSyncLyrics(), ID3_AddTitle(), ID3_AddTrack(), ID3_AddYear(), ID3_FieldImpl::Set(), ID3_FieldImpl::operator=(), and readTextFrame().

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

Parameters:
enc  

Reimplemented in ID3_FieldImpl.

Referenced by ID3_GetString(), parseFields(), and renderFields().

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, index_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();

Returns:
The size of the field, either in bytes (for binary or integer fields) or characters (for strings).

Reimplemented in ID3_FieldImpl.

Referenced by ID3_TagImpl::Find(), ID3_GetString(), and ID3_GetSyncLyricsInfo().

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

Parameters:
sInfo  

Reimplemented in ID3_FieldImpl.

ID3_Field & ID3_Field::operator= ( const ID3_Field & rhs ) [pure virtual]
 

Parameters:
rhs  

Reimplemented in ID3_FieldImpl.

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:
string   The string to assign to the field
Parameters:
s  

Reimplemented in ID3_FieldImpl.

ID3_Field & ID3_Field::operator= ( const char * s ) [pure virtual]
 

Shortcut for the Set operator.

Parameters:
data   The string to assign to this field
See also:
Set(const char*)
Parameters:
s  

Reimplemented in ID3_FieldImpl.

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

A shortcut for the Set method. 

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

Reimplemented in ID3_FieldImpl.

The documentation for this class was generated from the following files:
Generated at Sat Sep 8 15:51:12 2001 for id3lib by doxygen1.2.8 written by Dimitri van Heesch, © 1997-2001