Mac Developer Library

Developer

DRCDTextBlock Class Reference

Options
Deployment Target:

On This Page

DRCDTextBlock

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

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

    Declaration

    - (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.

  • Initializes an empty CD-Text block.

    Declaration

    - (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.

  • Returns a single value from the block.

    Declaration

    - (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.

  • Returns the properties dictionary of the CD-Text block.

    Declaration

    - (NSDictionary*) properties;

    Return Value

    An NSDictionary containing the properties of the block.

  • Changes a single string in the block.

    Declaration

    - (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.

  • Sets the properties dictionary of the CD-Text block.

    Declaration

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

    Parameters

    properties

    NSDictionary of the properties to set.

  • Sets the array of track dictionaries for the block.

    Declaration

    - (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.

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

    Declaration

    - (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.

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

    Declaration

    + (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.

  • Creates a CD-Text block.

    Declaration

    + (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.