Importing and Exporting Movie Data

Your application starts a data import or export operation by calling the Movie Toolbox. There are several Movie Toolbox functions that allow you to specify a data import or data export component. For example, the PasteHandleIntoMovie and ConvertFileToMovieFile functions allow you to specify a movie data import component. The PutMovieIntoTypedHandle and ConvertMovieToFile functions allow you to specify a movie data export component. All of these functions select a component for you if you do not specify one yourself.

When you import data into a QuickTime movie, you can specify that the data be placed into a specific existing track in the movie, into a new track that is created by the movie data import component, or into one or more existing tracks (in this case, the component may create additional tracks, if necessary).

When you export data from a QuickTime movie, you can request data from a specific track or from the entire movie. In addition, you can specify a segment of the track or movie to be exported.

Configuring a Movie Data Exchange Component

You do not need to configure a movie data exchange component before you use it to convert data into or out of a QuickTime movie. These components are implemented in such a way that they can operate successfully using their own default configuration information. In fact, some data exchange components do not allow you to configure them. However, most data exchange components do support some or all of the configuration functions that are defined for components of this type.

If you are going to configure a data exchange component, you must do so before you start the data exchange operation. You must call the component directly in order to set the configuration; the Movie Toolbox does not do this for you. Use the functions described in Configuring Movie Data Import Components and Configuring Movie Data Export Components as appropriate. Note that all of these functions are optional; that is, it is up to the developer of the component to decide whether or not to support a given configuration function. If the component does not support a function you have called, the component returns an error code of badComponentSelector.

Configuring Movie Data Import Components

Your component may provide one or more configuration functions. These functions allow applications to configure your component before the Movie Toolbox calls your component to start the import process. Note that applications may call these functions directly.

All of these functions are optional. If your component receives a request that it does not support, you should return the badComponentSelector error code. In addition, your component should work properly even if none of these functions is called.

These functions address a variety of configuration issues. The MovieImportSetSampleDuration function allows an application to set your component’s sample duration. Use the MovieImportSetDuration function to control the duration of the imported data. Applications can use the MovieImportSetDimensions function to specify the spatial dimensions of a new track. Use the MovieImportSetSampleDescription function to supply a sample description structure to your movie data import component.

The MovieImportSetMediaFile function allows applications to direct your component’s output to a specific media file. Applications can provide additional data to your component by calling the MovieImportSetAuxiliaryData function. The MovieImportSetChunkSize function allows applications to control the chunk size in the new media. Applications can inform you that the source data came from the scrap by calling your MovieImportSetFromScrap function.

Applications can specify a progress function for use by your component by calling the MovieImportSetProgressProcfunction.

Applications can instruct your component to display its user dialog box by calling the MovieImportDoUserDialog function.

Configuring Movie Data Export Components

Your component may provide one or more configuration functions. These functions allow applications to configure your component before the Movie Toolbox calls your component to start the export process. Note that applications may call these functions directly.

All of these functions are optional. If your component receives a request that it does not support, you should return the badComponentSelector error code. In addition, your component should work properly even if none of these functions is called.

These functions address a variety of configuration issues. Applications can retrieve additional data from your component by calling the MovieExportGetAuxiliaryData function.

Applications can specify a progress function for use by your component by calling the MovieExportSetProgressProc function.

Applications can instruct your component to display its user dialog box by calling the MovieExportDoUserDialog function.

Finding a Specific Movie Data Exchange Component

If you are going to specify a particular data exchange component to the Movie Toolbox, you must first open a connection to that component. Use the Component Manager’s OpenDefaultComponent or OpenComponent function to open a connection to a movie data exchange component. Before you can open that connection, however, you must find an appropriate movie data exchange component.

To find an appropriate data exchange component, you may need to use the Component Manager’s FindNextComponent function. You specify the characteristics of the component you are seeking in a component description record; in particular, in the componentType, componentSubtype, componentManufacturer, and componentFlags fields.

Movie data import components have a component type value of 'eat ', which is defined by the MovieImportType constant. Movie data export components have a type value of 'spit', which is defined by the MovieExportType constant.

Movie data exchange components use their component subtype and manufacturer values to indicate the type of data that they support. The subtype value indicates the type of data that these components can import or export. For example, movie data import components that convert text into QuickTime movie data have a component subtype value of 'TEXT'. A single data exchange component may support only one data type.

The manufacturer field indicates the QuickTime media type that is supported by the component. For example, movie data export components that can read data from a sound media have a manufacturer value of 'soun' (this value is defined by the SoundMediaType constant). If a data exchange component can work with more than one media type, it specifies a manufacturer value of 0.

In addition, these components use the componentFlags field to indicate more specific information about their capabilities. The following flags are currently defined:

enum {

    canMovieImportHandles          = 1,    /* can import from  handles */

    canMovieImportFiles            = 2,    /* can import from files */

    hasMovieImportUserInterface    = 4,    /* import has user  interface */

    canMovieExportHandles          = 8,    /* can export to handles */

    canMovieExportFiles            = 16,   /* can export to files */

    hasMovieExportUserInterface    = 32,   /* export has user interface */

    dontAutoFileMovieImport        = 64    /* turn off automatic file conversion */

};

Movie data import components use the first three flags to specify their capabilities. If a component can convert data from a handle, its canMovieImportHandles flag is set to 1. If it can work with files, its canMovieImportFiles flag is set to 1. Note that both of these flags may be set to 1 if a single component can work with both files and handles. If a component provides a dialog box that allows the user to specify configuration information, the hasMovieImportUserInterface flag is set to 1. If a component does not support the automatic conversion of standard files to movies in an import component, set the dontAutoFileMovieImport flag to 1 (the default setting is 0).

Movie data export components use the other three flags in the same way.

Specifying a Part of a File to Import

When using certain movie import components, applications can import data from a part of a file rather than the entire file by calling MovieImportSetOffsetAndLimit or MovieImportSetOffsetAndLimit64. The latter function accomodates 64-bit offsets instead of just 32-bit offsets. These functions let an application specify a byte offset into the file at which the import operation begins and another offset, known as the limit, that indicates the last data in the file that can be imported. This function is especially useful when one file format is embedded in another; it allows an application to skip header data for the enclosing file and begin importing data at the start of the desired format.

Not all movie import components support the MovieImportSetOffsetAndLimit or MovieImportSetOffsetAndLimit64 function. Those that do include the movie import components provided with QuickTime for the kQTFileTypeAIFF, kQTFileTypeWave, and kQTFileTypeMuLaw file types. Those that do not return the result code badComponentSelector in response to a MovieImportSetOffsetAndLimit or MovieImportSetOffsetAndLimit64 call. If your export component implements MovieImportSetOffsetAndLimit64, it should implement MovieImportSetOffsetAndLimit too, since older clients may not use the new 64-bit offset version of the call.

Getting a List of Supported MIME Types

Applications can get a list of MIME types supported by a movie import component by calling the MovieImportGetMIMETypeList function.

In QuickTime, import components should additionally include a public component resource holding the same data that MovieImportGetMIMETypeList would return. This public resource’s public type and ID should be 'mime' and 1, respectively; these values are held in the import component’s public resource list. The following shows an example of such a list:

resource 'thnr' (kMyImportComponentResID)

{

    'mime', 1, 0,

    'mime', kMyImportMIMETypeListResID, 0

}

By including this public resource, QuickTime and applications don’t need to open the import component and call MovieImportGetMIMETypeList to determine the MIME types the importer supports. In the absence of this resource, QuickTime and applications will use MovieImportGetMIMETypeList.

Determining Whether Movie Data Export Is Possible

Although a movie export component can export one or more media types, it may not be able to export all the kinds of data stored in those media. Applications can find out whether a movie export component can export all the data for a particular movie or track by calling the MovieExportValidate function.

Not all export components implement the MovieExportValidate call. In the following code snippet, you make the Validate call, and even if the component routine is not implemented it is still true:

Boolean canExport = true;

    MovieExportValidate(ci, &canExport);

    if(canExport) {

    . . .

    }