# PM_[Append|Prepend|Insert]*SleepCallback

## Syntax

      #include <nitro/spi.h>

      void PM_AppendPreSleepCallback( PMSleepCallbackInfo* info );
      void PM_PrependPreSleepCallback( PMSleepCallbackInfo* info );
      void PM_InsertPreSleepCallback( PMSleepCallbackInfo* info, int priority );

      void PM_AppendPostSleepCallback( PMSleepCallbackInfo* info );
      void PM_PrependPostSleepCallback( PMSleepCallbackInfo* info );
      void PM_InsertPostSleepCallback( PMSleepCallbackInfo* info, int priority );

      typedef void (*PMSleepCallback)( void* );

## Arguments

info | Pointer to the structure that includes the information for the callback to add.
priority | Priority level. Used to determine the registration order in the callback list. Takes a value from 0 to 255.

## Return Values

None.

## Description

Registers a sleep mode callback.

The `*PreSleepCallback` functions register callbacks that are invoked immediately before the system enters sleep mode. The `*PostSleepCallback` functions register callbacks that are invoked upon recovering from sleep mode.

Callbacks are `void` functions that take a single `void*` argument.

Multiple callbacks can be registered and will be connected by a list. There are two callback lists: one that is called immediately before entering sleep mode and one that is called after recovering from sleep mode. Each callback has a priority, and is ordered in the list and run in ascending priority order. These callback functions are invoked from inside the `PM_GoSleepMode` function.

Use the `PM_SetSleepCallbackInfo` function to register the callback and callback argument in the callback information structure pointed to by info. This function registers info on the callback list. If info has already been added to the list, this function returns without doing anything. When a callback is registered on the callback list, it is ordered according to the callback priority given by priority. The value of priority can range from -255 (`PM_CALLBACK_PRIORITY_MIN`) to 255 (`PM_CALLBACK_PRIORITY_MAX`).

The `PM_AppendPreSleepCallback` function registers a callback at the end of the pre-sleep callback list, giving it a priority of 255.

The `PM_PrependPreSleepCallback` function registers a callback at the start of the pre-sleep callback list, giving it a priority of -255.

The `PM_InsertPreSleepCallback` function registers a callback in the pre-sleep callback list, giving it the specified priority.

The `PM_AppendPostSleepCallback` function registers a callback at the end of the post-sleep callback list, giving it a priority of 255.

The `PM_PrependPostSleepCallback` function registers a callback at the start of the post-sleep callback list, giving it a priority of -255.

The `PM_InsertPostSleepCallback` function registers a callback in the post-sleep callback list, giving it the specified priority.

When a callback is registered using an "`Append`" function, it is placed after any other existing callbacks that also have a priority of 255. When a callback is registered using a "`Prepend`" function, it is placed before any other existing callbacks that also have a priority of 0. When a callback is registered using an "`Insert`" function, it is placed after any other existing callbacks that have the same priority. In other words, specifying a priority of 255 to an `Insert` function causes it to behave identically to an `Append` function. However, specifying a priority of -255 to an `Insert` function does not result in the same behavior as a `Prepend` function.

Callback Removal

Call the `PM_DeletePreSleepCallback` or `PM_DeletePostSleepCallback` functions to remove callbacks from the lists.

Example

> `//---- sleep callback info
> PMSleepCallbackinfo c1info;
> PMSleepCallbackinfo c2info;
> //---- Callback before sleep mode
> void myCallback1( void* )
> {
> OS_Printf( "go to sleep mode.\n" );
> }
> //---- Callback after sleep mode
> void myCallback2( void* )
> {
> OS_Printf( "now return from sleep mode.\n" );
> }
> //---- Main
> void NitroMain( void )
> {
> :
> //---- set callback to callback info
> PM_SetSleepCallbackInfo( &c1info, myCallback1, NULL );
> PM_SetSleepCallbackInfo( &c2info, myCallback2, NULL );
> //---- set pre-callback for sleep mode
> PM_AppendPreSleepCallback( &c1info );
> //---- set post-callback for sleep mode
> PM_AppendPostSleepCallback( &c2info );
> //---- go to sleep mode
> PM_GoSleepMode(...);
> :
> }`

## See Also

`PM_Init`
`PM_GoSleepMode`
`PM_DeletePreSleepCallback`
`PM_DeletePostSleepCallback`
`PM_SetSleepCallbackInfo`

## Revision History

2008/07/15 Changed the lowest priority value available to developers from 0 to -255.
2008/06/12 Added priority settings.
2005/09/14 Changed `PM_SetSleepCallback` to `PM_SetSleepCallbackInfo`.
2005/06/02 Clarified the callback's caller.
2004/10/06 Initial version.

CONFIDENTIAL