Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Initializing QuickTime
QuickTime must be initialized before applications or components can make calls to the QuickTime Movie Toolbox.
If you are writing a threaded application, and intend to call QuickTime functions from multiple threads, you need to initialize QuickTime for each worker thread explicitly.
Windows applications must initialize the QuickTime Media Layer (QTML), prior to initializing QuickTime itself. This also serves to verify that QuickTime for Windows is installed.
As part of the initialization process, it is usually advisable to check the installed version of QuickTime to ensure that all required features are present on the user’s machine. This can also serve as a method to verify that QuickTime is installed prior to initializing it.
Initializing QuickTime Media Layer for Windows
If your application runs on a Windows operating system, you need to verify that QuickTime is installed and initialize the QuickTime Media Layer (QTML). A single call to InitializeQTML
does both. Listing 2-1 shows the call to InitializeQTML
.
Listing 2-1 Calling InitializeQTML
static void QuickTimeQTML (void) |
{ |
OSErr err; |
err = InitializeQTML(0L); |
CheckError (err, "InitializeQTML error" ); |
} |
Use the InitializeQTML
function to initialize QuickTime before calling any other QuickTime function. It is recommended that you call InitializeQTML
at the very beginning of your program, in your WinMain
function, before creating your main window.
InitializeQTML
supports flags that allow you to specify how QuickTime should behave. For example, you can tell QuickTime to operate exclusively in full-screen mode, or to use the Windows Graphics Device Interface (GDI) for all drawing, rather than the DirectDraw or DCI services.
If QuickTime is not installed, the InitializeQTML
function is not available and an error is returned.
If your application is distributed on a CD, you should include QuickTime installers on the disc and run the Windows installer if QuickTime is not present. (Including the installer requires a license from Apple, but there is currently no fee for such a license. To obtain a license, click the QuickTime link at http://developer.apple.com/softwarelicensing/agreements/quicktime.html and follow the instructions there.) Alternatively, you may prompt the user to download QuickTime at http://www.apple.com/quicktime/download/.
If you are writing a routine that does not know whether InitializeQTML
has already been called, call InitializeQTML
at the beginning of the routine and TerminateQTML
at the end.
It does no harm to call InitializeQTML
more than once, as long as each call is nested with a matching call to TerminateQTML
. If this function has already been called, subsequent calls do nothing except increment a counter. Calls to TerminateQTML
just decrement the counter (if it is nonzero). Only the first nested call and the last nested call to TerminateQTML
do any actual work, so there is no penalty for having multiple nested calls.
Once the QuickTime Media Layer has been initialized, Windows programmers should follow the same steps that Mac OS programmers follow to test the QuickTime version and initialize QuickTime itself.
Checking the QuickTime Version
Your application may want to check the version of QuickTime installed on the user’s system at runtime, to determine if all the needed features are supported. You should do this before initializing QuickTime.
To get the version of QuickTime installed on the user’s computer, call the Gestalt
function (the necessary parts of which are included in QuickTime for Windows). The Gestalt
function returns the QuickTime version if the appropriate selectors are passed in, as shown in Listing 2-2.
Listing 2-2 Getting the QuickTime version with Gestalt
{ |
/* check the version of QuickTime installed */ |
long version; |
OSErr result; |
result = Gestalt(gestaltQuickTime,&version); |
if ((result == noErr) && (version >= 0x05020000)) |
{ |
/* we have version 5.0.2 or later */ |
} |
} |
Initializing a QuickTime Environment
Your application initializes a working QuickTime environment by calling EnterMovies
.
EnterMovies(); |
If you are writing a routine that does not know whether QuickTime has already been initialized, go ahead and call EnterMovies
; repeated calls do no harm.
You do not need to balance calls to EnterMovies
with calls to ExitMovies
. Call ExitMovies
only if you are done using QuickTime and want to free the resources as soon as possible without terminating your application. ExitMovies
is called automatically when your application quits.
Windows users need to initialize QTML before calling EnterMovies
, as shown in Listing 2-3.
Listing 2-3 Initializing QTML and QuickTime for Windows
static void InitQTMLandQuickTime (void) |
{ |
OSErr err; |
err = InitializeQTML(0L); |
CheckError (err, "InitializeQTML error" ); |
EnterMovies(); |
} |
EnterMovies
initializes a single, non-reentrant QuickTime environment for your application.
If your application uses QuickTime on multiple threads simultaneously, call EnterMoviesOnThread
from each thread that uses QuickTime to create a local QuickTime environment for that thread (requires QuickTime 6 or later).
For more information about threaded programming and QuickTime, see Technical Note TN2125, Thread-safe programming in QuickTime.
Copyright © 2004, 2018 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2018-06-04