# PM_[Append|Prepend|Insert]*ExitCallback

## 構文

      #include <twl/spi.h>

      void PM_AppendPreExitCallback( PMExitCallbackInfo info );
      void PM_PrependPreExitCallback( PMExitCallbackInfo info );
      void PM_InsertPreExitCallback( PMExitCallbackInfo info, int priority );

      void PM_AppendPostExitCallback( PMExitCallbackInfo info );
      void PM_PrependPostExitCallback( PMExitCallbackInfo info );
      void PM_InsertPostExitCallback( PMExitCallbackInfo info, int priority );

      typedef void (*PMExitCallback)( void* );

## 引数

info | 追加する終了コールバックの情報を含んだ構造体へのポインタ。
priority | 優先度。コールバックリストの登録順序を決定するのに使用します。0〜255 の値を取ります。

## 返り値

なし。

## 説明

終了コールバックを追加します。
この関数は TWLモード専用です。

ハードウェアリセットや、電源オフとなる要因(電源ボタンを押す、電池残量がなくなる)をハードウェアで検知した際に呼ばれる終了コールバックを追加します。実際にはこれらを検知するのは ARM7 側です。ARM7 からの通達で ARM9 側はここで設定したコールバックを呼びます。その後 ARM9 からARM7 に 終了する準備が出来たことを伝え、電源オフやハードウェアリセットを行います。終了コールバックは速やかに抜けるようにしなければなりません。

コールバックは `void*` 型引数を1つとる `void` 型関数です。

コールバックはリストで接続され、複数登録することが可能です。またコールバックリストは２つあり、先に処理されるリストと、後に処理されるリストの2つに分けることが出来ます。それぞれのコールバックには優先度が設定されており、リスト中で昇順に並べられており、コールバックの実行順序もそれに従います。

info は終了コールバックの情報構造体へのポインタで、この構造体に `PM_SetExitCallbackInfo()` でコールバックとコールバック引数を登録します。 本関数では、info をコールバックリストに登録します。すでに info がリストに結合されている場合、本関数では何も行わずに戻ります。priority はコールバック優先度でコールバックリストに登録する際のリスト中の順序を決定するのに用いられます。priority は -255 (`PM_CALLBACK_PRIORITY_MIN`) 〜 255 (`PM_CALLBACK_PRIORITY_MAX`) の値を取ります。

`PM_AppendPreExitCallback()` は優先度を 255 として先処理リストの後尾にコールバックを登録します。

`PM_PrependPreExitCallback()` は優先度を -255 として先処理リストの先頭にコールバックを登録します。

`PM_InsertPreExitCallback()` は指定の優先度で先処理リストにコールバックを登録します。

`PM_AppendPostExitCallback()` は優先度を 255 として後処理リストの後尾にコールバックを登録します。

`PM_PrependPostExitCallback()` は優先度を -255 として後処理リストの先頭にコールバックを登録します。

`PM_InsertPostExitCallback()` は指定の優先度で後処理リストにコールバックを登録します。

Append 関数で登録される場合、同じ優先度255のコールバックが存在した場合にはその末尾に登録されます。Prepend 関数で登録される場合、同じ優先度0 のコールバックが存在した場合にはその先頭に登録されます。Insert 関数で登録される場合、同じ優先度のコールバックが存在した場合にはその末尾に登録されます。つまり、Insert 関数で優先度を255と指定する場合と Append 関数は同じですが、Insert 関数で 優先度を -255 と指定する場合と Prepend 関数は異なります。

終了コールバックの要因

コールバック内では、どのような要因で終了コールバックが呼ばれることになったかを `PM_GetExitFactor()` で取得することが出来ます。

後処理リストに登録されたコールバックについて

このリストに登録されたコールバックは、状況によって割り込みハンドラから呼ばれたり、ユーザのスレッドから呼ばれたりします。ハードウェアリセットや電源オフとなる要因を検知して内部で最後まで自動的に処理を行う際には割り込みハンドラからの呼び出しとなりますが、`PM_SetAutoExit( FALSE )` によって自動的に処理しないようにした場合はユーザが呼び出す `PM_ReadyToExit()` の中から呼ばれます。

また、ユーザが自ら `PM_ForceToResetHardware()` や `PM_ForceToPowerOff*()` を呼び出した場合、後処理リストに登録されたコールバックが呼ばれますが、前処理リストに登録されたコールバックは呼ばれません。

コールバックの削除

リストからコールバックを削除するには `PM_DeletePreExitCallback()` または `PM_DeletePostExitCallback()` を呼んでください。

## 参照

`PM_SetExitCallbackInfo, PM_GetExitFactor`
`PM_DeletePreExitCallback``, PM_DeletePostExitCallback`
`PM_SetAutoExit, PM_ReadyToExit`

## 履歴

2008/07/15 ユーザ開放分の優先度の最低値を 0 から -255 へ変更
2008/06/11 Insert 関数を追加
2008/03/13 後処理リストのコールバックについての説明を追記
2008/02/07 初版