1 /*---------------------------------------------------------------------------*
2 Project: Horizon
3 File: applet_Wrapper.h
4
5 Copyright (C)2010 Nintendo Co., Ltd. All rights reserved.
6
7 These coded instructions, statements, and computer programs contain
8 proprietary information of Nintendo of America Inc. and/or Nintendo
9 Company Ltd., and are protected by Federal copyright law. They may
10 not be disclosed to third parties or copied or duplicated in any form,
11 in whole or in part, without the prior written consent of Nintendo.
12
13 $Rev: 31695 $
14 *---------------------------------------------------------------------------*/
15
16 #ifndef NN_APPLET_CTR_APPLET_WRAPPER_H_
17 #define NN_APPLET_CTR_APPLET_WRAPPER_H_
18
19 #include <nn/os.h>
20 #include <nn/applet/CTR/applet_Parameters.h>
21 #include <nn/applet/CTR/applet_API.h>
22 #include <nn/applet/CTR/applet_Gfx.h>
23
24 namespace nn {
25 namespace applet {
26 namespace CTR {
27 namespace detail {
28
29 AppletWakeupState WaitForStarting( AppletId* pSenderId=NULL, u8* pParam=NULL, size_t paramSize=0, s32* pReadLen=NULL,
30 nn::Handle *pHandle=NULL, nn::fnd::TimeSpan span=NN_APPLET_WAIT_INFINITE );
31 bool ProcessHomeButton(void);
32 }
33 }
34 }
35 }
36
37 namespace nn {
38 namespace applet {
39 namespace CTR {
40 /*!
41 @name ホームメニュー
42 @{
43 */
44 /*!
45 @brief ホームボタンの状態を取得します。
46
47 nn::applet::CTR::HOME_BUTTON_NONE, HOME_BUTTON_SINGLE_PRESSED,
48 HOME_BUTTON_DOUBLE_PRESSED のいずれかを返します。
49
50 nn::applet::CTR::HOME_BUTTON_NONE 以外の状態のときには
51 アプリケーションで必要な処理を行った後に、
52 ProcessHomeButton() を呼んでください。
53
54 なお、通常はホームボタン処理が必要かを調べる IsExpectedToProcessHomeMenu() を
55 使ってください。そちらは、ホームボタンによるホームメニュー遷移の必要性だけではなく、
56 他のアプレットからのシーケンスによるホームボタン同様のホームメニュー遷移要求も
57 考慮しています。
58
59 この関数で取得できる値は、一旦 applet::HOME_BUTTON_NONE 以外の値になると、
60 applet::GetHomeButtonState() でクリアする(applet::HOME_BUTTON_NONEにする) まで
61 同じ値を持ち続けます。
62
63 @return 状態を返します。
64 */
65 AppletHomeButtonState GetHomeButtonState(void);
66
67 /*!
68 @brief ホームボタンの状態をクリアします。
69
70 applet::GetHomeButtonState() で取得できる値をクリアします。
71
72 また、この関数はホームボタン処理の遷移と電源ボタンやスリープとの
73 排他の終了をシステムに知らせるものでもあります。
74
75 WaitForStarting() からアプリケーションに戻ったときに、
76 そのまま終了する場合は特に呼ぶ必要はありませんが
77 アプリケーションを続行する場合には、この関数を呼んでおかなければ
78 電源ボタンやスリープといった他の遷移要素が有効になりませんので
79 注意してください。
80 */
81 void ClearHomeButtonState(void);
82
83 // 内部関数(非公開)
84 bool IsExpectedToJumpToHomeMenu(void);
85 // 内部関数(非公開)
86 void SetExpectationToJumpToHomeMenu( bool sw );
87
88 /*!
89 @brief ホームボタンの処理を行う要求があるかを調べます。
90
91 返り値が true なら、ホームボタン押しによるメニュー遷移か、
92 他のアプレットからのシーケンスでホームボタン同様のホームメニュー遷移要求が
93 あることを示します。
94
95 この場合は、速やかに ProcessHomeButton() を呼び出して
96 ホームボタン処理を行って、必要なら WaitForStarting() で待ちうけを行ってください。
97 必要かどうかは ProcessHomeButton() の返り値によります。
98
99 @return 処理要求です。
100 */
101 bool IsExpectedToProcessHomeButton(void);
102 /*!
103 @}
104 */
105
106 /*!
107 @name ホームメニュー
108 @{
109 */
110 /*!
111 @brief ホームメニュー遷移処理を行います。
112
113 この関数は IsExpectedToProcesHomeButton() でホームメニュー遷移が必要であった場合の
114 ホームメニュー遷移処理を行うためのものです。
115
116 関数名は ProcessHomeButton() ですが、ホームボタン以外にも他のアプレットからの
117 終了要求も考慮します。
118
119 返り値は、呼び出し後に WaitForStarting() で待ち受けを行う必要があるかどうかを示します。
120 true の場合は WaitForStarting() を呼んでください。
121 false の場合は呼ぶ必要はありません。(が、呼んでもウェイトせずに問題なく抜けるようになっています)
122
123 なお、前バージョンまでの互換性のために全く同じ動作をする
124 ProcessHomeButtonIfPrepared() が残されていますが、こちらの ProcessHomeButton()を
125 使うようにしてください。
126
127 @return ウェイトする必要があるかどうかを返します。
128
129 true の場合 WaitForStarting() で待ちうけが必要です。false の場合は待つ必要はありません。
130 */
ProcessHomeButton(void)131 inline bool ProcessHomeButton(void)
132 {
133 return detail::ProcessHomeButton();
134 }
135
136 // ↓この関数は古い表記です。変わりにProcessHomeButton()を使ってください。
137 // (互換性のために本バージョンでは残してあります)
ProcessHomeButtonIfPrepared(void)138 inline bool ProcessHomeButtonIfPrepared(void)
139 {
140 return detail::ProcessHomeButton();
141 }
142 /*!
143 @}
144 */
145
146 /*!
147 @name スリープ
148 @{
149 */
150 /*!
151 @brief スリープ通知状態を取得します。
152
153 nn::applet::CTR::NOTIFY_NONE, NOTIFY_SLEEP_QUERY, NOTIFY_SLEEP_ACCEPT,
154 NOTIFY_SLEEP_REJECT, NOTIFY_SLEEP_ACCEPTED, NOTIFY_AWAKE のいずれかを返します。
155
156 アプリケーションがスリープ問い合わせのコールバックに対し
157 "保留"(nn::applet::CTR::REPLY_LATER)
158 を返した後は nn::applet::CTR::NOTIFY_QUERY となります。
159 このときには、速やかに ReplySleepQuery() で nn::applet::CTR::REPLY_ACCEPT
160 か、nn::applet::CTR::REPLY_REJECT のいずれかを ReplySleepQuery() で
161 返してください。
162
163 コールバックに対し、"あるいは ReplySleepQuery() で
164 承諾"(nn::applet::CTR::REPLY_ACCEPT) を返したした後は
165 nn::applet::CTR::NOTIFY_ACCEPT となります。
166
167 コールバックに対し、"あるいは ReplySleepQuery() で
168 拒否"(nn::applet::CTR::REPLY_REJECT) を返したした後は
169 nn::applet::CTR::NOTIFY_REJECT となります。
170
171 スリープに入る直前に、nn::applet::CTR::NOTIFY_SLEEP_ACCEPTED となります。
172 ただしアプリケーションでこの値を使用することはほぼ不可能です。
173
174 スリープから起床した後は nn::applet::CTR::NOTIFY_AWAKE となります。
175
176 @return 状態を返します。
177 */
178 AppletSleepNotificationState GetSleepNotificationState(void);
179
IsExpectedToReplySleepQuery(void)180 inline bool IsExpectedToReplySleepQuery(void)
181 {
182 return (GetSleepNotificationState() == nn::applet::CTR::NOTIFY_SLEEP_QUERY)? true: false;
183 }
184
185 /*!
186 @brief スリープ通知状態をクリアします。
187
188 GetSleepNotificationState() で取得できる状態が、
189 nn::applet::CTR::NOTIFY_NONE となります。
190
191 システムでは、この状態を用いて何かの動作を行ってはいませんので、
192 アプリケーションの都合がよければどのようなタイミングで状態を変更しても
193 問題はありません。
194 */
195 void ClearSleepNotificationState(void);
196
197 /*!
198 @brief スリープ問い合わせへの返答を行います。
199
200 この関数は、SetSleepQueryCallback() で設定されるスリープ問い合わせの
201 コールバックで、アプリケーションが "保留"(nn::CTR::applet::REPLY_LATER) を
202 返した後に、改めて問い合わせの返答を行うものです。
203
204 "承諾"( nn::applet::CTR::REPLY_ACCEPT) または
205 "拒否"(nn::applet::CTR::REPLY_REJECT) のいずれかを指定してください。
206 @param[in] reply 返答
207 */
208 void ReplySleepQuery( AppletQueryReply reply );
209 /*!
210 @}
211 */
212
213
214 /*!
215 @name コールバック設定
216 @{
217 */
218 /*!
219 @brief ホームボタン検出コールバックを設定します。
220 @param[in] callback コールバック
221 @param[in] arg コールバックへの引数
222 */
223 void SetHomeButtonCallback( AppletHomeButtonCallback callback, uptr arg=0 );
224
225 /*!
226 @brief メッセージ受け取りコールバックを設定します。
227 @param[in] callback コールバック
228 @param[in] arg コールバックへの引数
229 */
230 void SetReceiveMessageCallback( AppletMessageCallback callback, uptr arg=0 );
231
232 /*!
233 @brief 電源ボタン検出コールバックを設定します。
234 @param[in] callback コールバック
235 @param[in] arg コールバックへの引数
236 */
237 void SetPowerButtonCallback( AppletPowerButtonCallback callback, uptr arg=0 );
238
239 /*! :private
240 @brief 共有メモリ要求受け取りコールバックを設定します。
241 @param[in] callback コールバック
242 @param[in] arg コールバックへの引数
243 */
244 void SetRequestMemoryCallback( AppletRequestMemoryCallback callback, uptr arg=0 );
245 /*! :private
246 @brief 共有メモリ解放コールバックを設定します。
247 @param[in] callback コールバック
248 @param[in] arg コールバックへの引数
249 */
250 void SetReleaseMemoryCallback( AppletReleaseMemoryCallback callback, uptr arg=0 );
251
252 /*! :private
253 @brief DSP スリープコールバックを設定します。
254 @param[in] callback コールバック
255 @param[in] arg コールバックへの引数
256 */
257 void SetDspSleepCallback( AppletDspSleepCallback callback, uptr arg=0 );
258 /*! :private
259 @brief DSP スリープ復帰コールバックを設定します。
260 @param[in] callback コールバック
261 @param[in] arg コールバックへの引数
262 */
263 void SetDspWakeUpCallback( AppletDspWakeUpCallback callback, uptr arg=0 );
264
265 /*!
266 @brief スリープ問い合わせコールバックを設定します。
267 @param[in] callback コールバック
268 @param[in] arg コールバックへの引数
269 */
270 void SetSleepQueryCallback( AppletSleepQueryCallback callback, uptr arg=0 );
271 /*!
272 @brief スリープキャンセルコールバックを設定します。
273 @param[in] callback コールバック
274 @param[in] arg コールバックへの引数
275 */
276 void SetSleepCanceledCallback( AppletSleepCanceledCallback callback, uptr arg=0 );
277 /*!
278 @brief スリープ復帰コールバックを設定します。
279
280 なお、スリープから復帰したあとに nngxStartLcdDisplay() で
281 LCD の復帰を行うのはアプリケーションで行う必要があります。
282
283 @param[in] callback コールバック
284 @param[in] arg コールバックへの引数
285 */
286 void SetAwakeCallback( AppletAwakeCallback callback, uptr arg=0 );
287
288 /*!
289 @brief シャットダウン通知コールバックを設定します。
290 @param[in] callback コールバック
291 @param[in] arg コールバックへの引数
292 */
293 void SetShutdownCallback( AppletShutdownCallback callback, uptr arg=0 );
294
295 /*! :private
296 @brief アプレット終了時コールバックを設定します。
297 @param[in] callback コールバック
298 @param[in] arg コールバックへの引数
299 */
300 void SetCloseAppletCallback( AppletCloseAppletCallback callback, uptr arg=0 );
301
302 /*!
303 @brief アプリケーションからホームメニュー/システムアプレット遷移時のコールバックを設定します。
304 @param[in] callback コールバック
305 @param[in] arg コールバックへの引数
306 */
307 void SetTransitionCallback( AppletTransitionCallback callback, uptr arg=0 );
308 /*!
309 @}
310 */
311
312 /*!
313 @name 動作制御
314 @{
315 */
316 /*!
317 @brief 自身の開始イベントが来るのを待ちます。
318
319 開始のイベントを受け取るまでこの関数から戻ります。
320 関数から戻る際には、AppletWakeupState 列挙型の値が返りますが、その値によって
321 以降の動作(通常再開するとか、アプリケーションを終了するとか)を決定する必要があります。
322
323 例えば、nn::applet::CTR::WAKEUP_BY_CANCEL を受け取った場合は、
324 速やかにアプリケーションを終了させる必要があります。
325
326 また電源ボタンのクリックが検出されている場合
327 (IsExpectedToProcessPowerButton() == true である場合) は
328 返り値によらずアプリケーションを終了する必要があります。
329
330 また、ホームボタン遷移と他の遷移のロックを解除するために
331 その後アプリケーションを続行する場合は ClearHomeButtonState() を呼ぶ必要があります。
332 (ClearHomeButtonState() のリファレンスを参照してください)
333
334
335 @param[out] pSenderId イベント送信元の アプレットID
336 @param[out] pParam パラメータバッファ
337 @param[in] paramSize パラメータバッファサイズ
338 @param[out] pReadLen 読み込みサイズ
339 @param[out] pHandle ハンドラ
340 @param[in] timeout タイムアウト時間
341
342 @return 起床理由を返します。
343 */
344 inline AppletWakeupState WaitForStarting( AppletId* pSenderId=NULL, u8* pParam=NULL, size_t paramSize=0, s32* pReadLen=NULL,
345 nn::Handle *pHandle=NULL, nn::fnd::TimeSpan timeout=NN_APPLET_WAIT_INFINITE )
346 {
347 return detail::WaitForStarting( pSenderId, pParam, paramSize, pReadLen, pHandle, timeout );
348 }
349 /*!
350 @}
351 */
352
353
354 bool IsAppletPreloaded( AppletId id );
355 void WaitForAppletPreloaded( AppletId id );
356
357 /*!
358 @name ライブラリアプレットのプリロードと終了
359 @{
360 */
361 /*! :private
362 @brief ライブラリアプレットのプリロードが完了したかを調べます。
363 @param[in] id ライブラリアプレットのアプレット ID
364 @return 終了していれば true となります。
365 */
IsLibraryAppletPreloaded(void)366 inline bool IsLibraryAppletPreloaded(void)
367 {
368 return IsAppletPreloaded( APPLIB_APPLET_ID );
369 }
370 /*! :private
371 @brief ライブラリアプレットのプリロードが完了するまで待ちます。
372 */
WaitForLibraryAppletPreloaded(void)373 inline void WaitForLibraryAppletPreloaded(void)
374 {
375 WaitForAppletPreloaded( APPLIB_APPLET_ID );
376 }
377 /*!
378 @}
379 */
380
381 /*!
382 @brief スリープを可能にします。
383
384 この関数でスリープを可能にしておかなければ、
385 アプリケーションがアクティブであるときに、
386 スリープ問い合わせコールバック(applet::SetSleepQueryCallback() で設定します)に
387 どのように返答しても、REPLY_REJECT(却下) 扱いとなります。
388
389 なお、applet::Enable() で applet::EnableSleep(false) を行っています。
390
391 @param[in] isSleepCheck ふたの状態をみてスリープするかどうかを表します。true ならば行います。
392 */
393 void EnableSleep( bool isSleepCheck=true );
394
395 /*!
396 @brief スリープを禁止にします。
397
398 この関数でスリープを禁止にしておくと、アプリケーションがアクティブであるときに、
399 スリープ問い合わせコールバック(applet::SetSleepQueryCallback() で設定します)に
400 どのように返答しても、REPLY_REJECT(却下) 扱いとなります。
401
402 @param[in] isReplyReject true の場合、スリープの問い合わせが来ていることを考慮して applet::ReplySleepQuery( applet::REPLY_REJECT ) を呼びます。
403 */
404 void DisableSleep( bool isReplyReject=true );
405
406 bool IsEnableSleep();
407 }
408 }
409 }
410
411 #include <nn/util/detail/util_CLibImpl.h>
nnappletGetHomeButtonState(void)412 NN_EXTERN_C inline AppletHomeButtonState nnappletGetHomeButtonState(void)
413 {
414 return nn::applet::CTR::GetHomeButtonState();
415 }
nnappletClearHomeButtonState(void)416 NN_EXTERN_C inline void nnappletClearHomeButtonState(void)
417 {
418 nn::applet::CTR::ClearHomeButtonState();
419 }
420
421 NN_EXTERN_C inline AppletWakeupState nnappletWaitForStarting( AppletId* pSenderId=NULL, u8* pParam=NULL, size_t paramSize=0, s32* pReadLen=NULL, nn::Handle *pHandle=NULL )
422 {
423 return nn::applet::CTR::WaitForStarting( pSenderId, pParam, paramSize, pReadLen, pHandle );
424 }
nnappletProcessHomeButton(void)425 NN_EXTERN_C inline bool nnappletProcessHomeButton(void)
426 {
427 return nn::applet::CTR::ProcessHomeButton();
428 }
429
430 #endif // ifndef NN_APPLET_CTR_APPLET_WRAPPER_H_
431