ChangeIdleRoutine

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Changes some or all of the characteristics of a FNIDLE based idle routine.

Header file:	Mapiutil.h
Implemented by:	MAPI
Called by:	Client applications and service providers

VOID ChangeIdleRoutine(
  FTG ftg,
  PFNIDLE pfnIdle,
  LPVOID pvIdleParam,
  short priIdle,
  ULONG csecIdle,
  USHORT iroIdle,
  USHORT ircIdle
);

Parameters

• ftg
  [in] Function tag that identifies the idle routine.

• pfnIdle
  [in] Pointer to the idle routine.

• pvIdleParam
  [in] Pointer to a new block of memory that the calling implementation allocates for the idle routine.

• priIdle
  [in] Value representing a new priority for the idle routine. Possible priorities for implementation-defined routines are greater than or less than zero, but not zero. A value of zero is reserved for a user event such as a mouse click or a WM_PAINT message. Values greater than zero represent priorities for background tasks that have a higher priority than user events and are dispatched as part of the standard Windows message pump loop. Values less than zero represent priorities for 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] A new time, in hundredths of a second, to apply to the idle routine. 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 routine for the first time, if the FIROWAIT flag is set in iroIdle. After this time passes, the idle engine can call the idle routine as often as necessary.

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

• iroIdle
  [in] Bitmask of flags indicating new options for calling the idle routine. Exactly one of the following flags must be set:

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

  • FIROONCEONLY
    Obsolete. Do not use.

  • FIROPERBLOCK
    Obsolete. Do not use.

  • 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 routine for the first time. After this time passes, the idle engine can call the idle routine as often as necessary.

• ircIdle
  [in] Bitmask of flags used to indicate the changes to be made to the idle routine. The following flags can be set in any combination:

  • FIRCCSEC
    A change to the time associated with the idle routine, that is, a change indicated by the value passed in the csecIdle parameter.

  • FIRCIRO
    A change to the options for the idle routine, that is, a change indicated by the value passed in the iroIdle parameter.

  • FIRCPFN
    A change to the idle routine pointer, that is, a change indicated by the value passed in the pfnIdle parameter.

  • FIRCPRI
    A change to the priority of the idle routine, that is, a change indicated by the value passed in the priIdle parameter.

  • FIRCPV
    A change to the memory block of the idle routine, that is, a change indicated by the value passed in the pvIdleParam parameter.

Return Value

None.

Remarks

The following functions deal with the MAPI idle engine and with idle routines based on the FNIDLE function prototype:

Idle routine function	Usage
ChangeIdleRoutine	Changes the characteristics of a registered idle routine.
DeregisterIdleRoutine	Removes a registered idle routine from the MAPI system.
EnableIdleRoutine	Disables or re-enables a registered idle routine without removing it from the MAPI system.
FtgRegisterIdleRoutine	Adds an idle routine to the MAPI system, with or without enabling it.
MAPIDeInitIdle	Shuts down the MAPI idle engine for the calling application.
MAPIInitIdle	Initializes the MAPI idle engine for the calling application.

   ChangeIdleRoutine, DeregisterIdleRoutine, and EnableIdleRoutine take as an input parameter the function tag returned by FtgRegisterIdleRoutine.

When all foreground tasks for the platform become idle, the MAPI idle engine calls the highest priority idle routine that is ready to execute. There is no guarantee of calling order among idle routines of the same priority.