Inside Macintosh: QuickTime Reference

A Change in the Loading Model

The loading model has changed from this

NewMovieFrom... <playable> <complete>

to this

NewMovieFrom... <incomplete> <playable> <complete>

In the old model, you could play the movie but not all the data would be made available. In the new model, when the movie is loaded -- i.e., between the time it is loaded and playable -- it doesn't "know" its tracks, or its structure.

During this <incomplete> phase querying the movie for its characteristics is not helpful. Only at the point where it is playable can such queries be useful.

To determine when such queries are useful or to enable or disable behavior, a new QuickTime Movie Toolbox API has been introduced in QuickTime 4.1. This is the GetMovieLoadState function.

pascal long GetMovieLoadState( Movie theMovie );

The GetMovieLoadState routine returns a value that indicates the state of the loading process.

kMovieLoadStateLoading // searching for movie resource kMovieLoadStatePlayable // movie fully formed, fast-start would work kMovieLoadStateComplete // all media data is available

These values are ordered so that the values treated as numbers conform to this rule:

kMovieLoadStateLoading < kMovieLoadStatePlayable < kMovieLoadStateComplete

This allows code to perform relative comparisons against these milestones to determine if certain operations make sense.

There is also an additional state kMovieLoadStateError indicating that the loading of the movie failed. This typically means that a URL could not be found or loaded. This has a negative value, so that the above rule becomes:

kMovieLoadStateError < kMovieLoadStateLoading < kMovieLoadStatePlayable < kMovieLoadStateComplete

If the value is less than complete, then you should not assume that you can save it.

Note: If the load state is negative, then this indicates an error has occurred.

Not all states will be seen by a client. A completely local movie will transition directly to kMovieLoadStateComplete. A local movie with media stored on a slow connection will probably transition to kMovieLoadStatePlayable since fast-starting will occur.

By way of a quick example of code using this new information, consider how the load state might be used by an application updated to recognize asynchronous movie loading. Assume that it called the NewMovieFromDataRef function to open a URL:

err = NewMovieFromDataRef( &theMovie, newMovieActive | newMovieAsyncOK, nil, url, URLDataHandlerSubType );

and periodically it will check the movie to see if it has reached a particular state of interest:

void checkOnMovie( MovieInfo movieInfo ) { long loadState; loadState = GetMovieLoadState(movieInfo->theMovie); if (movieInfo->loadState == loadState) // didn't change return; movieInfo->loadState = loadState; // new state if (loadState < 0) { // failed to load the movie so tell the user and dispose of movie } if (loadState < kMovieLoadStatePlayable) { // just keep tasking the movie so it gets time to load } if (loadState < kMovieLoadStateComplete) { // we just became playable // get movie box and size window // put a movie controller on this movie // update other UI appropriately // check for auto play } if (loadState >= kMovieLoadStateComplete) { // now we know all media data is available and we might // only now allow the user to perform a self-contained save // or an export } }

Until the movie has reached its playable state, an application should not try to attach a movie controller, since the user data that allows the QuickTime Movie Toolbox to choose the type of movie controller will not be available. Also, the application should call the MoviesTask function to give it time to continue loading.

This offers a way to detect the difference between when the movie is fast-starting and therefore its data is not all available and when it is fully loaded. This is useful in enabling certain menu items only appropriate when all media is accessible.

In the future, it is expected that new and useful states will be added. However, it will be done in such a way that the above ordering still holds.

GetMovieStatus Updated

Other API Additions

Inside Macintosh: QuickTime Reference