Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

< Previous Page Hide TOC

QuickTime 6.4 API Reference

In this section:

Functions
Callbacks
Data Structures
VDIIDC Call Selectors


Functions

The functions new to the QuickTime 6.4 API are documented alphabetically in this section.

AttachMovieToCurrentThread

Attaches a movie to the current thread.

OSErr AttachMovieToCurrentThread (Movie m);

Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

AttachTimeBaseToCurrentThread

Attaches a time base to the current thread.

OSErr AttachTimeBaseToCurrentThread (TimeBase tb);

Parameters
tb

A time base.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

ClockGetRateChangeConstraints

Obtains minimum and maximum delays that a clock could introduce during a rate change.

ComponentResult ClockGetRateChangeConstraints (
   ComponentInstance    aClock,
   TimeRecord           *minimum,
   TimeRecord           *maximum );

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from OpenComponent.

minimum

A pointer to a TimeRecord structure that the clock will update with the minimum delay introduced during a rate change. You can pass NIL if you do not want to receive this information.

maximum

A pointer to a TimeRecord structure that the clock will update with the maximum delay introduced during a rate change. You can pass NIL if you do not want to receive this information.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error. Returns badComponentSelector if the component does not support the call.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
QuickTimeComponents.h

ClockGetTimeForRateChange

Obtains the current rate change time according to a specific clock, a preferred time, and a safe increment duration.

ComponentResult ClockGetTimesForRateChange (
   ComponentInstance    aClock,
   Fixed                fromRate,
   Fixed                toRate,
   TimeRecord           *currentTime,
   TimeRecord           *preferredTime,
   TimeRecord           *safeIncrementForPreferredTime );

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from OpenComponent.

fromRate

The clock rate you are starting from.

toRate

The clock rate you are going to.

currentTime

A pointer to a TimeRecord structure that the clock will update with the current rate change time. You can pass NIL if you do not want to receive this information.

preferredTime

A pointer to a TimeRecord structure that the clock will update with the next clock time at which the clock would prefer dependent time bases to perform the rate change. You can pass NIL if you do not want to receive this information.

safeIncrementForPreferredTime

A pointer to a TimeRecord structure that the clock will update with the increment between preferred times for the rate change. If this increment is nonzero, multiples of it may be added to the preferredTime value to calculate future preferred times. You can pass NIL if you do not want to receive this information.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

The preferredTime parameter indicates a better choice than the current time to have a rate transition fromRate to toRate. But the clock cannot expect the interesting time to be the one used when the rate changes. The safeIncrementForPreferredTime indicates that the preferred time can be incremented by this value (and any multiple of it) and still be safe to use.

Version Notes

Introduced in QuickTime 6.4.

Availability

ConvertDataRefToMovieDataRef

Converts a piece of data in a storage location to a movie file format and stores it in another storage location, supporting a user settings dialog box for import operations.

OSErr ConvertDataRefToMovieDataRef (
   Handle               inputDataRef,
   OSType               inputDataRefType,
   Handle               outputDataRef,
   OSType               outputDataRefType,
   OSType               creator,
   long                 flags,
   ComponentInstance    userComp,
   MovieProgressUPP     proc,
   long                 refCon );

Parameters
inputDataRef

A data reference that specifies the storage location of the source data.

inputDataRefType

The type of the input data reference.

outputDataRef

A data reference that specified the storage location to receive the converted data.

outputDataRefType

The type of the output data reference.

creator

The creator type of the output storage location.

flags

Flags that control the operation of the dialog box.

createMovieFileDeleteCurFile

Indicates whether to delete an existing file. If you set this flag to 1, the Movie Toolbox deletes the file (if it exists) before converting the new movie file. If you set this flag to 0 and the file specified by the inputDataRef and outputDataRef parameters already exists, the Movie Toolbox uses the existing file. In this case, the toolbox ensures that the file has both data.

movieToFileOnlyExport

If this bit is set and the showUserSettingsDialog bit is set, the Save As dialog box restricts the user to those file formats that are supported by movie data export components.

movieFileSpecValid

If this bit is set and the showUserSettingsDialog bit is set, the name of the outputDataRef parameter is used as the default name of the exported file in the Save As dialog box.

showUserSettingsDialog

Controls whether the user settings dialog box for the specified import operation can appear. Set this flag to 1 to display the user settings dialog box.

userComp

An instance of a component to be used for converting the movie data.

proc

A progress callback function; see MovieProgressProc in the QuickTime API Reference.

refCon

A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your function needs.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

This function converts a piece of data in a storage location into a movie and stores into another storage location. Both the input and the output storage locations are specified through data references. If the storage location is on a local file system, the file will have the specified creator. If specified as such in the flags, the function displays a dialog box that lets the user to choose the output file and the export type. If an export component (or its instance) is specified in userComp, it will be used for the conversion operation.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

ConvertMovieToDataRef

Converts a specified movie (or a single track within a movie) into a specified file format and stores it in a specified storage location.

OSErr ConvertMovieToDataRef (
   Movie                theMovie,
   Track                onlyTrack,
   Handle               dataRef,
   OSType               dataRefType,
   OSType               fileType,
   OSType               creator,
   long                 flags,
   ComponentInstance    userComp );

Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

onlyTrack

The track in the source movie, if you want to convert only a single track.

dataRef

A data reference that specifies the storage location to receive the converted movie data.

dataRefType

The type of data reference. This function currently supports only alias data references.

fileType

The Mac OS file type of the storage location, which determines the export format.

creator

The creator type of the storage location.

flags

Flags (see below)that control the operation of the dialog box.

showUserSettingsDialog

If this bit is set, the Save As dialog box will be displayed to allow the user to choose the type of file to export to, as well as the file name to export to.

movieToFileOnlyExport

If this bit is set and the showUserSettingsDialog bit is set, the Save As dialog box restricts the user to those file formats that are supported by movie data export components.

movieFileSpecValid

If this bit is set and the showUserSettingsDialog bit is set, the name field of the dataRef parameter is used as the default name of the exported file in the Save As dialog box.

userComp

An instance of the component to be used for converting the movie data.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

If the storage location is on a local file system, the file will have the specified file type and the creator. If specified as such in the flags, the function displays a dialog box that lets the user choose the output file and the export type. If an export component (or its instance) is specified in the userComp parameter, it will be used to perform the conversion operation.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

ConvertTimeToClockTime

Converts a time record in a time base to clock time.

void ConvertTimeToClockTime ( TimeRecord *time );

Parameters
time

The TimeRecord structure to be converted. It must contain a valid time base; otherwise it remains untouched.

Discussion

The result of this call has no meaning it the time base rate is 0.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

DetachMovieFromCurrentThread

Detaches a movie from the current thread.

OSErr DetachMovieFromCurrentThread (Movie m);

Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

DetachTimeBaseFromCurrentThread

Detaches a time base from the current thread.

OSErr DetachTimeBaseFromCurrentThread (TimeBase tb);

Parameters
tb

A time base.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

EnterMoviesOnThread

Indicates that the client will be using QuickTime on the current thread.

OSErr EnterMoviesOnThread (UInt32 inFlags);

Parameters
inFlags

Flags indicating how the executing thread will be using QuickTime. Setting the thread mode is a convenience provided by this function. Pass 0 for the default options.

kQTEnterMoviesFlagDontSetComponentsThreadMode

Public state. Value is 1L << 0. By default, this function sets the current Component Manager thread mode according to kCSAcceptThreadSafeComponentsOnlyMode. By setting the kQTEnterMoviesFlagDontSetComponentThreadMode flag, no change to the thread mode will be made, leaving it as it was before the call to this function.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error. This function returns an appropriate operating system or QuickTime error if the operation couldn't be completed. This might occur because a second call on the thread was made that used incompatible flags (for example, the first call required a shared state but a subsequent call required a private state).

Discussion

This function is analogous to EnterMovies. It initializes QuickTime and prepares QuickTime for calls from its thread. Unlike EnterMovies, this function allows the client to indicate if its access to QuickTime requires sharing of QuickTime state with the main thread. The default is to maintain a private state.

Your application should call this function on threads you create. Calling it on the main thread should be done if QuickTime will be used from the main thread.

If a client doesn't call this function on a spawned preemptive thread and then makes a QuickTime call (including EnterMovies), the global QuickTime state will be shared with the main (or application) thread. This behavior ensures compatibility with current applications accessing QuickTime from multiple threads.

The first call to this function will change the components thread mode unless the kQTEnterMoviesFlagDontSetComponentsThreadMode flag is passed. All subsequent calls will leave the components thread mode unaffected.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

ExitMoviesOnThread

Indicates to QuickTime that the client will no longer be using QuickTime on the current thread.

OSErr ExitMoviesOnThread (void);

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error. Returns an appropriate operating system or QuickTime error if the operation couldn't be completed. This might occur because a previous call to EnterMoviesOnThread was not made.

Discussion

This function should be called before exiting from a spawned thread that uses QuickTime. It undoes the setup performed by EnterMoviesOnThread. Each call to EnterMoviesOnThread should be matched with a call to this function. This function should not be called on a thread without a previous call to EnterMoviesOnThread.

After the last call to this function is made on a thread, subsequent calls to QuickTime functions without calling EnterMoviesOnThread first will result in threads sharing the main thread’s state just as though the application didn’t use EnterMoviesOnThread or this function. This behavior ensures compatibility. Thus callers should bracket all QuickTime calls on secondary threads between an initial call to EnterMoviesOnThread and final call to this function.

If you do not call this function, certain cleanup may not occur, potentially causing resource leaks.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

GetMovieRateChangeConstraints

Returns the minimum and maximum delay you can get when a movie’s rate is changed.

void GetMovieRateChangeConstraints (
   Movie         theMovie,
   TimeRecord    *minimumDelay,
   TimeRecord    *maximumDelay );

Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

minimumDelay

A pointer to a TimeRecord structure. The function updates this structure to contain the minimum delay when a rate change happens.

maximumDelay

A pointer to a TimeRecord structure. The function updates this structure to contain the maximum delay when a rate change happens.

Discussion

If the time base master clock of the movie is changed, this function must be called again to reflect the current constraints.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

GetMovieThreadAttachState

Determines whether a given movie is attached to a thread.

OSErr GetMovieThreadAttachState (
   Movie      m,
   Boolean    *outAttachedToCurrentThread,
   Boolean    *outAttachedToAnyThread );

Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

outAttachedToCurrentThread

A pointer to a Boolean that on exit is TRUE if the movie is attached to the current thread, FALSE otherwise.

outAttachedToAnyThread

A pointer to a Boolean that on exit is TRUE if the movie is attached to any thread, FALSE otherwise.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

GetTimeBaseMasterOffsetTimeBase

Allows an offset time base to retrieve the master time base it is attached to.

TimeBase GetTimeBaseMasterOffsetTimeBase ( TimeBase
tb );

Parameters
tb

An offset time base.

Return Value

The master time base for the offset time base passed in tb. Returns NIL if tb does not contain an offset time base.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

GetTimeBaseRateChangeStatus

Lets a time base client determine the time base’s last rate change status.

void GetTimeBaseRateChangeStatus (
   TimeBase          tb,
   TimeScale         scale,
   Fixed             *rateChangedTo,
   TimeBaseStatus    *flags,
   TimeRecord        *rateChangeTimeBaseTime,
   TimeRecord        *rateChangeClockTime,
   TimeRecord        *currentClockTime );

Parameters
tb

A pointer to a TimeBaseRecord structure.

scale

The scale to use for the returned time values. Pass 0 to retrieve the time in the preferred time scale of the time base.

rateChangedTo

The rate value changed to. Clients may pass NIL if they do not want to receive this information.

flags

A pointer to a flag that will be returned when the clock is waiting for a future time to start moving while its rate is nonzero. When set, the unpinned time will return a negative value telling how far you are from the real start time. Clients may pass NIL if they do not want to receive this information.

rateChangeTimeBaseTime

The time base time when the rate changed. Clients may pass NIL if they do not want to receive this information.

rateChangeClockTime

The clock time when the rate changed. Clients may pass NIL if they do not want to receive this information.

currentClockTime

The current clock time value. Clients may pass NIL if they do not want to receive this information.

timeBaseRateChanging

The clock is waiting for a future time to start moving while its rate is nonzero. When set, the unpinned time will return a negative value telling how far you are from the real start time.

rateChangeTimeBaseTime

The time base time when the rate changed. Clients may pass NIL if they do not want to receive this information.

rateChangeClockTime

The clock time when the rate changed. Clients may pass NIL if they do not want to receive this information.

currentClockTime

The current clock time value. Clients may pass NIL if they do not want to receive this information.

Discussion

When the flag timeBaseRateChanging is returned, the amount of time left before the time base ticks is equal to (rateChangeClockTime - currentClockTime).

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

GetTimeBaseThreadAttachState

Determines whether a given time base is attached to a thread.

OSErr GetTimeBaseThreadAttachState (
   TimeBase    inTimeBase,
   Boolean     *outAttachedToCurrentThread,
   Boolean     *outAttachedToAnyThread );

Parameters
inTimeBase

A time base.

outAttachedToCurrentThread

A pointer to a Boolean that on exit is TRUE if the time base is attached to the current thread, FALSE otherwise.

outAttachedToAnyThread

A pointer to a Boolean that on exit is TRUE if the time base is attached to any thread, FALSE otherwise.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

GraphicsExportGetInputCGBitmapContext

Retrieves the CGBitmapContext that the graphics exporter is using as its input image.

ComponentResult GraphicsExportGetInputCGBitmapContext
(
   GraphicsExportComponent    ci,
   CGContextRef               *bitmapContextRef );

Parameters
ci

The component instance that identifies your connection to the graphics exporter component.

bitmapContextRef

A reference to the Core Graphics context.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsExportGetInputCGImage

Determines which Core Graphics CGImage is the source for a graphics export operation.

ComponentResult GraphicsExportGetInputCGImage (
   GraphicsExportComponent    ci,
   CGImageRef                 *imageRef );

Parameters
ci

The component instance that identifies your connection to the graphics exporter component.

imageRef

A reference to a Core Graphics image.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsExportSetInputCGBitmapContext

Sets the CGBitmapContext that the graphics exporter will use as its input image.

ComponentResult GraphicsExportSetInputCGBitmapContext
(
   GraphicsExportComponent    ci,
   CGContextRef               bitmapContextRef );

Parameters
ci

The component instance that identifies your connection to the graphics exporter component.

bitmapContextRef

A reference to the Core Graphics context.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsExportSetInputCGImage

Specifies a Core Graphics CGImage as the source for a graphics export operation.

ComponentResult GraphicsExportSetInputCGImage(
   GraphicsExportComponent    ci,
   CGImageRef                 imageRef );

Parameters
ci

The component instance that identifies your connection to the graphics exporter component.

imageRef

A reference to a CG image.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportCreateCGImage

Imports an image as a Core Graphics CGImage.

ComponentResult GraphicsImportCreateCGImage (
   GraphicsImportComponent    ci,
   CGImageRef                 *imageRefOut,
   UInt32                     flags );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

imageRefOut

A reference to the CG image to be created.

flags

A flag that determines the settings to use.

kGraphicsImportCreateCGImageUsingCurrentSettings

Use the current settings.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportDoExportImageFileToDataRefDialog

Presents a dialog box that lets the user save an imported image in a foreign file format.

ComponentResult GraphicsImportDoExportImageFileToDataRefDialog
(
   GraphicsImportComponent    ci,
   Handle                     inDefaultDataRef,
   OSType                     inDefaultDataRefType,
   CFStringRef                prompt,
   ModalFilterYDUPP           filterProc,
   OSType                     *outExportedType,
   Handle                     *outExportedDataRef,
   OSType                     *outExportedDataRefType );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

inDefaultDataRef

A data reference that specifies the default export location.

inDefaultDataRefType

The type of the data reference that specifies the default export location.

prompt

A reference to a CFString that contains the prompt text string for the dialog.

filterProc

A modal filter function; see ModalFilterYDProc in the QuickTime API Reference.

outExportedType

A pointer to an OSType entity where the type of the exported file will be returned.

outExportedDataRef

A pointer to an handle where the data reference to the exported file will be returned.

outExportedDataRefType

A pointer to an OSType entity where the type of the data reference that points to the exported file will be returned.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

This function presents a file dialog that lets the user to specify a file to which the exported data goes and a format into which image data is exported. By using data references, a long file name or Unicode file name can be used as a default file name as well as the name of the file into which the export data goes. This function is equivalent to GraphicsImportDoExportImageFileDialog.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportExportImageFileToDataRef

Saves an imported image in a foreign file format.

ComponentResult GraphicsImportExportImageFileToDataRef
(
   GraphicsImportComponent    ci,
   OSType                     fileType,
   OSType                     fileCreator,
   Handle                     dataRef,
   OSType                     dataRefType );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

fileType

The Mac OS file type for the new file, which determines the file format.

fileCreator

The creator type of the new file.

dataRef

A data reference that specifies a storage location to which the image is to be exported.

dataRefType

The type of the data reference.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

This function exports the imported image as a foreign file format specified by fileType. The exported data will be saved into a storage location specified by a data reference. You can use data reference functions to create a data reference for a file that has long or Unicode file name. This function is equivalent to GraphicsImportExportImageFile.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportGetDestinationColorSyncProfileRef

Retrieves a ColorSync profile from a graphics importer component.

GraphicsImportGetDestinationColorSyncProfileRef (
   GraphicsImportComponent   ci,
   CMProfileRef              *destinationProfileRef);

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

destinationProfileRef

On return, a pointer to an opaque struct containing a ColorSync profile.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportGetGenericColorSyncProfile

Retrieves the generic colorsync profile for a graphics importer component.

GraphicsImportGetGenericColorSyncProfile (
   GraphicsImportComponent    ci,
   OSType                     pixelFormat,
   void                       *reservedSetToNULL,
   UInt32                     flags,
   Handle                     *genericColorSyncProfileOut );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

pixelFormat

See “Pixel Formats” in the QuickTime API Reference.

reservedSetToNULL

Pass NIL.

flags

Currently not used.

genericColorSyncProfileOut

A handle to the the generic colorsync profile for the graphics importer.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportGetOverrideSourceColorSyncProfileRef

Retrieves the override ColorSync profile for a graphics importer component.

ComponentResult GraphicsImportGetOverrideSourceColorSyncProfileRef
(
   GraphicsImportComponent   ci,
   CMProfileRef              *outOverrideSourceProfileRef );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

outOverrideSourceProfileRef

A pointer to an opaque struct containing a ColorSync profile.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportSaveAsPictureToDataRef

Creates a storage location that contains a QuickDraw picture for an imported image.

ComponentResult GraphicsImportSaveAsPictureToDataRef
(
   GraphicsImportComponent    ci,
   Handle                     dataRef,
   OSType                     dataRefType );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

dataRef

A data reference that specifies a storage location to which the picture is to be saved.

dataRefType

The type of the data reference.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

This function saves the imported image as a QuickDraw picture into a storage location specified through a data reference. You can use Data Reference Utilities to create a data reference for a file that has long or Unicode file name. This function is equivalent to GraphicsImporterSaveAsPictureFile.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportSaveAsQuickTimeImageFileToDataRef

Creates a storage location that contains a QuickTime image of an imported image.

ComponentResult GraphicsImportSaveAsQuickTimeImageFileToDataRef
(
   GraphicsImportComponent    ci,
   Handle                     dataRef,
   OSType                     dataRefType );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

dataRef

A data reference that specifies a storage location to which the picture is to be saved.

dataRefType

The type of the data reference.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

This function saves the imported image as a QuickTime image into a storage location specified through a data reference. You can use data reference functions to create a data reference for a file that has long or Unicode file name. This function is equivalent to GraphicsImportSaveAsQuickTimeImageFile.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportSetDestinationColorSyncProfileRef

Sets the ColorSync profile for a graphics importer component.

ComponentResult GraphicsImportSetDestinationColorSyncProfileRef
(
   GraphicsImportComponent   ci,
   CMProfileRef              newDestinationProfileRef);

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

newDestinationProfileRef

A pointer to an opaque struct containing a ColorSync profile.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportSetOverrideSourceColorSyncProfileRef

Sets the override ColorSync profile for a graphics importer component.

ComponentResult GraphicsImportSetOverrideSourceColorSyncProfileRef
(
   GraphicsImportComponent   ci,
   CMProfileRef              newOverrideSourceProfileRef);

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

newOverrideSourceProfileRef

A pointer to an opaque struct containing a ColorSync profile.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

GraphicsImportWillUseColorMatching

Asks whether GraphicsImportDraw will use color matching if called with the current importer settings.

ComponentResult GraphicsImportWillUseColorMatching
(
   GraphicsImportComponent   ci,
   Boolean                   *outWillMatch );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

outWillMatch

On return, a pointer to a Boolean set to TRUE if the graphics importer will use color matching, FALSE otherwise.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

MovieImportDoUserDialogDataRef

Requests that a movie import component display its user dialog box.

ComponentResult MovieImportDoUserDialogDataRef (
   MovieImportComponent    ci,
   Handle                  dataRef,
   OSType                  dataRefType,
   Boolean                 *canceled );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

dataRef

A data reference that specifies a storage location that contains the data to import.

dataRefType

The type of the data reference.

canceled

A pointer to a Boolean entity that is set to TRUE if the user cancels the export operation.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

This function brings up the option dialog for the import component. The data reference specified the storage location that contains the data to import.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
QuickTimeComponents.h

MovieImportSetMediaDataRef

Specifies a storage location that is to receive imported movie data.

ComponentResult MovieImportSetMediaDataRef (
   MovieImportComponent    ci,
   Handle                  dataRef,
   OSType                  dataRefType );

Parameters
ci

The component instance that identifies your connection to the graphics importer component.

dataRef

A data reference that specifies a storage location that receives the imported data.

dataRefType

The type of the data reference.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

By calling this function you can specify a storage location that receives some imported movie data.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
QuickTimeComponents.h

QTAddComponentPropertyListener

Installs a callback to monitor a component property.

ComponentResult QTAddComponentPropertyListener (
   ComponentInstance                 inComponent,
   ComponentPropertyClass            inPropClass,
   ComponentPropertyID               inPropID,
   QTComponentPropertyListenerUPP    inDispatchProc,
   void                              *inUserData );

Parameters
inComponent

A component instance, which you can get by calling OpenComponent or OpenDefaultComponent.

inPropClass

A value of type OSType that specifies a property class:

kComponentPropertyClassPropertyInfo ('pnfo')

A QTComponentPropertyInfo structure that defines a property information class.

kComponentPropertyInfoList ('list')

An array of QTComponentPropertyInfo structures, one for each property.

kComponentPropertyCacheSeed ('seed')

A component property cache seed value.

kComponentPropertyExtendedInfo ('meta')

A CFDictionary with extended property information.

kComponentPropertyCacheFlags ('flgs')

One of the following two flags:

kComponentPropertyCacheFlagNotPersistent

Property metadata should not be saved in persistent cache.

kComponentPropertyCacheFlagIsDynamic

Property metadata should not be cached at all.

inPropID

A value of type OSType that specifies a property ID.

inDispatchProc

A Universal Procedure Pointer to a QTComponentPropertyListenerProc callback.

inUserData

A pointer to user data that will be passed to the callback. You may pass NULL in this parameter.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

QTAddMoviePropertyListener

Installs a callback to monitor a movie property.

OSErr QTAddMoviePropertyListener (
   Movie                         inMovie,
   QTPropertyClass               inPropClass,
   QTPropertyID                  inPropID,
   QTMoviePropertyListenerUPP    inListenerProc,
   void                          *inUserData );

Parameters
inMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

inPropClass

A property class.

inPropID

A property ID.

inListenerProc

A Universal Procedure Pointer to a QTMoviePropertyListenerProc callback.

inUserData

A pointer to user data that will be passed to the callback.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

QTComponentPropertyListenerCollectionAddListener

Adds a listener callback for a specified property class and ID to a property listener collection.

OSStatus QTComponentPropertyListenerCollectionAddListener
(
   QTComponentPropertyListenersRef    inCollection,
   ComponentPropertyClass             inPropClass,
   ComponentPropertyID                inPropID,
   QTComponentPropertyListenerUPP     inListenerProc,
   const void                         *inListenerProcRefCon );

Parameters
inCollection

A property listener collection created by a previous call to QTComponentPropertyListenerCollectionCreate.

inPropClass

A value of type OSType that specifies a property class:

kComponentPropertyClassPropertyInfo ('pnfo')

A QTComponentPropertyInfo structure that defines a property information class.

kComponentPropertyInfoList ('list')

An array of QTComponentPropertyInfo structures, one for each property.

kComponentPropertyCacheSeed ('seed')

A component property cache seed value.

kComponentPropertyExtendedInfo ('meta')

A CFDictionary with extended property information.

kComponentPropertyCacheFlags ('flgs')

One of the following two flags:

kComponentPropertyCacheFlagNotPersistent

Property metadata should not be saved in persistent cache.

kComponentPropertyCacheFlagIsDynamic

Property metadata should not be cached at all.

inPropID

A value of type OSType that specifies a property ID.

inListenerProc

A QTComponentPropertyListenerProc callback.

inListenerProcRefCon

A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your function needs.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

QTComponentPropertyListenerCollectionCreate

Creates a collection of component property monitors.

OSStatus QTComponentPropertyListenerCollectionCreate
(
   CFAllocatorRef                                        inAllocator,
   const QTComponentPropertyListenerCollectionContext    *inContext,
   QTComponentPropertyListenersRef                    *outCollection
);

Parameters
inAllocator

A pointer to the allocator used to create the collection and its contents. You can pass NIL.

inContext

A pointer to a QTComponentPropertyInfo data structure. You can pass NIL if no structure exists. A copy of the contents of the structure is made; therefore you can pass a pointer to a structure on the stack.

outCollection

On return, a pointer to the new empty listener collection.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Platform Considerations

This function can be used to create a collection for use with ComponentPropertyListenerCollectionAddListener, ComponentPropertyListenerCollectionRemoveListener, ComponentPropertyListenerCollectionNotifyListeners, ComponentPropertyListenerCollectionIsEmpty, and ComponentPropertyListenerCollectionHasListenersForProperty.

Declared In
ImageCompression.h

QTComponentPropertyListenerCollectionHasListenersForProperty

Determines if there are any listeners in a component property listener collection registered for a specified property class and ID.

Boolean QTComponentPropertyListenerCollectionHasListenersForProperty
(
   QTComponentPropertyListenersRef    inCollection,
   ComponentPropertyClass             inPropClass,
   ComponentPropertyID                inPropID );

Parameters
inCollection

A property listener collection created by a previous call to QTComponentPropertyListenerCollectionCreate.

inPropClass

A value of type OSType that specifies a property class:

kComponentPropertyClassPropertyInfo ('pnfo')

A QTComponentPropertyInfo structure that defines a property information class.

kComponentPropertyInfoList ('list')

An array of QTComponentPropertyInfo structures, one for each property.

kComponentPropertyCacheSeed ('seed')

A component property cache seed value.

kComponentPropertyExtendedInfo ('meta')

A CFDictionary with extended property information.

kComponentPropertyCacheFlags ('flgs')

One of the following two flags:

kComponentPropertyCacheFlagNotPersistent

Property metadata should not be saved in persistent cache.

kComponentPropertyCacheFlagIsDynamic

Property metadata should not be cached at all.

inPropID

A value of type OSType that specifies a property ID.

Return Value

Returns TRUE if there are any listeners in the listener collection registered for the specified property class and ID, FALSE otherwise.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

QTComponentPropertyListenerCollectionIsEmpty

Determines if a listener collection is empty.

Boolean QTComponentPropertyListenerCollectionIsEmpty
(
   QTComponentPropertyListenersRef    inCollection );

Parameters
inCollection

A property listener collection created by a previous call to QTComponentPropertyListenerCollectionCreate.

Return Value

Returns TRUE if the collection is empty, FALSE otherwise.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

QTComponentPropertyListenerCollectionNotifyListeners

Calls all listener callbacks in a component property listener collection registered for a specified property class and ID.

OSStatus QTComponentPropertyListenerCollectionNotifyListeners
(
   QTComponentPropertyListenersRef    inCollection,
   ComponentInstance                  inNotifier,
   ComponentPropertyClass             inPropClass,
   ComponentPropertyID                inPropID,
   const void                         *inFilterProcRefCon,
   UInt32                             inFlags );

Parameters
inCollection

A property listener collection created by a previous call to QTComponentPropertyListenerCollectionCreate.

inNotifier

The caller’s component instance.

inPropClass

A value of type OSType that specifies a property class:

kComponentPropertyClassPropertyInfo ('pnfo')

A QTComponentPropertyInfo structure that defines a property information class.

kComponentPropertyInfoList ('list')

An array of QTComponentPropertyInfo structures, one for each property.

kComponentPropertyCacheSeed ('seed')

A component property cache seed value.

kComponentPropertyExtendedInfo ('meta')

A CFDictionary with extended property information.

kComponentPropertyCacheFlags ('flgs')

One of the following two flags:

kComponentPropertyCacheFlagNotPersistent

Property metadata should not be saved in persistent cache.

kComponentPropertyCacheFlagIsDynamic

Property metadata should not be cached at all.

inPropID

A value of type OSType that specifies a property ID.

inFilterProcRefCon

A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your function needs. You may pass NIL.

inFlags

Currently not used.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Discussion

If the filterProcUPP field in the QTComponentPropertyListenerCollectionContext data structure that was passed to QTComponentPropertyListenerCollectionCreate is not NIL, the QTComponentPropertyListenerFilterProc callback it points to will be called before each call to a registered listener that matches the specified property class and ID passed to this function. If the filter function return FALSE, that listener callback will not be called. This lets a component change the calling semantics (for example, to call another thread) or use a different listener callback signature.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

QTComponentPropertyListenerCollectionRemoveListener

Removes a listener callback with a specified property class and ID from a property listener collection.

OSStatus QTComponentPropertyListenerCollectionRemoveListener
(
   QTComponentPropertyListenersRef    inCollection,
   ComponentPropertyClass             inPropClass,
   ComponentPropertyID                inPropID,
   QTComponentPropertyListenerUPP     inListenerProc,
   const void                         *inListenerProcRefCon)

Parameters
inCollection

A property listener collection created by a previous call to QTComponentPropertyListenerCollectionCreate.

inPropClass

A value of type OSType that specifies a property class:

kComponentPropertyClassPropertyInfo ('pnfo')

A QTComponentPropertyInfo structure that defines a property information class.

kComponentPropertyInfoList ('list')

An array of QTComponentPropertyInfo structures, one for each property.

kComponentPropertyCacheSeed ('seed')

A component property cache seed value.

kComponentPropertyExtendedInfo ('meta')

A CFDictionary with extended property information.

kComponentPropertyCacheFlags ('flgs')

One of the following two flags:

kComponentPropertyCacheFlagNotPersistent

Property metadata should not be saved in persistent cache.

kComponentPropertyCacheFlagIsDynamic

Property metadata should not be cached at all.

inPropID

A value of type OSType that specifies a property ID.

inListenerProc

The QTComponentPropertyListenerProc callback to be removed.

inListenerProcRefCon

A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your function needs.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

QTGetComponentProperty

Returns the value of a specific component property.

ComponentResult QTGetComponentProperty (
   ComponentInstance         inComponent,
   ComponentPropertyClass    inPropClass,
   ComponentPropertyID       inPropID,
   ByteCount                 inPropValueSize,
   ComponentValuePtr         outPropValueAddress,
   ByteCount                 *outPropValueSizeUsed );

Parameters
inComponent

A component instance, which you can get by calling OpenComponent or OpenDefaultComponent.

inPropClass

A value of type OSType that specifies a property class:

kComponentPropertyClassPropertyInfo ('pnfo')

A QTComponentPropertyInfo structure that defines a property information class.

kComponentPropertyInfoList ('list')

An array of QTComponentPropertyInfo structures, one for each property.

kComponentPropertyCacheSeed ('seed')

A component property cache seed value.

kComponentPropertyExtendedInfo ('meta')

A CFDictionary with extended property information.

kComponentPropertyCacheFlags ('flgs')

One of the following two flags:

kComponentPropertyCacheFlagNotPersistent

Property metadata should not be saved in persistent cache.

kComponentPropertyCacheFlagIsDynamic

Property metadata should not be cached at all.

inPropID

A value of type OSType that specifies a property ID.

inPropValueSize

The size of the buffer allocated to hold the property value.

outPropValueAddress

A pointer to the buffer allocated to hold the property value.

outPropValueSizeUsed

On return, the actual size of the value written to the buffer.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

QTGetComponentPropertyInfo

Returns information about the properties of a component.

ComponentResult QTGetComponentPropertyInfo (
   ComponentInstance         inComponent,
   ComponentPropertyClass    inPropClass,
   ComponentPropertyID       inPropID,
   ComponentValueType        *outPropType,
   ByteCount                 *outPropValueSize,
   UInt32                    *outPropertyFlags );

Parameters
inComponent

A component instance, which you can get by calling OpenComponent or OpenDefaultComponent.

inPropClass

A value of type OSType that specifies a property class:

kComponentPropertyClassPropertyInfo ('pnfo')

A QTComponentPropertyInfo structure that defines a property information class.

kComponentPropertyInfoList ('list')

An array of QTComponentPropertyInfo structures, one for each property.

kComponentPropertyCacheSeed ('seed')

A component property cache seed value.

kComponentPropertyExtendedInfo ('meta')

A CFDictionary with extended property information.

kComponentPropertyCacheFlags ('flgs')

One of the following two flags:

kComponentPropertyCacheFlagNotPersistent

Property metadata should not be saved in persistent cache.

kComponentPropertyCacheFlagIsDynamic

Property metadata should not be cached at all.

inPropID

A value of type OSType that specifies a property ID.

outPropType

A pointer to memory allocated to hold the property type on return. This pointer may be NULL.

outPropValueSize

A pointer to memory allocated to hold the size of the property value on return. This pointer may be NULL.

outPropertyFlags

A pointer to memory allocated to hold property flags on return.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
ImageCompression.h

QTGetDataHandlerDirectoryDataReference

Returns a new data reference to the parent directory of the storage location associated with a data handler instance.

OSErr  QTGetDataHandlerDirectoryDataReference (
   DataHandler    dh,
   UInt32         flags,
   Handle         *outDataRef,
   OSType         *outDataRefType );

Parameters
dh

A data handler component instance that is associated with a file.

flags

Currently not used; pass 0.

outDataRef

A pointer to a handle in which the newly created alias data reference is returned.

outDataRefType

A pointer to memory in which the OSType of the newly created data reference is returned.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error. Returns paramErr if either of the output parameters was NIL.

Discussion

This function creates a new data reference that points at the parent directory of the storage location associated to the data handler instance.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

QTGetDataHandlerFullPathCFString

Returns the full pathname of the storage location associated with a data handler.

OSErr QTGetDataHandlerFullPathCFString (
   DataHandler    dh,
   QTPathStyle    style,
   CFStringRef    *outPath );

Parameters
dh

A data handler component instance that is associated with a file.

style

A constant that identifies the syntax of the pathname.

kQTNativeDefaultPathStyle

The default pathname syntax of the platform.

kQTPOSIXPathStyle

Used on Unix-based systems where pathname components are delimited by slashes.

kQTHFSPathStyle

The Macintosh HFS file system syntax where the delimiters are colons.

kQTWindowsPathStyle

The Windows pathname syntax that uses backslashes as component delimiters.

outPath

A pointer to a CFStringRef entity where a reference to the newly created CFString will be returned.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error. Returns paramErr if outPath is NIL.

Discussion

This function creates a new CFString that represents the full pathname of the storage location associated with the data handler passed in dh.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

QTGetDataHandlerTargetNameCFString

Returns the name of the storage location associated with a data handler.

OSErr  QTGetDataHandlerTargetNameCFString (
   DataHandler    dh,
   CFStringRef    *fileName );

Parameters
dh

A data handler component instance that is associated with a file.

fileName

A pointer to a CFStringRef entity where a reference to the newly created CFString will be returned.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error. Returns paramErr if fileName is NIL.

Discussion

This function creates a new CFString that represents the name of the storage location associated with the data handler passed in dh.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

QTGetDataReferenceDirectoryDataReference

Returns a new data reference for a parent directory.

OSErr QTGetDataReferenceDirectoryDataReference (
   Handle    dataRef,
   OSType    dataRefType,
   UInt32    flags,
   Handle    *outDataRef,
   OSType    *outDataRefType );

Parameters
dataRef

An alias data reference to which you want a new data reference that points to the directory.

dataRefType

The type the input data reference; must be AliasDataHandlerSubType.

flags

Currently not used; pass 0.

outDataRef

A pointer to a handle in which the newly created alias data reference is returned.

outDataRefType

A pointer to memory in which the OSType of the newly created data reference is returned.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error. Returns paramErr if either of the output parameters is NIL.

Discussion

This function returns a new data reference that points to the parent directory of the storage location specified by the data reference passed in dataRef. The new data reference returned will have the same type as dataRefType.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

QTGetDataReferenceFullPathCFString

Returns the full pathname of the target of the data reference as a CFString.

OSErr QTGetDataReferenceFullPathCFString (
   Handle         dataRef,
   OSType         dataRefType,
   QTPathStyle    pathStyle,
   CFStringRef    *outPath );

Parameters
dataRef

An alias data reference to which you want a new data reference that points to the directory.

dataRefType

The type the input data reference; must be AliasDataHandlerSubType.

pathStyle

A constant that identifies the syntax of the pathname.

kQTNativeDefaultPathStyle

The default pathname syntax of the platform.

kQTPOSIXPathStyle

Used on Unix-based systems where pathname components are delimited by slashes.

kQTHFSPathStyle

The Macintosh HFS file system syntax where the delimiters are colons.

kQTWindowsPathStyle

The Windows pathname syntax that uses backslashes as component delimiters.

outPath

A pointer to a CFStringRef entity where a reference to the newly created CFString will be returned.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error. Returns paramErr if either of the output parameters was NIL or the value of dataRefType is not AliasDataHandlerSubType.

Discussion

This function creates a new CFString that represents the full pathname of the target pointed to by the input data reference, which must be an alias data reference.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

QTGetDataReferenceTargetNameCFString

Returns the name of the target of a data reference as a CFString.

OSErr QTGetDataReferenceTargetNameCFString (
   Handle         dataRef,
   OSType         dataRefType,
   CFStringRef    *name );

Parameters
dataRef

An alias data reference to which you want a new data reference that points to its directory.

dataRefType

The type the input data reference; must be AliasDataHandlerSubType.

name

A pointer to a CFStringRef entity where a reference to the newly created CFString will be returned.

Return Value

See “Error Codes” in the QuickTime API Reference. Returns noErr if there is no error. Returns paramErr if either of the output parameters was NIL or the value of dataRefType is not AliasDataHandlerSubType.

Discussion

This function creates a new CFString that represents the name of the target pointed to by the input data reference, which must be an alias data reference.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h