---

Windows API Reference for QuickTime

Overview

Apple provides a small set of utility functions that are used for developing QuickTime applications in the Windows environment.

Functions

QTMLCreateMutex

Creates a synchronization object to facilitate mutually exclusive access to a Windows data structure.

QTMLMutex QTMLCreateMutex (
   void
);

Discussion

This function creates a mutex object for guarded access to data structures and routines that require mutually exclusive access. In a multithreaded preemptive environment, such as Windows NT, you can use the various mutex utility functions such as QTMLGrabMutex to protect a shared resource from simultaneous access by multiple threads or processes. Mutex objects are used throughout QTML to provide such protection.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

• Available in Mac OS X v10.3 and later.

Related Sample Code

• audiocodec
• audiocodec.win
• QTCarbonCoreImage101
• WhackedTV

Declared In

QTML.h

QTMLDestroyMutex

Deallocates a synchronization object created by QTMLCreateMutex.

void QTMLDestroyMutex (
   QTMLMutex mu
);

Parameters

mu

A mutex object.

Discussion

Call this function to deallocate the mutex object created by QTMLCreateMutex.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

• Available in Mac OS X v10.3 and later.

Related Sample Code

• audiocodec
• audiocodec.win
• WhackedTV

Declared In

QTML.h

QTMLGrabMutex

Confers ownership of a mutex created by QTMLCreateMutex.

void QTMLGrabMutex (
   QTMLMutex mu
);

Parameters

mu

A mutex object.

Discussion

Call this function when you require exclusive ownership of the resource guarded by a mutex. This function will return when you have gained this ownership. In the case where another thread or process holds the mutex, this function waits until that process or thread relinquishes control. If you need to determine if you can grab the mutex, without actually grabbing it, call QTMLTryGrabMutex.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

• Available in Mac OS X v10.3 and later.

Related Sample Code

• audiocodec
• audiocodec.win
• QTCarbonCoreImage101
• WhackedTV

Declared In

QTML.h

QTMLReturnMutex

Releases ownership of a QTMLMutex object.

void QTMLReturnMutex (
   QTMLMutex mu
);

Parameters

mu

A mutex object.

Discussion

Call this function to balance a call to QTMLGrabMutex when you are ready to relinquish control of the mutex and corresponding shared resource. By making this call, you allow other processes or threads waiting for the release of this mutex to gain access.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

• Available in Mac OS X v10.3 and later.

Related Sample Code

• audiocodec
• audiocodec.win
• QTCarbonCoreImage101
• WhackedTV

Declared In

QTML.h

QTMLTryGrabMutex

Determines if you would be able to get immediate ownership of a mutex created by QTMLCreateMutex.

Boolean QTMLTryGrabMutex (
   QTMLMutex mu
);

Parameters

mu

A mutex object.

Return Value

Returns TRUE if you are able to immediately grab the mutex, via the QTMLGrabMutex call, without having to wait.

Discussion

Call this function when you need to preflight a QTMLGrabMutex call.

Special Considerations

Under normal circumstances you should not need to make this call.

Version Notes

Introduced in QuickTime 4.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

QTML.h

QTMLYieldCPU

Yields time to other threads while your code is in a tight loop.

void QTMLYieldCPU (
   void
);

Discussion

Use this function from within tight loops to yield time to other threads. Using this function is similar to calling SystemTask from within a Macintosh event loop.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

QTML.h

QTMLYieldCPUTime

Yields time to other threads and specifies the sleep time while in a tight loop.

void QTMLYieldCPUTime (
   long milliSeconds,
   unsigned long flags
);

Parameters

milliSeconds

Number of milliseconds to sleep before returning to the caller.

flags

A flag (see below) that specifies an option for this function. See these constants:

• kQTMLHandlePortEvents

Discussion

Use this function from within tight loops to yield time to other threads.

Special Considerations

This function differs from QTMLYieldCPU in that you can specify the time to sleep as well as optionally have QTML process Win32 messages while waiting for the yield time to expire.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

QTML.h

Callbacks

Data Types

QTMLMutex

Represents a type used by the Windows API API.

typedef long QTMLMutex;

Availability

• Available in Mac OS X v10.3 and later.

Declared In

QTML.h

Constants

QTMLYieldCPUTime Values

Constants passed to QTMLYieldCPUTime.

enum {
   kQTMLHandlePortEvents         = (1L << 0) /* ask for event handling during the yield*/
};

Declared In

QTML.h

---