CMSync Reference

Framework
CoreMedia.framework
Declared in
CMSync.h

Overview

CMSync API provides a reference clock that you can use to synchronize applications and devices. This API also provides functions to monitor relative drift between CMClocks and functions that are associated with timer services.

Functions

CMClockConvertHostTimeToSystemUnits

Converts a host time from CMTime to the host time's native units.

   uint64_t CMClockConvertHostTimeToSystemUnits( CMTime hostTime )
Discussion

This function performs a scale conversion, not a clock conversion. It can be more accurate than CMTimeConvertScale because the system units may have a non-integer timescale. On Mac OS X, this function converts to the units of mach_absolute_time.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMClockGetAnchorTime

Retrieves the current time from a clock and also the matching time from the clock's reference clock.

OSStatus CMClockGetAnchorTime(CMClockRef clock,
   CMTime *outClockTime,
   CMTime *outReferenceClockTime )
Discussion

To make practical use of this, you may need to know what the clock's reference clock is.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMClockGetHostTimeClock

Returns a reference to the singleton clock logically identified with host time.

CMClockRef CMClockGetHostTimeClock( void );
Discussion

On Mac OS X, the host time clock uses mach_absolute_time but returns a value with a large integer timescale (e.g. nanoseconds).

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMClockGetTime

Retrieves the current time from a clock.

CMTime CMClockGetTime(CMClockRef clock )
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMClockGetTypeID

Returns the CFTypeID of the CMClock.

CFTypeID CMClockGetTypeID(void)
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMClockInvalidate

Makes the clock stop functioning.

void CMClockInvalidate(CMClockRef clock );
Discussion

After invalidation, the clock will return errors from all APIs. This should only be called by the "owner" of the clock, who knows (for example) that some piece of hardware has gone away, and the clock will no longer work (and might even crash).

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMClockMakeHostTimeFromSystemUnits

Converts a host time from native units to CMTime.

CMTime CMClockMakeHostTimeFromSystemUnits(uint64_t hostTime )
Discussion

The returned value will have a large integer timescale (eg, nanoseconds). This function handles situations where host time's native units use a non-integer timescale. On Mac OS X, this function converts from the units of mach_absolute_time.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMClockMightDrift

Returns a Boolean that indicates whether it is possible for two clocks to drift relative to each other.

Boolean CMClockMightDrift(CMClockRef clock, CMClockRef otherClock );
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMSyncConvertTime

Converts a time from one timebase or clock to another timebase or clock.

CMTime CMSyncConvertTime(CMTime time, CMClockOrTimebaseRef fromClockOrTimebase, CMClockOrTimebaseRef toClockOrTimebase )
Discussion

If both have a common master, this calculation is performed purely based on the mathematical rates and offsets in the common tree rooted in that master. If they have different master clocks (or are both clocks), this calculation also compensates for measured drift between the clocks. To convert to or from host time, pass CMClockGetHostTimeClock() as the appropriate argument.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMSyncGetRelativeRate

Queries the relative rate of one timebase or clock relative to another timebase or clock.

Float64  CMSyncGetRelativeRate(CMClockOrTimebaseRef ofClockOrTimebase, CMClockOrTimebaseRef relativeToClockOrTimebase );
Discussion

If both have a common master, this calculation is performed purely based on the rates in the common tree rooted in that master. If they have different master clocks (or are both clocks), this calculation takes into account the measured drift between the two clocks, using host time as a pivot. The rate of a moving timebase relative to a stopped timebase is a NaN. Calling CMTimebaseGetEffectiveRate(timebase) is equivalent to calling CMSyncGetRelativeRate(timebase, CMTimebaseGetUltimateMasterClock(timebase)).

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMSyncGetRelativeRateAndAnchorTime

Queries the relative rate of one timebase or clock relative to another timebase or clock and the times of each timebase or clock at which the relative rate went into effect.

OSStatus CMSyncGetRelativeRateAndAnchorTime(CMClockOrTimebaseRef ofClockOrTimebase,
   CMClockOrTimebaseRef relativeToClockOrTimebase,
   Float64* outRelativeRate,
   CMTime* outOfClockOrTimebaseAnchorTime,
   CMTime* outRelativeToClockOrTimebaseAnchorTime);
Discussion

If both have a common master, this calculation is performed purely based on the rates in the common tree rooted in that master. If they have different master clocks (or are both clocks), this calculation takes into account the measured drift between the two clocks, using host time as a pivot. The rate of a moving timebase relative to a stopped timebase is a NaN.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMSyncGetTime

A helper function to get time from a clock or timebase.

CMTime CMSyncGetTime(CMClockOrTimebaseRef clockOrTimebase );
Discussion

CMSyncGetTime simply calls either CMClockGetTime or CMTimebaseGetTime, as appropriate. It comes in handy for things like: CMSyncGetTime(CMTimebaseGetMaster(timebase)).

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMSyncMightDrift

Returns a Boolean indicating whether it is possible for one timebase/clock to drift relative to the other.

Boolean CMSyncMightDrift(CMClockOrTimebaseRef clockOrTimebase1, CMClockOrTimebaseRef clockOrTimebase2 );
Discussion

A timebase can drift relative to another if they are ultimately mastered by clocks that can drift relative to each other.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseAddTimer

Adds the timer to the list of timers managed by the timebase.

OSStatus CMTimebaseAddTimer(
   CMTimebaseRef timebase,
   CFRunLoopTimerRef timer,
   CFRunLoopRef runloop )
Discussion

The timer must be a repeating run loop timer (with a very long interval at least as long as kCMTimebaseVeryLongCFTimeInterval), attached to a runloop. The timebase will retain the timer, and will maintain its "NextFireDate" according to the CMTime set using CMTimebaseSetTimerNextFireTime. Until the first call to CMTimebaseSetTimerNextFireTime, the "NextFireDate" will be set to a future time. The runloop that timer is attached to must be passed in and the timebase will retain that runloop. The retained runloop will be used to call CFRunLoopWakeUp() any time the timebase modifies the timer's fire date.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseAddTimerDispatchSource

Adds the timer dispatch source to the list of timers managed by the timebase.

OSStatus CMTimebaseAddTimerDispatchSource(
   CMTimebaseRef timebase,
   dispatch_source_t timerSource );
Discussion

The timer source must have been created by calling dispatch_source_create( DISPATCH_SOURCE_TYPE_TIMER, 0, 0, some_dispatch_queue ) and should have had an event handler associated with it via dispatch_source_set_event_handler( timerSource, some_handler_block ) or dispatch_source_set_event_handler_f( timerSource, some_handler_function ). Don't forget to call dispatch_resume( timerSource ) as dispatch sources are created in a suspended state. The timebase will retain the timer source, and will maintain its start time according to the CMTime set using CMTimebaseSetTimerDispatchSourceNextFireTime. Until the first call to CMTimebaseSetTimerDispatchSourceNextFireTime, the start time will be set to DISPATCH_TIME_FOREVER. For more information on dispatch sources see Dispatch Sources.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseCreateWithMasterClock

Creates a timebase driven by the given clock.

OSStatus CMTimebaseCreateWithMasterClock(
   CFAllocatorRef allocator,
   CMClockRef masterClock,
   CMTimebaseRef *timebaseOut )
Discussion

The timebase will initially have rate zero and time zero. Pass CMClockGetHostTimeClock() for masterClock to have the host time clock drive this timebase.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseCreateWithMasterTimebase

Creates a timebase driven by the given master timebase.

OSStatus CMTimebaseCreateWithMasterTimebase(
CFAllocatorRef allocator,
   CMTimebaseRef masterTimebase,
   CMTimebaseRef *timebaseOut )
Discussion

The timebase will initially have rate zero and time zero.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetEffectiveRate

Gets the effective rate of a timebase (which combines its rate with the rates of all its master timebases).

Float64 CMTimebaseGetEffectiveRate(
   CMTimebaseRef timebase );
Discussion

Calling CMTimebaseGetEffectiveRate(timebase) is equivalent to calling CMSyncGetRelativeRate(timebase, CMTimebaseGetUltimateMasterClock(timebase)).

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetMaster

Returns the immediate master (either timebase or clock) of a timebase.

CMClockOrTimebaseRef CMTimebaseGetMaster(
   CMTimebaseRef timebase )
Discussion

Returns NULL if there was an error (such as timebase == NULL). Example of use: time = CMSyncGetTime(CMTimebaseGetMaster(timebase));

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetMasterClock

Returns the immediate master clock of a timebase.

CMClockRef CMTimebaseGetMasterClock(         CMTimebaseRef timebase );
Discussion

Returns NULL if the timebase actually has a master timebase instead of a master clock.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetMasterTimebase

Returns the immediate master timebase of a timebase.

CMTimebaseRef CMTimebaseGetMasterTimebase(
   CMTimebaseRef timebase )
Discussion

Returns NULL if the timebase actually has a master clock instead of a master timebase.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetRate

Retrieves the current rate of a timebase.

CMTimebaseGetRate(
   CMTimebaseRef timebase )
Discussion

This is the rate relative to its immediate master clock or timebase. For example, if a timebase is running at twice the rate of its master, its rate is 2.0.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetTime

Retrieves the current time from a timebase.

CMTime CMTimebaseGetTime(
   CMTimebaseRef timebase );
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetTimeAndRate

Retrieves the current time and rate of a timebase.

CMTimebaseGetTimeAndRate(
   CMTimebaseRef timebase,
   CMTime *outTime,
   Float64 *outRate );
Discussion

You can use this function to take a consistent snapshot of the two values, avoiding possible inconsistencies due to external changes between retrieval of time and rate.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetTimeWithTimeScale

Retrieves the current time from a timebase in the specified timescale.

CMTime CMTimebaseGetTimeWithTimeScale(
   CMTimebaseRef timebase,
   CMTimeScale timescale,
   CMTimeRoundingMethod method);
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetTypeID

Returns the CFTypeID for CMTimebase.

CFTypeID CMTimebaseGetTypeID(void);
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseGetUltimateMasterClock

Returns the master clock that is the master of all of a timebase's master timebases.

CMClockRef CMTimebaseGetUltimateMasterClock(CMTimebaseRef timebase );
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseNotificationBarrier

Requests that the timebase wait until it is not posting any notifications.

OSStatus CMTimebaseNotificationBarrier(CMTimebaseRef timebase );
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseRemoveTimer

Removes the timer from the list of timers managed by the timebase.

OSStatus CMTimebaseRemoveTimer(CMTimebaseRef timebase, CFRunLoopTimerRef timer );
Discussion

The timebase will no longer maintain the timer's "NextFireDate". If the timer is invalidated, the timebase will eventually remove it from its list and release it even if this function is not called.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseRemoveTimerDispatchSource

Removes the timer dispatch source from the list of timers managed by the timebase.

OSStatus CMTimebaseRemoveTimerDispatchSource(CMTimebaseRef timebase,
dispatch_source_t timerSource );
Discussion

The timebase will no longer maintain the timer source's start time. If the timer source is cancelled, the timebase will eventually remove it from its list and release it even if this function is not called.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseSetAnchorTime

Sets the time of a timebase at a particular master time.

CMTimebaseSetAnchorTime(
   CMTimebaseRef timebase,
   CMTime timebaseTime,
   CMTime immediateMasterTime)
Discussion

CMTimebaseGetTime's results will be interpolated from that anchor time.

CMTimebaseSetTime(timebase, time) is equivalent to calling CMTimebaseSetAnchorTime(timebase, time, CMSyncGetTime(CMTimebaseGetMaster(timebase))).

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseSetRate

Sets the rate of a timebase.

OSStatus  CMTimebaseSetRate(CMTimebaseRef timebase, Float64 rate );
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseSetRateAndAnchorTime

Sets the time of a timebase at a particular master time, and changes the rate at exactly that time.

OSStatus CMTimebaseSetRateAndAnchorTime(
   CMTimebaseRef timebase,
   Float64 rate,
   CMTime timebaseTime,
   CMTime immediateMasterTime)
Discussion

CMTimebaseGetTime's results will be interpolated from that anchor time as though the timebase has been running at the requested rate since that time.

CMTimebaseSetRate(timebase, rate) is approximately equivalent to calling CMTimebaseSetRateAndAnchorTime(timebase, rate, CMTimebaseGetTime(timebase), CMSyncGetTime(CMTimebaseGetMaster(timebase))), except that CMTimebaseSetRate will not generate a TimeJumped notification.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseSetTime

Sets the current time of a timebase.

OSStatus  CMTimebaseSetTime(
   CMTimebaseRef timebase,
   CMTime time );
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseSetTimerDispatchSourceNextFireTime

Sets the CMTime on the timebase's timeline at which the timer dispatch source should be fired next.

OSStatus CMTimebaseSetTimerDispatchSourceNextFireTime(
   CMTimebaseRef timebase,
   dispatch_source_t timerSource,
   CMTime fireTime,
   uint32_t flags );
Discussion

The timer source must be on the list of timers managed by the timebase. The timebase will continue to update the timer dispatch source's start time according to time jumps and effective rate changes. If fireTime is not numeric, or if the timebase is not moving, the start time will be set to DISPATCH_TIME_FOREVER.

Due to the way that timer dispatch sources are implemented, if a timer passes through a state in which it is due to fire, it may fire even if its rescheduled before the event handler is run. Clients should take care to avoid temporarily scheduling timers in the past. For example, set the timebase's rate or time before you set the timer's next fire time, if you are doing both at once. (If setting the timebase's rate or time might put the timer's fire time in the past, you may need to set the fire time to kCMTimeInvalid across the timebase change.)

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseSetTimerDispatchSourceToFireImmediately

Sets the timer dispatch source to fire immediately once, overriding any previous CMTimebaseSetTimerDispatchSourceNextFireTime call.

OSStatus CMTimebaseSetTimerDispatchSourceToFireImmediately(          CMTimebaseRef timebase,         dispatch_source_t timerSource );
Discussion

The timer source must be on the list of timers managed by the timebase. This is equivalent to calling dispatch_source_set_timer(timerSource, DISPATCH_TIME_NOW, 0, 0 ); except that the timebase gets to know that it shouldn't interfere.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseSetTimerNextFireTime

Sets the CMTime on the timebase's timeline at which the timer should next be fired.

CMTimebaseSetTimerNextFireTime(
   CMTimebaseRef timebase,
   CFRunLoopTimerRef timer,
   CMTime fireTime,
   uint32_t flags )
Discussion

The timer must be on the list of timers managed by the timebase. The timebase will continue to update the timer's "NextFireDate" according to time jumps and effective rate changes. If fireTime is not numeric, or if the timebase is not moving, the "NextFireDate" will be set to a future date.

Due to the way that CFRunLoopTimers are implemented, if a timer passes through a state in which it is due to fire, it may fire even if its rescheduled before the runloop runs again. Clients should take care to avoid temporarily scheduling timers in the past. For example, set the timebase's rate or time before you set the timer's next fire time, if you are doing both at once. (If setting the timebase's rate or time might put the timer's fire time in the past, you may need to set the fire time to kCMTimeInvalid across the timebase change.)

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebaseSetTimerToFireImmediately

Sets the timer to fire immediately once, overriding any previous CMTimebaseSetTimerNextFireTime call.

OSStatus CMTimebaseSetTimerToFireImmediately(
   CMTimebaseRef timebase,
   CFRunLoopTimerRef timer )
Discussion

The timer must be on the list of timers managed by the timebase. This is equivalent to calling CFRunLoopTimerSetNextFireDate( timer, CFAbsoluteTimeGetCurrent() ); except that the timebase gets to know that it shouldn't interfere.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

kCMTimebaseFarFutureCFAbsoluteTime

Returns a specific point of time in far, far future.

#define kCMTimebaseFarFutureCFAbsoluteTime    ((CFAbsoluteTime)kCMTimebaseVeryLongCFTimeInterval)

kCMTimebaseVeryLongCFTimeInterval

Defines a very long elapsed time in seconds.

#define kCMTimebaseVeryLongCFTimeInterval    (CFTimeInterval)(256.0 * 365.0 * 24.0 * 60.0 * 60.0)

Data Types

CMClock

A timing source object.

typedef struct OpaqueCMClock* CMClockRef;
Discussion

A clock represents a source of time information: generally, a piece of hardware that measures the passage of time. One example of a clock is the host time clock, accessible via CMClockGetHostTimeClock. It measures time using the CPU system clock, which on Mac OS X is mach_absolute_time(). Every audio device can also be considered a clock since the audio samples that it outputs or inputs each have a defined duration (eg, 1/48000 of a second for 48 kHz audio). CMClocks are read-only: they cannot be stopped or started, and the current time cannot be set. A CMClock has one primary function, CMClockGetTime, which tells what time it is now. Additionally, the CMSync infrastructure monitors relative drift between CMClocks.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMTimebase

Models a timeline under application control.

typedef struct OpaqueCMTimebase* CMTimebaseRef;
Discussion

A timebase represents a timeline that clients can control by setting the rate and time. Each timebase has either a master clock or a master timebase. The rate of the timebase is expressed relative to its master.

When a timebase has rate 0.0, its time is fixed and does not change as its master's time changes. When a timebase has rate 1.0, its time increases one second as its master's time increases by one second. When a timebase has rate 2.0, its time increases two seconds as its master's time increases by one second. When a timebase has rate -1.0, its time decreases one second as its master's time increases by one second.

If a timebase has a master timebase, the master timebase's rate is a factor in determining the timebase's effective rate. In fact, a timebase's effective rate is defined as the product of its rate, its master timebase's rate, its master timebase's master timebase's rate, and so on up to the ultimate master clock. This is the rate at which the timebase's time changes relative to the ultimate master clock.

Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

CMClockOrTimebase

Used in argument lists and function results to indicate that either may be passed

typedef CFTypeRef CMClockOrTimebaseRef;
Availability
  • Available in iOS 6.0 and later.
Declared In
CMSync.h

Constants

CMClock Error Codes

The following constants represents the errors in Core Media clock operations.

enum {
   kCMClockError_MissingRequiredParameter    = -12745,
   kCMClockError_InvalidParameter            = -12746,
   kCMClockError_AllocationFailed            = -12747,
   kCMClockError_UnsupportedOperation        = -12756,
};
Constants
kCMClockError_MissingRequiredParameter

Indicates that a required parameter is missing.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMClockError_InvalidParameter

Indicates a NULL or 0 was passed for a required parameter.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMClockError_AllocationFailed

Indicates a failed memory allocation.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMClockError_UnsupportedOperation

Indicates that the requested operation is not supported.

Available in iOS 6.0 and later.

Declared in CMSync.h.

CMTimebase error codes

The following constants represents errors in core media time base operations.

enum {
   kCMTimebaseError_MissingRequiredParameter    = -12748,
   kCMTimebaseError_InvalidParameter            = -12749,
   kCMTimebaseError_AllocationFailed            = -12750,
   kCMTimebaseError_TimerIntervalTooShort        = -12751,
   kCMTimebaseError_ReadOnly                    = -12757,
};
Constants
kCMTimebaseError_MissingRequiredParameter

Indicates that a required parameter is missing.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMTimebaseError_InvalidParameter

Indicates a NULL or 0 was passed for a required parameter.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMTimebaseError_AllocationFailed

Indicates a failed memory allocation.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMTimebaseError_TimerIntervalTooShort

Indicates that the supplied time interval is too short.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMTimebaseError_ReadOnly

Indicates that an attempt was made to modify a read-only timebase.

Available in iOS 6.0 and later.

Declared in CMSync.h.

CMSync error codes

These following constants represents error codes returned by core media synch operations.

enum {
   kCMSyncError_MissingRequiredParameter    = -12752,
   kCMSyncError_InvalidParameter            = -12753,
   kCMSyncError_AllocationFailed            = -12754,
   kCMSyncError_RateMustBeNonZero            = -12755,
};
Constants
kCMSyncError_MissingRequiredParameter

Indicates that a required parameter is missing.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMSyncError_InvalidParameter

Indicates a NULL or 0 was passed for a required parameter.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMSyncError_AllocationFailed

Indicates a failed memory allocation.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMSyncError_RateMustBeNonZero

Indicates that the rate supplied is zero.

Available in iOS 6.0 and later.

Declared in CMSync.h.

Timebase Notifications

Keys that represent time base notifications.

const CFStringRef kCMTimebaseNotification_EffectiveRateChanged
const CFStringRef kCMTimebaseNotification_TimeJumped
Constants
kCMTimebaseNotification_EffectiveRateChanged

Posted by a timebase after a change in effective rate.

Available in iOS 6.0 and later.

Declared in CMSync.h.

kCMTimebaseNotification_TimeJumped

Posted by a timebase after a discontinuous time jump.

Available in iOS 6.0 and later.

Declared in CMSync.h.