Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
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 */ |
}; |
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 theRemoveCallBackFromTimeBase
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
andGetNextCallBack
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 */ |
}; |
Field |
Description |
---|---|
|
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. |
|
Reserved for use by Apple. |
|
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 |
---|---|
|
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. |
|
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. |
|
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 |
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 */ |
Copyright © 2005, 2018 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2018-06-04