Mac Developer Library

Developer

DRContentObject.h Reference

Options
Deployment Target:

On This Page
Language:

DRContentObject.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import DiscRecording

Objective-C

@import DiscRecording;

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

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

    Declaration

    Swift

    func DRFSObjectCopyBaseName(_ object: DRFSObject!) -> Unmanaged<CFString>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectCopyFilesystemProperties(_ object: DRFSObject!, _ fsKey: CFString!, _ coalesce: Boolean) -> Unmanaged<CFDictionary>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Obtains a property for a file or folder object.

    Declaration

    Swift

    func DRFSObjectCopyFilesystemProperty(_ object: DRFSObject!, _ fsKey: CFString!, _ propertyKey: CFString!, _ coalesce: Boolean) -> Unmanaged<AnyObject>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectCopyMangledName(_ object: DRFSObject!, _ fsKey: CFString!) -> Unmanaged<CFString>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectCopyMangledNames(_ object: DRFSObject!) -> Unmanaged<CFDictionary>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectCopyRealURL(_ object: DRFSObject!) -> Unmanaged<CFURL>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectCopySpecificName(_ object: DRFSObject!, _ fsKey: CFString!) -> Unmanaged<CFString>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectCopySpecificNames(_ object: DRFSObject!) -> Unmanaged<CFDictionary>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectGetFilesystemMask(_ object: DRFSObject!, _ explicitMask: UnsafeMutablePointer<DRFilesystemMask>, _ effectiveMask: UnsafeMutablePointer<DRFilesystemMask>) -> DRFilesystemMask

    Objective-C

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

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectGetParent(_ object: DRFSObject!) -> Unmanaged<DRFolder>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectGetRealFSRef(_ object: DRFSObject!, _ fsRef: UnsafeMutablePointer<FSRef>)

    Objective-C

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

    Parameters

    object

    The file or folder object to query.

    fsRef

    On success, contains a valid FSRef object.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectIsVirtual(_ object: DRFSObject!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • Sets the base name for a file or folder object.

    Declaration

    Swift

    func DRFSObjectSetBaseName(_ object: DRFSObject!, _ baseName: CFString!)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectSetFilesystemMask(_ object: DRFSObject!, _ newMask: DRFilesystemMask)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectSetFilesystemProperties(_ object: DRFSObject!, _ fsKey: CFString!, _ properties: CFDictionary!)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectSetFilesystemProperty(_ object: DRFSObject!, _ fsKey: CFString!, _ propertyKey: CFString!, _ value: AnyObject!)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectSetSpecificName(_ object: DRFSObject!, _ fsKey: CFString!, _ specificName: CFString!)

    Objective-C

    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 .

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func DRFSObjectSetSpecificNames(_ object: DRFSObject!, _ specificNames: CFDictionary!)

    Objective-C

    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 .

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

Data Types

See the Overview section above for header-level documentation.

  • The type of a reference to a DRFile object.

    Declaration

    Swift

    typealias DRFileRef = DRFile

    Objective-C

    typedef struct __DRFile* DRFileRef;

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    typealias DRFilesystemMask = UInt32

    Objective-C

    typedef UInt32 DRFilesystemMask;

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • The type of a reference to a DRFolder object.

    Declaration

    Swift

    typealias DRFolderRef = DRFolder

    Objective-C

    typedef struct __DRFolder* DRFolderRef;

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

  • A polymorphic type used for file and folder objects.

    Declaration

    Swift

    typealias DRFSObjectRef = DRFSObject

    Objective-C

    typedef DRTypeRef DRFSObjectRef;

    Import Statement

    Objective-C

    @import DiscRecording;

    Swift

    import DiscRecording

    Availability

    Available in OS X v10.2 and later.

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Swift

    var kDRFilesystemMaskISO9660: UInt32 { get } var kDRFilesystemMaskJoliet: UInt32 { get } var kDRFilesystemMaskUDF: UInt32 { get } var kDRFilesystemMaskHFSPlus: UInt32 { get } var kDRFilesystemMaskDefault: UInt32 { get }

    Objective-C

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

    Constants

    • kDRFilesystemMaskISO9660

      kDRFilesystemMaskISO9660

      The mask specifying the ISO-9660 file system.

      Available in OS X v10.2 and later.

    • kDRFilesystemMaskJoliet

      kDRFilesystemMaskJoliet

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

      Available in OS X v10.2 and later.

    • kDRFilesystemMaskUDF

      kDRFilesystemMaskUDF

      The mask specifying the UDF file system.

      Available in OS X v10.4 and later.

    • kDRFilesystemMaskHFSPlus

      kDRFilesystemMaskHFSPlus

      The mask specifying the HFS+ file system.

      Available in OS X v10.2 and later.

    • kDRFilesystemMaskDefault

      kDRFilesystemMaskDefault

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

      Available in OS X v10.2 and later.