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:

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 */
};

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:

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 */
};

Field

Description

callBackFlags

Contains flags that your component can use to communicate scheduling information about the callback event to the Movie Toolbox. This scheduling information tells the Movie Toolbox what time base events your clock component needs to know about in order to support the callback event.

reserved1

Reserved for use by Apple.

qtPrivate

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 */
};

Flag

Description

qtcbNeedsRateChanges

Indicates that your clock component needs to know about rate changes. If you set this flag to 1, QuickTime calls your ClockRateChanged function whenever the rate of the callback event's time base changes.

qtcbNeedsTimeChanges

Indicates that your clock component needs to know about time changes. If you set this flag to 1, the Movie Toolbox calls your ClockTimeChanged function whenever a program changes the time value of the time base, or when the time value changes by an amount that is different from the time base's rate.

qtcbNeedsStartStopChanges

Indicates that your clock component needs to know about the time base's start and stop changes. If you set this flag to 1, the Movie Toolbox calls your ClockStartStopChanged function whenever a program changes the start or stop time of the time base.

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 */