id3lib 3.8.3

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

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:

## 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_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, 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_Field & | operator= (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_t * | GetRawUnicodeText () const =0
virtual const unicode_t * | GetRawUnicodeTextItem (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 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 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 size_t ID3_Field::Add | ( | const char * |  | ) |
| 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::BinSize | ( |  | ) | const
| pure virtual

Implemented in ID3_FieldImpl.

virtual void ID3_Field::Clear | ( |  | ) |
| pure virtual

Implemented in ID3_FieldImpl.

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

Implemented 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

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 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 size_t ID3_Field::Get | ( | uchar * | ,
|  | size_t |
| ) |  | const
| pure virtual

Implemented in ID3_FieldImpl.

virtual ID3_TextEnc ID3_Field::GetEncoding | ( |  | ) | const
| pure virtual

Implemented in ID3_FieldImpl.

virtual ID3_FieldID ID3_Field::GetID | ( |  | ) | const
| pure virtual

Implemented in ID3_FieldImpl.

virtual size_t ID3_Field::GetNumTextItems | ( |  | ) | const
| pure virtual

Implemented in ID3_FieldImpl.

virtual const uchar* ID3_Field::GetRawBinary | ( |  | ) | 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 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 ID3_FieldType ID3_Field::GetType | ( |  | ) | const
| pure virtual

Implemented in ID3_FieldImpl.

virtual bool ID3_Field::HasChanged | ( |  | ) | const
| pure virtual

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

virtual bool ID3_Field::IsEncodable | ( |  | ) | 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.

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.

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 ID3_Field& ID3_Field::operator= | ( | const ID3_Field & |  | ) |
| pure virtual

Implemented in ID3_FieldImpl.

virtual bool ID3_Field::Parse | ( | ID3_Reader & |  | ) |
| pure virtual

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

virtual void ID3_Field::Set | ( | uint32 |  | ) |
| pure virtual

Implemented in ID3_FieldImpl.

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

Implemented in ID3_FieldImpl.

virtual size_t ID3_Field::Set | ( | 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 bool ID3_Field::SetEncoding | ( | ID3_TextEnc | enc | ) |
| 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.

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:

- include/id3/field.h
- src/field.cpp
- src/field_integer.cpp
- src/field_string_ascii.cpp
- src/field_string_unicode.cpp