Miles Sound System SDK 7.2a

AIL_register_timer

The function AIL_register_timer registers a callback function callback_fn to receive asynchronous time-slice service from a timer, and returns a handle HTIMER which may be used to start, stop, and program the function's assigned timer.

HTIMER AIL_register_timer(
  AILTIMERCB callback_fn
);

In Parameters

callback_fn: points to a timer callback function declared as the AILTIMERCB type.

Returns

A timer handle which may be used to start, stop, and control the timer.

Discussion

A timer is an API resource which, can provide periodic interrupt service to a given function at any desired frequency within the limits of system overhead. Depending upon the platform, this timer service may be implemented with threads, interrupts or system callbacks.

Since the DOS Miles Sound System must directly program the IBM PC's Programmable Interval Timer hardware, MSS makes this and other timer-related functions externally available in case the application itself requires periodic interrupt service. Up to 16 independent timer callback functions may be registered, but each sound driver which requires periodic service, including all XMIDI and digital audio drivers, will allocate one of the 16 available timer handles for its own use.

AIL_register_timer will return the value -1 if no timer handles are available.

Timer callback service will not begin until the timer's service rate is established with AIL_set_timer_period, AIL_set_timer_frequency, or AIL_set_timer_divisor, and the AIL_start_timer function is called to initiate timer service.

The timer callback function's user argument receives the value passed by the application to the AIL_set_timer_user function. It is required under both DOS and Windows.

The user argument allows a single function to be registered multiple times as a timer client, and called to handle timer processing for several different object instances. For example, an application may cast a structure pointer to type U32 and, by passing it to AIL_set_timer_user, cause the structure pointer to be passed on to that timer handle's timer service routine, which would then operate only on the structure whose pointer is passed to it by the MSS timer dispatcher. This is illustrative of the techniques MSS itself uses to manage multiple XMIDI or digital audio drivers simultaneously, and any application with an "object-oriented" design may benefit as well from the user feature.

Most MSS functions can be safely invoked from within timer callback functions. Exceptions include driver-installation or driver-shutdown functions and any other functions which may perform DOS or BIOS calls, such as AIL_init_sequence. These exceptions are noted in the descriptions of the functions involved. If in doubt about whether a particular action may safely be performed from within a timer callback function, contact RAD Game Tools for assistance.

Group: Timer Services
Related Functions: AILTIMERCB, AIL_init_sequence, AIL_register_timer, AIL_release_timer_handle, AIL_set_timer_divisor, AIL_set_timer_frequency, AIL_set_timer_period, AIL_set_timer_user, AIL_start_timer
Related Basic Types: HTIMER, MILES_PREFERENCES
Related FAQs: What's the deal with callbacks - are they threads, interrupts, system timers, or what?