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 Member Functions

virtual void Clear ()=0
virtual size_t Size () const=0
 Returns the size of a field.
virtual size_t BinSize () const=0
virtual size_t GetNumTextItems () const=0
virtual ID3_Fieldoperator= (uint32 val)=0
 A shortcut for the Set method.
virtual void Set (uint32)=0
virtual uint32 Get () const=0
 Returns the value of the integer field.
virtual ID3_Fieldoperator= (const char *s)=0
 Shortcut for the Set operator.
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.
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

virtual 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

virtual void ID3_Field::Clear (  )  [pure virtual]

Implemented in ID3_FieldImpl.

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

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

Implemented in ID3_FieldImpl.

Referenced by ID3_GetPictureData(), ID3_GetPictureDataOfPicType(), ID3_GetString(), ID3_GetSyncLyrics(), and ID3_GetSyncLyricsInfo().

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

Implemented in ID3_FieldImpl.

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

Implemented 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)

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

Referenced by ID3_AddAlbum(), ID3_AddArtist(), ID3_AddComment(), ID3_AddGenre(), ID3_AddLyricist(), ID3_AddLyrics(), ID3_AddPicture(), ID3_AddSyncLyrics(), ID3_AddTitle(), ID3_AddTrack(), ID3_AddYear(), and dami::mm::parse().

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

Implemented in ID3_FieldImpl.

Referenced by ID3_GetDescriptionOfPicType(), ID3_GetMimeTypeOfPicType(), ID3_GetPictureDataOfPicType(), ID3_GetString(), ID3_GetSyncLyricsInfo(), and ID3_RemovePictureType().

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

Shortcut for the Set operator.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented 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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

Referenced by ID3_GetSyncLyrics().

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

Implemented in ID3_FieldImpl.

Referenced by ID3_AddPicture().

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

Implemented in ID3_FieldImpl.

Referenced by ID3_GetPictureData(), and ID3_GetPictureDataOfPicType().

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

Referenced by ID3_FrameImpl::_InitFields().

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

Implemented in ID3_FieldImpl.

Referenced by ID3_FieldImpl::operator=().

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

Implemented in ID3_FieldImpl.

Referenced by ID3_GetString().

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

Implemented in ID3_FieldImpl.

Referenced by ID3_GetString().

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.


The documentation for this class was generated from the following files:
Generated on Mon Aug 20 17:48:46 2007 for id3lib by  doxygen 1.5.2