< Previous PageNext Page > Hide TOC

Clock Component Functions

This section describes the functions that are provided by clock components. These functions are described from the perspective of the Movie Toolbox, the entity that is most likely to call clock components. If you are developing a clock component, your component must behave as described here.

This section has been divided into the following topics:

• Getting the Current Time describes the function that allows QuickTime to obtain the current time from a clock component. This function can also be used by applications.

• Using the Callback Functions discusses the functions that allow clock components to help applications define and schedule time base callback functions.

• Managing the Time describes functions that help clock components manage their time correctly.

If you are developing an application that uses clock components, you should read the next section, Getting the Current Time.

If you are developing a clock component, you need to be familiar with all the functions described in this section.

You can use the following constants to refer to the request codes for each of the functions that your clock component must support:

/* constants to refer to request codes for supported functions */

enum {

    kClockGetTimeSelect                     = 0x1,  /* ClockGetTime */ 

    kClockNewCallBackSelect                 = 0x2,/* ClockNewCallBack */

    kClockDisposeCallBackSelect             = 0x3,/* ClockDisposeCallBack */

    kClockCallMeWhenSelect                  = 0x4,/* ClockCallMeWhen */

    kClockCancelCallBackSelect              = 0x5,/* ClockCancelCallBack */

    kClockRateChangedSelect                 = 0x6,/* ClockRateChanged */

    kClockTimeChangedSelect                 = 0x7,/* ClockTimeChanged */

    kClockSetTimeBaseSelect                 = 0x8,/* ClockSetTimeBase */

    kClockStartStopChangedSelect            = 0x9,/* ClockStartStopChanged */

    kClockGetRateSelect                     = 0xA /* ClockGetRate */

};

In this section:

Getting the Current Time
Using the Callback Functions
Managing the Time
Movie Toolbox Clock Support Functions
Data Types
Component Types for Clocks

Getting the Current Time

Clock components provide a single function, ClockGetTime, that allows the Movie Toolbox to obtain the current time.

Using the Callback Functions

Applications that use QuickTime time bases may define callback functions that are associated with a specific time base. Applications can then use these callback functions to perform activities that are triggered by temporal events, such as a certain time being reached or a specified rate being achieved. The time base functions of the Movie Toolbox interact with clock components to schedule the invocation of these callback functions; your clock component is responsible for calling the callback function at its scheduled time.

The functions described in this section are called by the Movie Toolbox to support applications that define time base callback functions. Note that your clock component can delegate its callback events to another component by calling the Component Manager’s DelegateComponent function.

The ClockNewCallBack function allows your clock component to allocate the memory to support a new callback event. When an application discards a callback event, the Movie Toolbox calls your clock component’s ClockDisposeCallBack function.

The Movie Toolbox calls your clock component’s ClockCallMeWhen function when an application wants to schedule a callback event. When the callback function is to be invoked to service the event, the Movie Toolbox calls your component’s ClockCancelCallBack function so that you can remove the callback event from the list of scheduled events.

Managing the Time

Clock components provide several functions that allow the Movie Toolbox to alert your component to changes in its environment. Three of these functions, ClockTimeChanged, ClockRateChanged, and ClockStartStopChanged, are associated with application callback functions and help your component determine whether to invoke the callback function. The fourth, the ClockSetTimeBase function, tells your clock component about the time base it is supporting.

Movie Toolbox Clock Support Functions

The Movie Toolbox provides a number of support functions for clock components. All of these functions help your component manage its associated callback functions. Your clock component may call any of these functions at interrupt time. These functions should only be called by clock components:

• Use the AddCallBackToTimeBase function to add a callback event to the list of scheduled callback events maintained by the Movie Toolbox. You should use the RemoveCallBackFromTimeBase function to remove a callback event from the list.

• When your clock component determines that it is time to invoke a callback function, you should use the ExecuteCallBack function to cause the Movie Toolbox to call the function.

• If your clock component needs to scan all its associated callback events, you can use the GetFirstCallBack and GetNextCallBack functions.

Data Types

The clock component data structure is a private data structure. Programs that use your clock component never change the contents of this data structure directly. Your clock component provides functions that allow programs to use this data structure.

The callback header structure specifies the callback function for an operation. Your application can obtain callback function identifiers by calling its clock component’s ClockNewCallBack function.

The QTCallBackHeader data type defines the callback header structure.

struct QTCallBackHeader {

    long    callBackFlags;    /* flags used by clock component to communicate

                                 scheduling data about callback to QuickTime */ 

    long    reserved1;        /* reserved for use by Apple */

    char    qtPrivate[40];    /* reserved for use by Apple */

};

The following flags are defined for the callBackFlags field (all other flags must be set to 0):

enum {

    qtcbNeedsRateChanges = 1,       /* clock needs to know about rate

    qtcbNeedsTimeChanges = 2        /* clock needs to know about time

    qtcbNeedsStartStopChanges = 4   /* clock needs to know about

                                       time base changes */ 

};

Component Types for Clocks

Apple has defined a type value and a number of subtype values for clock components. All clock components have a component type value of 'clok'. The component subtype value indicates the type of clock. You can use the following constants to specify these type and subtype values.

#define clockComponentType        'clok'     /* clock component type */

#define systemTickClock           'tick'     /* system tick clock */

#define systemSecondClock         'seco'     /* system seconds clock */

#define systemMillisecondClock    'mill'     /* system millisecond clock */

#define systemMicrosecondClock    'micr'     /* system microsecond clock */

< Previous PageNext Page > Hide TOC