ADC Home > Reference Library > Reference > Carbon > Resource Management > Time Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Time Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

InstallTimeTask

Installs a task structure into the Time Manager task queue. (Deprecated in Mac OS X v10.4. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

OSErr InstallTimeTask (
   QElemPtr tmTaskPtr
);

Parameters
tmTaskPtr

A pointer to an original task structure to be installed in the queue.

Return Value

A result code. See “Time Manager Result Codes.”

Discussion

The InstallTimeTask function adds the Time Manager task structure specified by the tmTaskPtr parameter to the Time Manager queue. Your application should fill in the tmAddr field of the task structure and should set the tmCount field to 0. The tmTaskPtr parameter must point to an original Time Manager task structure.

With the revised and extended Time Managers, you can set the tmAddr field to NULL if you do not want a task to execute when the delay passed to the PrimeTime function expires. Also, the revised Time Manager resets the high-order bit of the qType field to 0 when you call the InsTime function.

The InstallTimeTask function, which returns a value of type OSErr, takes the place of InsTime.

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability
Declared In
Timer.h

InstallXTimeTask

Installs a task, taking advantage of the drift-free, fixed-frequency timing services of the extended Time Manager. (Deprecated in Mac OS X v10.4. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

OSErr InstallXTimeTask (
   QElemPtr tmTaskPtr
);

Parameters
tmTaskPtr

A pointer to an extended task structure to be installed in the queue.

Return Value

A result code. See “Time Manager Result Codes.”

Discussion

The InstallXTimeTask function adds the Time Manager task structure specified by tmTaskPtr to the Time Manager queue. Use InstallXTimeTask only if you wish to use the drift-free, fixed-frequency timing services of the extended Time Manager; use InstallTimeTask in all other cases. The tmTaskPtr parameter must point to an extended Time Manager task structure. Your application must fill in the tmAddr field of that task. You should set the tmWakeUp and tmReserved fields to 0 the first time you call InsXTime.

With the extended Time Manager, you can set tmAddr to NULL if you do not want a task to execute when the delay passed to PrimeTime expires. Also, InsXTime resets the high-order bit of the qType field to 0.

The InstallXTimeTask function, which returns a value of type OSErr, takes the place of InsXTime.

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability
Declared In
Timer.h

InsTime

Installs a task record into the Time Manager task queue. (Deprecated in Mac OS X v10.4. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

Not Recommended

void InsTime (
   QElemPtr tmTaskPtr
);

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability
Declared In
Timer.h

InsXTime

Installs an extended task record into the Time Manager task queue. (Deprecated in Mac OS X v10.4. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

Not Recommended

void InsXTime (
   QElemPtr tmTaskPtr
);

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability
Declared In
Timer.h

PrimeTime

Activates a task in the Time Manager queue. (Deprecated in Mac OS X v10.4. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

Not Recommended

void PrimeTime (
   QElemPtr tmTaskPtr,
   long count
);

Discussion

This function is deprecated. You should use the function PrimeTimeTask instead.

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability
Declared In
Timer.h

PrimeTimeTask

Activates a task in the Time Manager queue. (Deprecated in Mac OS X v10.4. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

OSErr PrimeTimeTask (
   QElemPtr tmTaskPtr,
   long count
);

Parameters
tmTaskPtr

A pointer to a task structure already installed in the queue.

count

The desired delay before execution of the task.

Return Value

A result code. See “Time Manager Result Codes.”

Discussion

The PrimeTimeTask function schedules the task specified by the tmAddr field of the structure pointed to by the tmTaskPtr parameter for execution after the delay specified by the count parameter has elapsed.

If the count parameter is a positive value, it is interpreted as milliseconds. If count is a negative value, it is interpreted in negated microseconds. Microsecond delays are allowable only in the revised and extended Time Managers.

The task record specified by the tmTaskPtr parameter must already be installed in the queue (by a previous call to the functions InstallTimeTask or InstallXTimeTask) before your application calls the PrimeTimeTask function. The PrimeTimeTask function returns immediately, and the specified task is executed after the specified delay has elapsed. If you call the PrimeTimeTask function with a time delay of 0, the task runs as soon as interrupts are enabled.

In the revised and extended Time Managers, the PrimeTimeTask function sets the high-order bit of the qType field to 1. In addition, any value of the count parameter that exceeds the maximum millisecond delay is reduced to the maximum. If you stop an unexpired task (by calling the function RemoveTimeTask) and then reinstall it (by calling the InstallXTimeTask function), you can continue the previous delay by calling the PrimeTimeTask function with the count parameter set to 0.

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability
Declared In
Timer.h

RemoveTimeTask

Removes a task from the Time Manager queue. (Deprecated in Mac OS X v10.4. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

OSErr RemoveTimeTask (
   QElemPtr tmTaskPtr
);

Parameters
tmTaskPtr

A pointer to a task structure to be removed from the queue.

Return Value

A result code. See “Time Manager Result Codes.”

Discussion

The RemoveTimeTask function removes the Time Manager task structure specified by the tmTaskPtr parameter from the Time Manager queue. In both the revised and extended Time Managers, if the specified task record is active (that is, if it has been activated but the specified time has not yet elapsed), the tmCount field of the task structure returns the amount of time remaining. To provide the greatest accuracy, the unused time is reported as negated microseconds if that value is small enough to fit into the tmCount field (even if the delay was originally specified in milliseconds); otherwise, the unused time is reported in positive milliseconds. If the time has already expired, the tmCount field contains 0.

In the revised and extended Time Managers, the RemoveTimeTask function sets the high-order bit of the qType field to 0.

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability
Declared In
Timer.h

RmvTime

Remove a task from the Time Manager queue. (Deprecated in Mac OS X v10.4. Use Carbon Event Loop timers or Cocoa NSTImers instead.)

Not Recommended

void RmvTime (
   QElemPtr tmTaskPtr
);

Special Considerations

Carbon Event timers and Cocoa NSTimers provide a simpler and more efficient way to handle timed or periodic tasks. For more information about using Carbon Event timers, see the timers section in Carbon Event Manager Programming Guide. For information about NSTimers, see Timer Programming Topics for Cocoa. Both Carbon event timers and NSTimers are built on top of the lower-level Core Foundation CFRunLoop timers. For CFRunLoop information, see Run Loops.

Availability
Declared In
Timer.h

< Previous PageNext Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-03-08)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.