DRContentObject.h Reference

Declared in
DRContentObject.h

Overview

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

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.

Included Headers

  • <CoreFoundation/CoreFoundation.h>

  • <CoreServices/CoreServices.h>

  • <DiscRecording/DRCoreObject.h>

  • <AvailabilityMacros.h>

Functions

See the Overview section above for header-level documentation.

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

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
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

Data Types

See the Overview section above for header-level documentation.

DRFileRef

The type of a reference to a DRFile object.

typedef struct __DRFile* DRFileRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

DRFilesystemMask

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

typedef UInt32 DRFilesystemMask;
Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

DRFolderRef

The type of a reference to a DRFolder object.

typedef struct __DRFolder* DRFolderRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

DRFSObjectRef

A polymorphic type used for file and folder objects.

typedef DRTypeRef DRFSObjectRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
DRContentObject.h

Constants

See the Overview section above for header-level documentation.

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.

Available in OS X v10.2 and later.

Declared in DRContentObject.h.

kDRFilesystemMaskJoliet

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

Available in OS X v10.2 and later.

Declared in DRContentObject.h.

kDRFilesystemMaskUDF

The mask specifying the UDF file system.

Available in OS X v10.4 and later.

Declared in DRContentObject.h.

kDRFilesystemMaskHFSPlus

The mask specifying the HFS+ file system.

Available in OS X v10.2 and later.

Declared in DRContentObject.h.

kDRFilesystemMaskDefault

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

Available in OS X v10.2 and later.

Declared in DRContentObject.h.