PrimoBurner(tm) for C++  4.6
CD, DVD and Blu-ray Software Development Kit
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Pages
CDText Class Referenceabstract

The CDText interface is used to manipulate the CD-TEXT data of an audio CD. More...

#include <PrimoBurnerAPI.h>

Inherits Reference.

Public Member Functions

virtual CDTextCodePage::Enum codePage () const =0
 Returns the code page used by CDText for CD-TEXT encoding/decoding. More...
 
virtual int count () const =0
 The count method gets the number of CD-TEXT items. More...
 
virtual bool_t getRawData (uint8_t **rawDataBuffer, uint16_t *bufferSize) const =0
 Obtains a pointer to the raw CD-TEXT data buffer of an CDText object. More...
 
virtual const char_t * item (CDTextType::Enum type, int index) const =0
 The item method retrieves a specific CD text entry for specific track number. More...
 
virtual CDTextLanguage::Enum language () const =0
 Gets the CD-TEXT language identifier. More...
 
virtual void setCodePage (CDTextCodePage::Enum codePage)=0
 Sets the code page to use when encoding/decoding CD-TEXT strings. More...
 
virtual bool_t setItem (CDTextType::Enum type, int index, const char_t *text)=0
 The setItem method sets a specific CD text entry for specific track number. More...
 
virtual void setLanguage (CDTextLanguage::Enum languageId)=0
 Sets the CD-TEXT language. More...
 
virtual bool_t setRawData (uint8_t *data, uint16_t size)=0
 Sets raw CD-TEXT data into the CDText buffer. More...
 
- Public Member Functions inherited from Reference
virtual int32_t release () const =0
 Releases the instance. More...
 
virtual int32_t retain () const =0
 Retains the instance. More...
 
virtual int32_t retainCount () const =0
 Returns the current reference count. More...
 

Detailed Description

The CDText interface is used to manipulate the CD-TEXT data of an audio CD.

CD Text is an extension of the existing audio CD standard that adds the ability to store text information like album titles, artist names, and song titles on a music CD. This information is stored in such a way that it doesn't interfere with the normal operation of any CD players or CDROM drives. You could store up to 5,000 characters with alphabet/numbers , and about 2,500 characters with Kanji on a single CD. Not all devices support CD Text though. To find out if a particular device supports CD-TEXT use the canReadCDText method of the CDFeatures interface.

See Also
Device

Member Function Documentation

virtual CDTextCodePage::Enum codePage ( ) const
pure virtual

Returns the code page used by CDText for CD-TEXT encoding/decoding.

Returns
If CDText::setCodePage has not been called this method returns CDTextCodePage::System, otherwise returns the value previously set with CDText::setCodePage.
See Also
CDTextCodePage::Enum
CDText::setCodePage
CDText::setAt
CDText::item
virtual int count ( ) const
pure virtual

The count method gets the number of CD-TEXT items.

Returns
The number of CD-TEXT items.
See Also
CDText::item
virtual bool_t getRawData ( uint8_t **  rawDataBuffer,
uint16_t *  bufferSize 
) const
pure virtual

Obtains a pointer to the raw CD-TEXT data buffer of an CDText object.

Parameters
rawDataBuffer[out] Address of a variable that receives a pointer to the buffer which contains the raw CD-TEXT data. The buffer is read only and should not be written to.
bufferSize[out] Pointer to uint16_t data type that receives the size, in bytes, of the buffer.
Returns
1 Success.
0 There was an error.
virtual const char_t* item ( CDTextType::Enum  type,
int  index 
) const
pure virtual

The item method retrieves a specific CD text entry for specific track number.

Parameters
typeThe type of the CD-TEXT information that is requested
indexThe index of the track for which the CD text data is requested. Set this parameter to 0 for the album wide information like album artist, album title. Use index from 1 to 99 to retrieve the CD text for all audio tracks. The value of this parameter should be in the 0 to 99 range.

The CDTextType::Genre (and CDTextType::GenreText) and CDTextType::DiscId attributes can be requested only when nIndex is set to 0. This method will fail if you try to retrieve the genre or the disc id of a track with index greater than 0.

Returns
A zero terminated string containing the requested CD Text data. The return value for CDTextType::Genre attribute is the text representation of the CD-TEXT genre code. See CDTextGenreCode::Enum enumeration for a complete list of the available genre codes.
An empty, zero length string if there is no data available for the requested text type and track index.
NULL If the request was made using invalid arguments.
See Also
Device
CDText
CDTextType::Enum
CDTextGenreCode::Enum
CDText::setItem
CDText::setCodePage
virtual CDTextLanguage::Enum language ( ) const
pure virtual

Gets the CD-TEXT language identifier.

Returns
CDTextLanguage::Enum enum value.
See Also
CDText::setLanguage
CDTextLanguage::Enum
virtual void setCodePage ( CDTextCodePage::Enum  codePage)
pure virtual

Sets the code page to use when encoding/decoding CD-TEXT strings.

The default value is CDTextCodePage::System. This method should be called before CDText::setItem or CDText::item is used. It is preferable that the method be called once during the lifetime of the CDText object.

Parameters
codePageThe identifier of the code page to use for encoding/decoding CD-TEXT strings.
See Also
CDTextCodePage::Enum
CDText::codePage
CDText::setAt
CDText::item
virtual bool_t setItem ( CDTextType::Enum  type,
int  index,
const char_t *  text 
)
pure virtual

The setItem method sets a specific CD text entry for specific track number.

The Genre and CDTextType::DiscId attributes can only be set only when nIndex is 0. This method will fail if you try to set the genre or the disc id of a track with index greater than 0.

Parameters
typeThe type of the CD Text that should be set.
indexThe track number for which you want to set the CD text data. Set this parameter to 0 for the album wide text entries. Use index from 1 to 99 to set the CD text for each track on the CD. The value of this parameter should be in the 0 to 99 range.
textThe CD Text data. This parameter must point to a valid zero terminated string. You could store up to 5,000 characters with alphabet/numbers , and about 2,500 characters with Kanji on a single CD. When you set the CDTextType::Genre attribute text parameter should be set to the text representation of the CD-TEXT genre code. For a complete list of genre codes see CDTextGenreCode::Enum enumeration. When burning an audio CD with CD text where the genre code is not set or is set to an invalid value (For example "abc") the CDText object would perform as if the genre code is set to "0".
Returns
1 Success.
0 There was an error.
See Also
Device
CDText
CDTextType::Enum
CDTextGenreCode::Enum
CDText::GetItem
CDText::SetCodePage
virtual void setLanguage ( CDTextLanguage::Enum  languageId)
pure virtual

Sets the CD-TEXT language.

The default value is Unknown

Parameters
languageIdLanguage identifier
See Also
CDText::language
CDTextLanguage::Enum
virtual bool_t setRawData ( uint8_t *  data,
uint16_t  size 
)
pure virtual

Sets raw CD-TEXT data into the CDText buffer.

Parameters
data[in] Pointer to the buffer which data should be copied into the raw CD-TEXT buffer of CDText object.
size[in] The number of bytes of data to be added to the raw CD-TEXT buffer object.
Returns
1 Success.
0 There was an error.