Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: User-Space Device Access Disc Recording Framework Reference

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.

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

extern CFStringRef DRFSObjectCopyBaseName( 
    const DRFSObjectRef object) ;  

Parameters

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

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

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

Obtains a property for a file or folder object.

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

Parameters

Return Value

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

Availability

Introduced in Mac OS X v10.2

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

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

Parameters

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

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

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

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

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

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

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

Parameters

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

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

extern CFDictionaryRef DRFSObjectCopySpecificNames( 
    const DRFSObjectRef object) ;  

Parameters

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

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

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

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

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

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

Availability

Introduced in Mac OS X v10.2

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

extern Boolean DRFSObjectIsVirtual( 
    const DRFSObjectRef object) ;  

Parameters

Return Value

Returns TRUE if the object is virtual, FALSE otherwise.

Availability

Introduced in Mac OS X v10.2

Sets the base name for a file or folder object.

extern void DRFSObjectSetBaseName( 
    DRFSObjectRef object, 
    CFStringRef baseName) ;  

Parameters

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

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

Discussion

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

Availability

Introduced in Mac OS X v10.2

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

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

Parameters

Availability

Introduced in Mac OS X v10.2

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

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

Parameters

Availability

Introduced in Mac OS X v10.2

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

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

Parameters

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

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

extern void DRFSObjectSetSpecificNames( 
    DRFSObjectRef object, 
    CFDictionaryRef specificNames) ;  

Parameters

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.

DRFilesystemMask

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

DRFolderRef

The type of a reference to a DRFolder object.

DRFSObjectRef

A polymorphic type used for file and folder objects.

The type of a reference to a DRFile object.

typedef struct __DRFile* DRFileRef;  

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

typedef UInt32 DRFilesystemMask;  

The type of a reference to a DRFolder object.

typedef struct __DRFolder* DRFolderRef;  

A polymorphic type used for file and folder objects.

typedef DRTypeRef DRFSObjectRef;  

Enumerated Types

DRFilesystemMask contants

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

Constants