ADC Home > Reference Library > Reference > Audio > Carbon > Disc Recording Framework Reference

DRContentObject.h

Includes:

Overview

Base file system object in Disc Recording content-creation APIs.

Discussion

Content creation provides an interface for dynamic file system creation, allowing complex file-system hierarchies to be created and burned on-the-fly without having to generate a complete on-disk representation.

The DRFSObjectRef opaque type serves as a base for file and folder objects.

Functions

DRFSObjectCopyBaseName: Obtains the default (base) name for the file or folder object.
DRFSObjectCopyFilesystemProperties: Obtains a dictionary of file system properties for a given file or folder object.
DRFSObjectCopyFilesystemProperty: Obtains a property for a file or folder object.
DRFSObjectCopyMangledName: Obtains a file-system-specific name for a file or folder object, modified for uniqueness.
DRFSObjectCopyMangledNames: Obtains a dictionary containing all of the file-system-specific names for a given object, each one modified for uniqueness.
DRFSObjectCopyRealURL: Given a real (as opposed to virtual) file or folder object, obtains a URL reference to the on-disk file or folder.
DRFSObjectCopySpecificName: Obtains a file-system-specific name for a file or folder object.
DRFSObjectCopySpecificNames: Obtains a dictionary containing the file-system-specific names for a file or folder object.
DRFSObjectGetFilesystemMask: Obtains the mask indicating in which file systems a file or folder object should appear.
DRFSObjectGetParent: Obtains a reference to the parent object, if any, of a given object in a file/folder hierarchy.
DRFSObjectGetRealFSRef: Given a real (as opposed to virtual) file or folder object, obtains a file-system reference to the on-disk file or folder.
DRFSObjectIsVirtual: Reports whether a file or folder object is real or virtual.
DRFSObjectSetBaseName: Sets the base name for a file or folder object.
DRFSObjectSetFilesystemMask: Sets the explicit mask for a file or folder object, indicating in which file systems this object should appear.
DRFSObjectSetFilesystemProperties: Changes file-system properties for a file or folder object.
DRFSObjectSetFilesystemProperty: Sets a file-system-specific property for a file or folder object.
DRFSObjectSetSpecificName: Changes a file-system-specific name for a file or folder object.
DRFSObjectSetSpecificNames: Changes all the file-system-specific names for a file or folder object.

DRFSObjectCopyBaseName

Obtains the default (base) name for the file or folder object.

extern CFStringRef DRFSObjectCopyBaseName( 
    const DRFSObjectRef object) ;

Parameters

object: The file or folder object to query.

Return Value

Returns a reference to a copy of the default (base) name.

Discussion

The default (base) name of a file or folder is the name from which Disc Recording automatically generates file-system-specific names.

Disc Recording's content creation API can generate multiple file systems, each of which may require its own naming conventions. To accommodate this need, each file or folder object has a default "base name" which the system alters as necessary to work with the target file system.

Whenever possible, Disc Recording uses the default name unmodified in a generated file system. If the name cannot be used as-is (for example, if it contains illegal characters, exceeds name length limitations, doesn't meet the required format, or a name collision is detected), then the Disc Recording engine automatically generates an acceptable name.

The default name for a real file or folder is the on-disk name of the file or folder.

Availability: Introduced in Mac OS X v10.2

DRFSObjectCopyFilesystemProperties

Obtains a dictionary of file system properties for a given file or folder object.

extern CFDictionaryRef DRFSObjectCopyFilesystemProperties( 
    const DRFSObjectRef object, 
    CFStringRef fsKey, 
    Boolean coalesce) ;

Parameters

object: Object reference to query.
fsKey: The file system to query.
coalesce: If TRUE, this function will also get the "all filesystems" properties dictionary and merge it with the requested file-system dictionary.

Return Value

Returns a reference to a file or folder object's properties dictionary, or NULL if no properties have been set.

Availability: Introduced in Mac OS X v10.2

DRFSObjectCopyFilesystemProperty

Obtains a property for a file or folder object.

extern CFTypeRef DRFSObjectCopyFilesystemProperty( 
    const DRFSObjectRef object, 
    CFStringRef fsKey, 
    CFStringRef propertyKey, 
    Boolean coalesce) ;

Parameters

object: The object reference to query.
fsKey: File system to query.
propertyKey: The property to query.
coalesce: If TRUE and if the property isn't found in the requested file-system dictionary, this function will go on to check the "all filesystems" properties dictionary.

Return Value

Returns a reference to a property, or NULL if not found.

Availability: Introduced in Mac OS X v10.2

DRFSObjectCopyMangledName

Obtains a file-system-specific name for a file or folder object, modified for uniqueness.

extern CFStringRef DRFSObjectCopyMangledName( 
    const DRFSObjectRef object, 
    CFStringRef fsKey) ;

Parameters

object: The object reference to query.
fsKey: The name-access key for the requested file-system-specific name. Valid keys include kDRISO9660LevelOne for '8.3' names or kDRISO9660LevelTwo for 30-character names.

Return Value

Returns a reference to a file-system-specific name, modified as necessary for uniqueness.

Discussion

The file or folder object's name string will be modified for uniqueness considering its siblings. If the burn were to happen immediately after this call, this is the name which would be used on the resulting disc.

When using this function to obtain a modified name, you must specify the fsKey parameter, as listed in DRContentProperties.h, as either kDRISO9660LevelOne for '8.3' names or kDRISO9660LevelTwo for 30-character names. You cannot use the kDRISO9660 constant because it does not distinguish between the level-one and level-two ISO-9660 formats. Use kDRISO9660 only for accessing file and folder object properties with the DRFSObjectCopyFilesystemProperty or DRFSObjectCopyFilesystemProperties functions.

Availability: Introduced in Mac OS X v10.2

DRFSObjectCopyMangledNames

Obtains a dictionary containing all of the file-system-specific names for a given object, each one modified for uniqueness.

extern CFDictionaryRef DRFSObjectCopyMangledNames( 
    const DRFSObjectRef object) ;

Parameters

object: The file or folder object reference to query.

Return Value

Returns a reference to a dictionary of names, each one modified as necessary for uniqueness.

Discussion

The dictionary will return only the names which are indicated by the object's effective mask. If the object's effective mask is zero, an empty dictionary is returned.

Availability: Introduced in Mac OS X v10.2

DRFSObjectCopyRealURL

Given a real (as opposed to virtual) file or folder object, obtains a URL reference to the on-disk file or folder.

extern CFURLRef DRFSObjectCopyRealURL( 
    const DRFSObjectRef object) ;

Parameters

object: The file or folder object to query.

Return Value

Returns a reference to a file URL that specifies the on-disk file or folder, or NULL if the object parameter does not refer to a real file or folder.

Availability: Introduced in Mac OS X v10.2

DRFSObjectCopySpecificName

Obtains a file-system-specific name for a file or folder object.

extern CFStringRef DRFSObjectCopySpecificName( 
    const DRFSObjectRef object, 
    CFStringRef fsKey) ;

Parameters

object: The file or folder object to query.
fsKey: The name-access key for the requested file-system-specific name. Valid keys include kDRISO9660LevelOne for '8.3' names or kDRISO9660LevelTwo for 30-character names.

Return Value

Returns a reference to a file-system-specific name.

Discussion

When using this function to generate a file-system-specific name, you must specify the fsKey parameter, as listed in DRContentProperties.h, as either kDRISO9660LevelOne for '8.3' names or kDRISO9660LevelTwo for 30-character names. You cannot use the kDRISO9660 constant because it does not distinguish between the level-one and level-two ISO-9660 formats. Use kDRISO9660 only for accessing file and folder object properties with the DRFSObjectCopyFilesystemProperty or DRFSObjectCopyFilesystemProperties functions.

Availability: Introduced in Mac OS X v10.2

DRFSObjectCopySpecificNames

Obtains a dictionary containing the file-system-specific names for a file or folder object.

extern CFDictionaryRef DRFSObjectCopySpecificNames( 
    const DRFSObjectRef object) ;

Parameters

object: The object reference to query.

Return Value

Returns a dictionary of file-system-specific names. If the object's effective mask is zero, an empty dictionary is returned.

Discussion

The dictionary obtained by this function will include only the names which are to be used in a burn according to the object's effective mask.

Availability: Introduced in Mac OS X v10.2

DRFSObjectGetFilesystemMask

Obtains the mask indicating in which file systems a file or folder object should appear.

extern DRFilesystemMask DRFSObjectGetFilesystemMask( 
    const DRFSObjectRef object, 
    DRFilesystemMask *explicitMask, 
    DRFilesystemMask *effectiveMask) ;

Parameters

object: The file or folder object to query.
explicitMask: On output, contains the object's explicit mask. May be NULL on input.
effectiveMask: On output, contains the object's effective mask. May be NULL on input.

Return Value

For convenience, the file or folder object's effective mask is returned.

Discussion

If you want all the file systems on a target disc -- such as HFS+ and ISO-9660 -- to have the same data, you do not have to set an explicit mask for anything but the root folder. And since Disc Recording automatically assigns a reasonable default mask to the root if none is provided, in most cases you do not even have to set an explicit root-folder mask.

With Disc Recording's file masking system you can specify which items in a source file structure will appear in various generated file structures when burning to disc. For example, you may want a Mac OS application file or bundle to appear only in an HFS+ tree, and may want a .EXE file to appear only in a Joliet tree.

File-system-specific suppression is handled through the file or folder object's file-system mask, a bit field in which a 1 indicates the object will appear in the corresponding file system, and 0 indicates it will not appear. Masks can define arbitrarily complex trees. In the extreme case, each file system can have its own unique, disjoint tree. Such discs, however, may be confusing to the user.

A file or folder object can be considered to have two mask values. The first is the explicit mask, set by the client unless it is simply the default value of kDRFilesystemMaskDefault , with all bits set to 1. The other is the effective mask, which is a derived mask used during a burn.

The Disc Recording engine implements the following rules prior to a burn to derive the effective mask:

A file or folder object's effective mask is equal to the bitwise AND of the object's explicit mask and its parent's effective mask.

An effective mask of 0 removes an object from all file systems. It will not be included in the burn.

For example, an explicit mask of 0 forces an effective mask of 0, and an explicit mask of kDRFilesystemMaskDefault implies an effective mask equal to the parent's effective mask.

For an object to appear in a file system, its parent folder, and all ancestors, up to the root, must also be in the file system.

When the burn is performed, Disc Recording performs a few additional steps in determining the file and folder layouts for each file system.

If your client gives the root folder has an explicit mask of kDRFilesystemMaskDefault , Disc Recording will assign to the root folder a default explicit mask of its own choosing in an attempt to produce the most cross-platform-compatible disc.

This automatically-selected default root mask depends, among other factors, on the type of media to be burned -- CD or DVD.

If you need to generate layouts for specific file systems, you should always set a non-default explicit mask for the root folder.

Assigning the root folder a mask of 0 results in undefined behavior.

If your client gives every file and folder object in your source layout an explicit mask of kDRFilesystemMaskDefault , then every object will inherit the mask that Disc Recording chooses for the root folder.

If you set the root folder's mask to a file system that is dependent on another file system not in the mask, Disc Recording resolves the conflict by enabling the required file system.

For example, the Joliet file system requires ISO-9660. If the root folder's mask is kDRFilesystemMaskJoliet only, Disc Recording will automatically enable kDRFilesystemMaskISO9660 as well.

If the root folder's mask requests a file system that cannot coexist with another requested file system, Disc Recording resolves the conflict by disabling one of the conflicting file systems. This is not currently an issue, since no pairs of file systems that can be currently generated are mutually exclusive.

(To provide a hypothetical example of this behavior: If Disc Recording supported both HFS and HFS+ in a mutually exclusive manner, and the root folder had a mask that enabled both, the burn engine would automatically disable HFS in favor of HFS+.)

Availability: Introduced in Mac OS X v10.2

DRFSObjectGetParent

Obtains a reference to the parent object, if any, of a given object in a file/folder hierarchy.

extern DRFolderRef DRFSObjectGetParent( 
    const DRFSObjectRef object) ;

Parameters

object: The object reference to query.

Return Value

Returns a reference to the object's parent, or NULL if there is no parent.

Availability: Introduced in Mac OS X v10.2

DRFSObjectGetRealFSRef

Given a real (as opposed to virtual) file or folder object, obtains a file-system reference to the on-disk file or folder.

extern void DRFSObjectGetRealFSRef( 
    const DRFSObjectRef object, 
    FSRef *fsRef) ;

Parameters

object: The file or folder object to query.
fsRef: On success, contains a valid FSRef object.

Availability: Introduced in Mac OS X v10.2

DRFSObjectIsVirtual

Reports whether a file or folder object is real or virtual.

extern Boolean DRFSObjectIsVirtual( 
    const DRFSObjectRef object) ;

Parameters

object: The file or folder object to query.

Return Value

Returns TRUE if the object is virtual, FALSE otherwise.

Availability: Introduced in Mac OS X v10.2

DRFSObjectSetBaseName

Sets the base name for a file or folder object.

extern void DRFSObjectSetBaseName( 
    DRFSObjectRef object, 
    CFStringRef baseName) ;

Parameters

object: A reference to the file or folder object to modify.
baseName: A reference to the new name for the object.

Discussion

The default (base) name of a file or folder is the name from which Disc Recording automatically generates file-system-specific names.

Disc Recording's content creation API can generate multiple file systems, each of which may have its own naming conventions. Whenever possible, the base name will be used without modification in a generated file system.

If the base name cannot be used as-is (if, for example, it contains illegal characters, exceeds the length requirements, doesn't meet the required format, or a name collision is detected), then Disc Recording automatically derives an acceptable name that meets the file system's criteria.

Changing a file or folder object's base name will remove any file-system-specific name overrides that may have been set in the object's names dictionary.

Availability: Introduced in Mac OS X v10.2

DRFSObjectSetFilesystemMask

Sets the explicit mask for a file or folder object, indicating in which file systems this object should appear.

extern void DRFSObjectSetFilesystemMask( 
    DRFSObjectRef object, 
    DRFilesystemMask newMask) ;

Parameters

object: A reference to the file or folder object to modify.
newMask: The new explicit mask to use.

Discussion

Refer to the discussion for DRFSObjectGetFilesystemMask for an explanation of explicit and effective masks.

Availability: Introduced in Mac OS X v10.2

DRFSObjectSetFilesystemProperties

Changes file-system properties for a file or folder object.

extern void DRFSObjectSetFilesystemProperties( 
    DRFSObjectRef object, 
    CFStringRef fsKey, 
    CFDictionaryRef properties) ;

Parameters

object: A reference to the file or folder object to modify.
fsKey: The file-system for the object properties you want to modify.
properties: A reference to the dictionary of properties to set.

Availability: Introduced in Mac OS X v10.2

DRFSObjectSetFilesystemProperty

Sets a file-system-specific property for a file or folder object.

extern void DRFSObjectSetFilesystemProperty( 
    DRFSObjectRef object, 
    CFStringRef fsKey, 
    CFStringRef propertyKey, 
    CFTypeRef value) ;

Parameters

object: A reference to the file or folder object to modify.
fsKey: The file-system for the object property you want to modify.
propertyKey: The property you want to modify.
value: The new value for the property.

Availability: Introduced in Mac OS X v10.2

DRFSObjectSetSpecificName

Changes a file-system-specific name for a file or folder object.

extern void DRFSObjectSetSpecificName( 
    DRFSObjectRef object, 
    CFStringRef fsKey, 
    CFStringRef specificName) ;

Parameters

object: A reference to the file or folder object to modify.
fsKey: The name-access key for the file-system-specific name you are changing. Valid keys include kDRISO9660LevelOne for '8.3' names or kDRISO9660LevelTwo for 30-character names.
specificName: The name to apply to the file or folder object.

Discussion

Disc Recording attempts to use the default (base) name of a file or folder object. If the default name is illegal, however, Disc Recording modifies it to fit the rules for the file system specified with the fsKey parameter.

To ensure that you are always displaying the most current name to the user, always follow a call to this function with a call to DRFSObjectCopySpecificName .

Availability: Introduced in Mac OS X v10.2

DRFSObjectSetSpecificNames

Changes all the file-system-specific names for a file or folder object.

extern void DRFSObjectSetSpecificNames( 
    DRFSObjectRef object, 
    CFDictionaryRef specificNames) ;

Parameters

object: A reference to the file or folder object to modify.
specificNames: The dictionary containing the names to apply to the file or folder object.

Discussion

Disc Recording attempts to use the default (base) names of a file or folder object. If any of the default names are illegal, however, Disc Recording modifies them to fit the rules for the file system specified with the fsKey parameter.

To ensure that you are always displaying the most current name to the user, always follow a call to this function with a call to DRFSObjectCopySpecificNames .

Availability: Introduced in Mac OS X v10.2

Typedefs

DRFileRef

The type of a reference to a DRFile object.

typedef struct __DRFile* DRFileRef;

DRFilesystemMask

A mask of values indicating in which filesystems a particular filesystem object should be included.

typedef UInt32 DRFilesystemMask;

DRFolderRef

The type of a reference to a DRFolder object.

typedef struct __DRFolder* DRFolderRef;

DRFSObjectRef

A polymorphic type used for file and folder objects.

typedef DRTypeRef DRFSObjectRef;

Enumerations

DRFilesystemMask contants

enum { 
    kDRFilesystemMaskISO9660 = (
        1<<0), 
    kDRFilesystemMaskJoliet = (
        1<<1), 
    kDRFilesystemMaskUDF = (
        1<<2), 
    kDRFilesystemMaskHFSPlus = (
        1<<3), 
    kDRFilesystemMaskDefault = 0xFFFFFFFF 
};

Constants

kDRFilesystemMaskISO9660
The mask specifying the ISO-9660 file system.

kDRFilesystemMaskJoliet
The mask specifying the Joliet file system, an extension to the ISO-9660 file system.

kDRFilesystemMaskUDF
The mask specifying the UDF file system.

kDRFilesystemMaskHFSPlus
The mask specifying the HFS+ file system.

kDRFilesystemMaskDefault
The default, unrestricted mask for newly-created file or folder objects.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-04-01