Main Page Class Hierarchy Compound List File List Compound Members File Members
ID3_Field Class Reference
The representative class of an ID3v2 field.
More...
#include <field.h>
List of all members.
Public Methods |
| ~ID3_Field () |
void | Clear () |
| Clears any data and frees any memory associated with the field. More...
|
size_t | Size () const |
| Returns the size of a field. More...
|
size_t | BinSize () const |
size_t | GetNumTextItems () const |
| Returns the number of items in a text list. More...
|
ID3_Field & | operator= (uint32 val) |
| A shortcut for the Set method. More...
|
void | Set (uint32) |
| Sets the value of the field to the specified integer. More...
|
uint32 | Get () const |
| Returns the value of the integer field. More...
|
ID3_Field & | operator= (const char *s) |
| Shortcut for the Set operator. More...
|
size_t | Set (const char *) |
size_t | Get (char *, size_t) const |
| Copies the contents of the field into the supplied buffer, up to the number of characters specified; for fields with multiple entries, the optional third parameter indicates which of the fields to retrieve. More...
|
size_t | Get (char *, size_t, size_t) const |
size_t | Add (const char *) |
ID3_Field & | operator= (const unicode_t *s) |
| 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...
|
size_t | Set (const unicode_t *) |
size_t | Get (unicode_t *buffer, size_t) const |
| Copies the contents of the field into the supplied buffer, up to the number of characters specified; for fields with multiple entries, the optional third parameter indicates which of the fields to retrieve. More...
|
size_t | Get (unicode_t *buffer, size_t, size_t) const |
size_t | Add (const unicode_t *) |
size_t | Set (const uchar *, size_t) |
| Copies the supplied unicode string to the field. More...
|
size_t | Get (uchar *, size_t) const |
| Copies the field's internal string to the buffer. More...
|
void | FromFile (const char *) |
| Copies binary data from the file specified to the field. More...
|
void | ToFile (const char *sInfo) const |
| Copies binary data from the field to the specified file. More...
|
ID3_Field & | operator= (const ID3_Field &) |
const uchar * | GetBinary () const |
bool | InScope (ID3_V2Spec spec) const |
ID3_FieldID | GetID () const |
ID3_FieldType | GetType () const |
bool | SetEncoding (ID3_TextEnc enc) |
ID3_TextEnc | GetEncoding () const |
bool | IsEncodable () const |
size_t | Render (uchar *buffer) const |
size_t | Parse (const uchar *buffer, size_t buffSize) |
bool | HasChanged () const |
Protected Methods |
size_t | RenderInteger (uchar *buffer) const |
size_t | RenderString (uchar *buffer) const |
size_t | RenderBinary (uchar *buffer) const |
size_t | ParseInteger (const uchar *buffer, size_t) |
size_t | ParseASCIIString (const uchar *buffer, size_t) |
size_t | ParseUnicodeString (const uchar *buffer, size_t) |
size_t | ParseBinary (const uchar *buffer, size_t) |
Friends |
class | ID3_Frame |
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.30 2000/09/14 22:31:39 eldamitri Exp
-
See also:
-
ID3_Tag , ID3_Frame , ID3_Err
Constructor & Destructor Documentation
ID3_Field::~ID3_Field
|
(  |
|
) |
|
|
Member Function Documentation
size_t ID3_Field::Add
|
(  |
const unicode_t * |
str |
) |
|
|
size_t ID3_Field::Add
|
(  |
const char * |
str |
) |
|
|
size_t ID3_Field::BinSize
|
(  |
|
) |
const |
|
void ID3_Field::Clear
|
(  |
|
) |
|
|
void ID3_Field::FromFile
|
(  |
const char * |
info |
) |
|
|
|
Copies binary data from the file specified to the field.
myFrame.Field(ID3FN_DATA).FromFile("mypic.jpg"); |
size_t ID3_Field::Get
|
(  |
uchar * |
buffer, |
|
|
|
|
|
size_t |
max_bytes |
|
)  |
const |
|
|
Copies the field's internal string to the buffer.
It copies the data in the field into the buffer, for as many bytes as the field contains, or the size of buffer, whichever is smaller.
uchar buffer[1024];
myFrame.Field(ID3FN_DATA).Get(buffer, sizeof(buffer)); |
size_t ID3_Field::Get
|
(  |
unicode_t * |
buffer, |
|
|
|
|
|
size_t |
, |
|
|
|
|
|
size_t |
|
|
)  |
const |
|
size_t ID3_Field::Get
|
(  |
unicode_t * |
buffer, |
|
|
|
|
|
size_t |
maxLength |
|
)  |
const |
|
|
Copies the contents of the field into the supplied buffer, up to the number of characters specified; for fields with multiple entries, the optional third parameter indicates which of the fields to retrieve.
Performs similarly as the ASCII Get(char *, size_t, index_t) method, taking a unicode_t string as a parameter rather than an ascii string. The maxChars parameter still represents the maximum number of characters, not bytes.
unicode_t myBuffer[1024];
size_t charsUsed = myFrame.Field(ID3FN_UNICODE).Get(buffer, 1024); -
Parameters:
-
buffer
|
Where the field's data is copied to |
maxChars
|
The maximum number of characters to copy to the buffer. |
itemNum
|
For fields with multiple items (such as the involved people frame, the item number to retrieve. |
-
See also:
-
Get(char *, size_t, index_t)
|
size_t ID3_Field::Get
|
(  |
char * |
, |
|
|
|
|
|
size_t |
, |
|
|
|
|
|
size_t |
|
|
)  |
const |
|
size_t ID3_Field::Get
|
(  |
char * |
buffer, |
|
|
|
|
|
size_t |
maxLength |
|
)  |
const |
|
|
Copies the contents of the field into the supplied buffer, up to the number of characters specified; for fields with multiple entries, the optional third parameter indicates which of the fields to retrieve.
The third parameter is useful when using text lists (see Add(const char*) for more details). The default value for this third parameter is 1, which returns the entire string if the field contains only one item.
It returns the number of characters (not bytes necessarily, and not including any NULL terminator) of the supplied buffer that are now used.
char myBuffer[1024];
size_t charsUsed = myFrame.Field(ID3FN_TEXT).Get(buffer, 1024);
It fills the buffer with as much data from the field as is present in the field, or as large as the buffer, whichever is smaller.
char myBuffer[1024];
size_t charsUsed = myFrame.Field(ID3FN_TEXT).Get(buffer, 1024, 3);
This fills the buffer with up to the first 1024 characters from the third element of the text list.
-
See also:
-
Add(const char*)
|
uint32 ID3_Field::Get
|
(  |
|
) |
const [inline] |
|
|
Returns the value of the integer field.
uint32 picType = myFrame.Field(ID3FN_PICTURETYPE).Get();
-
Returns:
-
The value of the integer field
|
const uchar* ID3_Field::GetBinary
|
(  |
|
) |
const [inline] |
|
ID3_TextEnc ID3_Field::GetEncoding
|
(  |
|
) |
const [inline] |
|
size_t ID3_Field::GetNumTextItems
|
(  |
|
) |
const |
|
|
Returns the number of items in a text list.
size_t numItems = myFrame.Field(ID3FN_UNICODE).GetNumItems();
-
Returns:
-
The number of items in a text list.
|
bool ID3_Field::HasChanged
|
(  |
|
) |
const |
|
bool ID3_Field::InScope
|
(  |
ID3_V2Spec |
spec |
) |
const [inline] |
|
bool ID3_Field::IsEncodable
|
(  |
|
) |
const [inline] |
|
size_t ID3_Field::Parse
|
(  |
const uchar * |
buffer, |
|
|
|
|
|
size_t |
buffSize |
|
)  |
|
|
size_t ID3_Field::ParseASCIIString
|
(  |
const uchar * |
buffer, |
|
|
|
|
|
size_t |
nSize |
|
)  |
[protected] |
|
size_t ID3_Field::ParseBinary
|
(  |
const uchar * |
buffer, |
|
|
|
|
|
size_t |
size |
|
)  |
[protected] |
|
size_t ID3_Field::ParseInteger
|
(  |
const uchar * |
buffer, |
|
|
|
|
|
size_t |
nSize |
|
)  |
[protected] |
|
size_t ID3_Field::ParseUnicodeString
|
(  |
const uchar * |
buffer, |
|
|
|
|
|
size_t |
nSize |
|
)  |
[protected] |
|
size_t ID3_Field::Render
|
(  |
uchar * |
buffer |
) |
const |
|
size_t ID3_Field::RenderBinary
|
(  |
uchar * |
buffer |
) |
const [protected] |
|
size_t ID3_Field::RenderInteger
|
(  |
uchar * |
buffer |
) |
const [protected] |
|
size_t ID3_Field::RenderString
|
(  |
uchar * |
buffer |
) |
const [protected] |
|
size_t ID3_Field::Set
|
(  |
const uchar * |
newData, |
|
|
|
|
|
size_t |
newSize |
|
)  |
|
|
|
Copies the supplied unicode string to the field.
Again, like the string types, the binary Set() function copies the data so you may dispose of the source data after a call to this method. |
size_t ID3_Field::Set
|
(  |
const unicode_t * |
string |
) |
|
|
size_t ID3_Field::Set
|
(  |
const char * |
string |
) |
|
|
void ID3_Field::Set
|
(  |
uint32 |
val |
) |
|
|
|
Sets the value of the field to the specified integer.
-
Parameters:
-
data
|
The data to assign to this field |
|
size_t ID3_Field::Size
|
(  |
|
) |
const |
|
|
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, no 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.Field(ID3FN_DATA).Size();
-
Returns:
-
The size of the field, either in bytes (for binary or integer fields) or characters (for strings).
|
void ID3_Field::ToFile
|
(  |
const char * |
info |
) |
const |
|
|
Copies binary data from the field to the specified file.
myFrame.Field(ID3FN_DATA).ToFile("output.bin"); |
ID3_Field & ID3_Field::operator=
|
(  |
const ID3_Field & |
rhs |
) |
|
|
ID3_Field & ID3_Field::operator=
|
(  |
const unicode_t * |
s |
) |
[inline] |
|
|
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 |
|
ID3_Field & ID3_Field::operator=
|
(  |
const char * |
data |
) |
[inline] |
|
|
Shortcut for the Set operator.
-
Parameters:
-
data
|
The string to assign to this field |
-
See also:
-
Set(const char*)
|
ID3_Field & ID3_Field::operator=
|
(  |
uint32 |
val |
) |
[inline] |
|
|
A shortcut for the Set method.
myFrame.Field(ID3FN_PICTURETYPE) = 0x0B; -
Parameters:
-
val
|
The data to assign to this field |
-
See also:
-
Set(uint32)
|
Friends And Related Function Documentation
friend class ID3_Frame [friend]
|
|
Member Data Documentation
uchar* ID3_Field::_binary
|
|
The documentation for this class was generated from the following files:
Generated at Wed Sep 5 16:53:38 2001 for id3lib by
1.2.9.1 written by Dimitri van Heesch,
© 1997-2001