DRCDTextBlock

Inherits from:
Declared In:

Overview

Defines a CD-Text block, which holds the CD-Text strings for the entire disc in one language.


Methods

+arrayOfCDTextBlocksFromPacks:

Parses raw CD-Text data from a disc into DRCDTextBlock objects.

+cdTextBlockWithLanguage:encoding:

Creates a CD-Text block.

-flatten

Flattens the CD-Text block to determine whether any information will be truncated.

-initWithLanguage:encoding:

Initializes an empty CD-Text block.

-objectForKey:ofTrack:

Returns a single value from the block.

-properties

Returns the properties dictionary of the CD-Text block.

-setObject:forKey:ofTrack:

Changes a single string in the block.

-setProperties:

Sets the properties dictionary of the CD-Text block.

-setTrackDictionaries:

Sets the array of track dictionaries for the block.

-trackDictionaries

Returns a copy of the array of track dictionaries for the block.

arrayOfCDTextBlocksFromPacks:

Parses raw CD-Text data from a disc into DRCDTextBlock objects. 

+ (NSArray*) arrayOfCDTextBlocksFromPacks:(NSData*)packs;
Parameters
packs

NSData containing raw CD-Text PACKs.

Return Value

An autoreleased array of DRCDTextBlock objects describing the information in the raw PACKs, or nil if the data could not be parsed.

Discussion

This method can be used to parse any data blob containing CD-Text PACKs, such as the result of +[DRDevice readCDText], or the data returned by the IOKit ioctl DKIOCCDREADTOC with format=5.

The NSData should be sized to fit the exact number of PACKs. Each PACK occupies 18 bytes, and the 4-byte header from a READ TOC command may optionally be included.

Availability
Introduced in Mac OS X v10.4.

cdTextBlockWithLanguage:encoding:

Creates a CD-Text block. 

+ (DRCDTextBlock*) cdTextBlockWithLanguage:(NSString*)lang 
        encoding:(NSStringEncoding)enc;
Parameters
lang

ISO 639 language code describing the language in which the strings are provided. CD-Text allows the concept of an unknown language, which can be represented here by an empty string.

enc

Character encoding into which the strings should be converted.

Return Value

An autoreleased DRCDTextBlock object.

Availability
Introduced in Mac OS X v10.4.

flatten

Flattens the CD-Text block to determine whether any information will be truncated. 

- (NSUInteger) flatten;
Return Value

The number of bytes that will be truncated from the CD-Text block. If this method returns 0, no truncation will occur.

Discussion

When burning your CD-Text information to a CD, DiscRecording will automatically truncate some of the information you've specified if it does not fit.

The size limit for CD-Text is approximately 3K of strings per block. This limit is only approximate because some of this space is taken up as overhead, and duplicate strings can sometimes be combined. The only way to tell for sure how big your CD-Text block is going to be is to ask DiscRecording to try flattening it. You can use this function to determine whether truncation will be needed.

Some clients will want to accept DiscRecording's truncation since it preserves the most important information and provides the simplest user experience. If you do not wish to use DiscRecording's automatic truncation, it is your responsibility to make sure that you specify a CD-Text block that will fit.

Following is a simple algorithm to avoid having your CD-Text data truncated:

  1. Call -[myCDTextBlock flatten].
  2. If the result is 0, no truncation is necessary. Stop.
  3. Otherwise, truncation will occur -- edit or remove some data.
  4. Repeat.

Availability
Introduced in Mac OS X v10.4.

initWithLanguage:encoding:

Initializes an empty CD-Text block. 

- (id) initWithLanguage:(NSString*)lang encoding:(NSStringEncoding)enc;
Parameters
lang

ISO 639 language code describing the language which this block will hold. CD-Text allows the concept of an unknown language, which can be represented here by an empty string.

enc

Character encoding into which the strings in this block will be converted.

Return Value

A DRCDTextBlock object.

Availability
Introduced in Mac OS X v10.4.

objectForKey:ofTrack:

Returns a single value from the block. 

- (id) objectForKey:(NSString*)key ofTrack:(NSUInteger)trackIndex;
Parameters
key

Key to get the value of.

trackIndex

One-based index of the track to query, or 0 to query the disc.

Return Value

Autoreleased NSObject for the key, or nil if not present.

Availability
Introduced in Mac OS X v10.4.

properties

Returns the properties dictionary of the CD-Text block. 

- (NSDictionary*) properties;
Return Value

An NSDictionary containing the properties of the block.

Availability
Introduced in Mac OS X v10.4.

setObject:forKey:ofTrack:

Changes a single string in the block. 

- (void) setObject:(id)value forKey:(NSString*)key ofTrack:(NSUInteger)trackIndex;
Parameters
value

Value - an NSString, NSData, or NSNumber as appropriate.

key

Key to assign.

trackIndex

One-based index of the track to modify, or 0 to modify the disc.

Availability
Introduced in Mac OS X v10.4.

setProperties:

Sets the properties dictionary of the CD-Text block. 

- (void) setProperties:(NSDictionary*)properties;
Parameters
properties

NSDictionary of the properties to set.

Availability
Introduced in Mac OS X v10.4.

setTrackDictionaries:

Sets the array of track dictionaries for the block. 

- (void) setTrackDictionaries:(NSArray*)tracks;
Parameters
tracks

An NSArray of NSDictionaries of NSStrings, containing the CD-Text information.

Discussion

Each item in the array is a dictionary, which in turn holds key-value encoded information about the track/disc. Array index 0 holds information about the disc, index 1 holds information about track 1, index 2 holds information about track 2, etc.

Any incoming strings are automatically modified to conform to the character set specified in the language block. Calling -trackDictionaries immediately after -setTrackDictionaries: will provide the modified values. These may not be the same as the ones you passed in, but instead correspond to what will actually be used.

Availability
Introduced in Mac OS X v10.4.

trackDictionaries

Returns a copy of the array of track dictionaries for the block. 

- (NSArray*) trackDictionaries;
Return Value

An autoreleased NSArray of CFDictionaries of CFStrings, containing the CD-Text information.

Discussion

Each item in the array is a dictionary, which in turn holds key-value encoded information about the track/disc. Array index 0 holds information about the disc, index 1 holds information about track 1, index 2 holds information about track 2, etc.

Availability
Introduced in Mac OS X v10.4.

 

Last Updated: 2009-08-12