FNIDLE

The FNIDLE function prototype defines an idle routine that the MAPI idle engine calls periodically according to priority.

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

Quick Info

Header file: MAPIUTIL.H
Defined function implemented by: Client applications and service providers
Defined function called by: MAPI
Corresponding pointer type: PFNIDLE 

BOOL (STDAPICALLTYPE FNIDLE)( 
  LPVOID lpvContext  
);

Parameters

lpvContext
[in] Pointer to a block of memory that MAPI passes to the idle routine each time it calls it. This pointer is passed to the MAPI idle engine in the pvIdleParam parameter by FtgRegisterIdleRoutine. The data in the memory block can provide context for the call to the idle routine, such as which object to operate on, or the current state of a lengthy operation.

Return Values

FALSE
An idle routine with the FNIDLE prototype should always return FALSE.

Remarks

The specific functionality of the idle routine is determined by the implementing client application or service provider.

The client or provider must limit the execution time of each state of an idle routine. Every state should perform a minimum amount of coherent processing, update the current state in the context data pointed to by lpvContext, and return to the MAPI idle engine.

The client or provider must call the MAPI function MAPIInitIdle before it can register its own idle routine with a call to the FtgRegisterIdleRoutine function.

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.

See Also

Idle Routine Functions