FtgRegisterIdleRoutine 

The FtgRegisterIdleRoutine function adds a function based on the FNIDLE19HJWII function prototype to the idle table.

Note  This function may not be supported in future versions of MAPI.

Quick Info

FtgRegisterIdleRoutine(

Parameters

pfnIdle

[in] Pointer to the idle function.

pvIdleParam

[in] Pointer to a block of memory that the idle engine should use when it calls the idle function.

priIdle

[in] Initial priority that the calling implementation requests for the idle function. Possible priorities for implementation-defined functions are greater than or less than zero, but not zero. The zero priority is reserved for a user event (for example, a mouse click or a WM_PAINT message).

Priorities greater than zero represent background tasks that have a higher priority than user events and are dispatched as part of the standard message pump loop. Priorities less than zero represent idle tasks that only run during message-pump idle time. Examples of priorities are: 1 for foreground submission, -1 for power-edit character insertion, and -3 for downloading new messages.

csecIdle

[in] Initial time value, in hundredths of a second, that the calling implementation requests to be used in specifying idle function parameters. The meaning of the initial time value varies, depending on what is passed in the iroIdle parameter. It can be:

    The minimum period of user inaction that must elapse before the MAPI idle engine calls the idle function for the first time, if the FIROWAIT flag is set in iroIdle. After this time passes, the idle engine can call the idle function as often as necessary.

    The minimum interval between calls to the idle function, if the FIROINTERVAL flag is set in iroIdle.

iroIdle

[in] Bitmask of flags used to set initial options for the idle function. The following flags can be set:

FIRODISABLED

The idle function is initially disabled when registered. The default action is to enable the idle function when FtgRegisterIdleRoutine registers it.

FIROINTERVAL

The time specified by the csecIdle parameter is the minimum interval between successive calls to the idle function.

FIROWAIT

The time specified by the csecIdle parameter is the minimum period of user inaction that must elapse before the MAPI idle engine calls the idle function for the first time. After this time passes, the idle engine can call the idle function as often as necessary.

Remarks

To later make changes to a registered idle function, a client application or service provider can call the ChangeIdleRoutine360G9L function. To remove an idle function from the idle table, a client application or provider calls the DeregisterIdleRoutineE37YQ4 function.

When all foreground tasks for the platform become idle, the idle engine calls the highest-priority idle function in the idle table that is ready to execute.

The FtgRegisterIdleRoutine function returns a function tag identifying the idle function that FtgRegisterIdleRoutine has added to the idle table. If FtgRegisterIdleRoutine cannot register the idle function for the client or service provider, for example because of memory problems, it returns NULL.