/*---------------------------------------------------------------------------* Project: Horizon File: boss_Task.h Copyright (C)2009 Nintendo Co., Ltd. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. $Rev: 32862 $ *---------------------------------------------------------------------------*/ #ifndef NN_BOSS_BOSS_TASK_H_ #define NN_BOSS_BOSS_TASK_H_ #include #include #include #include #include #include #include #include #include #ifdef __cplusplus namespace nn { namespace boss { /*! @brief タスクを表すクラスです。タスクの登録や登録解除、タスクの操作の際などに利用します。 */ class Task { public: /*! @brief コンストラクタです。 */ explicit Task(void); /*! @brief デストラクタです。 */ virtual ~Task(void); /*! @brief タスク登録済のタスクIDを指定して初期化します。この初期化にとってオブジェクトの再利用が可能になります。 @param[in] pTaskId タスクIDを指定します。 TaskId[TASK_ID_LENGTH] @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess 初期化に成功しました。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result Initialize(const char* pTaskId); /*! @brief タスク登録後、実行間隔を更新します。タスクの実行開始指示後でも変更が可能です。 有効な実行間隔は、1～3時間です。 @param[in] interval 実行間隔を指定します。単位は時間です。 @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess 実行間隔の更新に成功しました。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ inline nn::Result UpdateInterval(u32 interval){return UpdateIntervalWithSec(interval*60*60);} /*! @brief タスク登録後、実行間隔を更新します。単位は秒です。タスクの実行開始指示後でも変更が可能です。 @param[in] intervalSec 実行間隔を指定します。単位は秒です。 @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess 実行間隔の更新に成功しました。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result UpdateIntervalWithSec(u32 intervalSec); /*! @brief タスク登録後、消尽回数を更新します。タスクの実行開始指示後でも変更が可能です。 @param[in] count 実行回数を指定します。 @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess 消尽回数の更新に成功しました。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result UpdateCount(u32 count); /*! @brief 実行間隔を取得します。単位は時間です。タスクの実行開始指示後でも変更が可能です。 @retval 実行間隔が返ります。
*/ inline u32 GetInterval(void) { const u32 intervalSec = GetIntervalSec(); if(intervalSec > 0) { return (intervalSec / (60*60)); } else { return 0; } } /*! @brief 実行間隔を取得します。単位は秒です。 @retval 実行間隔が返ります。
*/ u32 GetIntervalSec(void); /*! @brief 消尽回数を取得します。 @return 消尽回数が返ります。
@retval U32_CANNOT_GET_DATA データが取得できません。 */ u32 GetCount(void); /*! @brief タスクのサービスステータス取得します。サービスステータスは、サーバからサービス終了の通知を検出した場合、そのステータスを確認できます。 但し、タスク登録後、一度もサーバへアクセスしていない状態では、@ref SERVICE_UNKNOWN　となりますので、ご注意ください。 @return タスクのサービスステータスが返ります。
*/ TaskServiceStatus GetServiceStatus(void); /*! @brief タスクの開始指示します。インフラ接続可能な状態になると、スケジューリングされたタスクがバックグラウンドで自動実行されます。 タスクの実行が終了すると、実行結果がエラーかどうかに関わらず、タスクの属性で指定した消尽回数が１差し引かれます。 その結果、消尽回数がゼロでない限り、タスクの属性で指定しました実行間隔時間後に、再度タスクが実行されます。 なお、消尽回数がゼロになったタスクは、内部データベースの容量の上限に達した場合、自動的に削除されることがありますので、ご注意ください。 以下の場合は、タスク開始指示を行ってもタスク実行のスケジューリングされませんので、ご注意ください。 ・消尽回数がゼロのタスク
・タスクの実行優先順位が@ref PRIORITY_STOPPED のタスク
・ペアレンタルコントロールが有効で、タスク属性でペアレンタルコントロールの解除がされていない場合
・EULA同意がされていない状態で、タスク属性でEULA同意の解除がされていない場合
・ゾーンAPからダウンロードされたポリシーリストで、タスク実行が停止された場合
・ダウンロードサービスを行うサーバからサービス停止の提示されていた場合
・管理者が全タスクを一時的に停止中の場合
良くあるケースの確認方法として、消尽回数の確認は、@ref GetCount 関数によって可能です。 ペアレンタルコントロールおよび、EULA同意については、Configツールなどで設定が可能です。 管理者が全タスクを一時的に停止中の場合は、@ref GetState 関数によって @ref TASK_PAUSED が返されますので識別が可能です。
タスク完了待機の方法は、下記のような方法があります。 ・@ref WaitFinish 関数による実行完了を待つ方法 ・最大の時間待ち時間を指定して @ref WaitFinish 関数による実行完了を待つ方法 ・@ref GetState 関数による実行完了タスク状態のポーリングも使用可能 ・@ref RegisterNewArrivalEvent 関数で登録した Event による新着イベント待ちを方法 なお、完了を検知後、@ref GetState でタスクの状態、@ref GetResult でタスクの実行結果コード、 @ref GetHttpStatusCode でhttp通信の結果コードが確認できます。 なお、その他詳細情報は、@ref GetStateDetail で取得可能です。
@return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess タスクの開始指示に成功しました。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result Start(void); /*! @brief タスクの即時開始指示します。あらかじめ、インフラ接続可能な状態にした後に呼び出す必要があります。 スケジュールされた時間に先駆けタスク実行が可能になりますので、バックグラウンドで動作するタスクを必要応じて即実行する用途に向いています。 この即時開始指示を行いますと、実行中の他のタスクがあった場合でも、そのタスクを中断して最優先で対象のタスクを実行することができます。 @ref Start との違いは、すでに実行時刻がきている状態である点、通信が中断した場合は、リジューム状態には至らず、タスク実行結果がエラーとなります。 また、注意点として、対象のタスクのみ１回だけ実行したい場合は、消尽回数を「1」に設定をしてください。 「1」以上設定しますと通常のタスクと同じように消尽回数がゼロになるまでバックグラウンドでタスクが自動実行されます。 インフラ接続可能にするためには、nn::ac::Connect()を参照ください。 @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess タスクの即時開始指示に成功しました。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result StartImmediate(void); /*! @brief タスクの実行中止指示します。一度中止指示を行ったタスクは、@ref Start で再度開始指示ができます。 中止状態のタスクは、@ref GetState 関数を呼び出すとタスクの状態として @ref TASK_STOPPED が返ります。 @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess タスクの実行中止指示に成功しました。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result Cancel(void); /*! @brief 指定時間内にタスクの完了待ちを行います。タイムアウト機能がついた、@ref WaitFinish です。 URLの更新日時が以前と同じ日時の場合、ダウンロードはされずタスクの完了にはなりませんので、ご注意ください。 @param[in] timeout タイムアウト時間を指定します。 @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess @ref TASK_DONE または、@ref TASK_ERROR でタスクが完了しました。 @retval ResultWaitFinishTaskNotDone タスクの開始指示されていないか（@ref TASK_REGISTERED 状態）、タスク実行が停止中（@ref TASK_STOPPED 状態）です。再度タスクの開始指示を行ってからタスクの完了待ちをしてください。 @retval ResultWaitFinishTimeout WaitFinish関数でタイムアウトになりました。再度完了待ちを行うなどの対応を行ってください。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result WaitFinish(const nn::fnd::TimeSpan& timeout); /*! @brief タスクの完了待ち指示します。 URLの更新日時が以前と同じ日時の場合、ダウンロードはされずタスクの完了にはなりませんので、ご注意ください。 @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess @ref TASK_DONE または、@ref TASK_ERROR でタスクが完了しました。 @retval ResultWaitFinishTaskNotDone タスクの開始指示されていないか（@ref TASK_REGISTERED 状態）、タスク実行が停止中（@ref TASK_STOPPED 状態）です。再度タスクの開始指示を行ってからタスクの完了待ちをしてください。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result WaitFinish(void); /*! @brief タスク状態の取得します。 通常、タスクの状態は、下記の①から⑤までを遷移します。 ①TASK_REGISTERED（登録済み）
②TASK_WAITING_TIMER（Start()後、時間待ち）
③TASK_WAITING（実行待ち）
④TASK_RUNNINGまたは、TASK_RETRY（実行中）
⑤TASK_DONEまたは、TASK_ERROR（実行終了状態）
特殊な状態として、TASK_PAUSED（一時停止中）、TASK_STOPPED（Cancel()による停止中）があります。 また、短時間で状態が変わる場合もあり、すべての状態を捕捉できない場合があることにご注意ください。 @param[in] acknowledge タスク実行が終わると、実行結果を確認できるように実行終了状態を保持します。 このフラグをtrueにして呼び出しますと、実行終了状態を保持を解除します。 仮に消尽回数がゼロでないタスクの場合は、前回のタスク実行完了直後に再スケジューリングされますので、 次回の返り値は、@ref TASK_WAITING_TIMER に切り替わることになります。 (省略可能) @param[out] pCount 消尽回数が返ります。 (省略可能) @param[out] pStepID タスクステップIDが返ります。(省略可能) @return タスクの状態を示すコードが返ります。
*/ TaskStateCode GetState(bool acknowledge=false, u32* pCount=NULL, u8* pStepID=NULL); /*! @brief 通信エラーコードを取得します。 下記は、よくあるhttp通信におけるレスポンスコードの例です。
200 正常なhttp通信結果です。
206 正常なhttp通信結果ですが、まだ継続データがある状態です。
401 Basic認証結果が正しくありません。Basic認証には対応していませんので、使用しないでください。
404 URLコンテンツが見つかりません。URLが正しいか、コンテンツが削除されていないか確認ください。
403 アクセスが認められていないURLが指定されました。URLが正しいか確認ください。
500 サーバ側の問題でエラーが発生しました。サーバの運用者に連絡ください。
@param[out] pCount 消尽回数が返ります。 (省略可能) @param[out] pStepID タスクステップIDが返ります。(省略可能) @return 通信エラーコードが返ります。
@retval U32_CANNOT_GET_DATA データが取得できません。 */ u32 GetHttpStatusCode(u32* pCount=NULL, u8* pStepID=NULL); /*! @brief @ref nn::boss::GetHttpStatusCode の旧名です。 互換性のために残しているものですので、新規利用は避けてください。 */ u32 GetCommErrorCode(u32* pCount=NULL, u8* pStepID=NULL) NN_ATTRIBUTE_DEPRECATED; /*! @brief タスク結果コードを取得します。 タスク結果コードについては、@ref TaskResultCode を参照してください。
よくあるタスク実行中のエラーについて
①インフラ通信が切断された場合
@ref HTTP_ERROR_RECV
@ref HTTP_ERROR_CONNECT
②サーバへの接続が失敗した場合（URLが示すサーバが見つからない場合）
@ref HTTP_ERROR_DNS
@ref HTTP_ERROR_CONNECT
③サーバへの接続が失敗した場合（HTTPSのネゴシエーションに失敗した場合）
@ref SSL_ERROR_FAILED
@ref SSL_ERROR_VERIFY_COMMON_NAME
@ref SSL_ERROR_VERIFY_ROOT_CA
@ref SSL_ERROR_VERIFY_CHAIN
@ref SSL_ERROR_VERIFY_DATE
④NSAダウンロードが失敗した場合（ NSAストレージ領域が不足した場合）
@ref NSA_ERROR_STORAGE_INSUFFICIENCY
⑤NSAダウンロードが失敗した場合（ NSAフォーマット以外か、通信エラーで内容が壊れたファイルをダウンロードした場合）
@ref NSA_ERROR_INVALID_FORMAT
@ref NSA_ERROR_VERIFY_HASH
@ref NSA_ERROR_VERIFY_SIGNATURE
@ref NSA_NSD_ERROR_VERIFY_HASH
@ref NSA_NSD_ERROR_VERIFY_SIGNATURE
@ref NSA_NSD_ERROR_INVALID_FORMAT

@param[out] pCount 消尽回数が返ります。 (省略可能) @param[out] pStepID タスクステップIDが返ります。(省略可能) @return タスク結果コードが返ります。
*/ TaskResultCode GetResult(u32* pCount=NULL, u8* pStepID=NULL); /*! @brief タスク状態を取得します。 あらかじめ、@ref TaskStatus のインスタンスを用意ください。また、このインスタンスは、128B程度のメモリを必要としますのでご注意ください。 それぞれの属性値の取得については、@ref TaskStatus のGetProperty()を参照ください。 @param[out] pStatus タスクステータスが返ります。 @param[in] acknowledge タスク実行が終わると、実行結果を確認できるように、@ref TaskStatus 内のタスクの実行終了状態を 示すコード　@ref TaskStateCode を保持します。このフラグをtrueにして呼び出しますと、 この実行終了状態の保持を解除します。 仮に消尽回数がゼロでないタスクの場合は、前回のタスク実行完了直後に再スケジューリングされますので、 次回からタスクの状態は、@ref TASK_WAITING_TIMER に切り替わることになります。 (省略可能) @param[out] pStepID タスクステップIDが返ります。 @param[in] taskStep タスクステップIDを指定します。 (省略時はカレントステップ) @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess タスク状態を取得に成功しました。 @retval ResultInvalidTaskStatus タスクステータスのポインタがNULLです。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result GetStateDetail(TaskStatus* pStatus, bool acknowledge=false, u8* pStepID=NULL, u8 taskStep=CURRENT_STEP_ID); /*! @brief @ref nn::boss::GetStateDetail の旧名です。 互換性のために残しているものですので、新規利用は避けてください。 */ nn::Result GetStatus(TaskStatus* pStatus, u8* pStepID=NULL, u8 taskStep=CURRENT_STEP_ID) NN_ATTRIBUTE_DEPRECATED; /*! @brief タスクエラー状態を取得します。 あらかじめ、@ref TaskError のインスタンスを用意ください。また、このインスタンスは、136B程度のメモリを必要としますのでご注意ください。 @param[out] pTaskError タスクエラー状態が返ります。 @param[out] pStepID タスクステップIDが返ります。 @param[in] taskStep タスクステップIDを指定します。 (省略時はカレントステップ) @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess 取得に成功しました。 @retval ResultInvalidTaskError タスクエラー情報のポインタがNULLです。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result GetError(TaskError* pTaskError, u8* pStepID=NULL, u8 taskStep=CURRENT_STEP_ID); /*! @brief 登録済のタスク情報を取得します。 あらかじめ、@ref TaskPolicy のインスタンス、@ref TaskAction のインスタンス、 @ref TaskOptionのインスタンスを用意ください。 それぞれの属性値の取得については、各クラスのGetProperty()を参照ください。 @param[out] pPolicy タスクポリシーを指定します。 @param[out] pAction タスクアクションを指定します。 @param[out] pOption タスクオプションを指定します。 @param[in] taskStep タスクステップID指定 (省略時はカレントステップ) @return 関数の実行結果を返します。以下に挙げる Result を返します。 @retval ResultSuccess 取得に成功しました。 @retval ResultInvalidTaskId タスクIDのポインタがNULLまたは０文字列です。 @retval ResultInvalidPolicy ポリシィ情報のポインタがNULLです。 @retval ResultInvalidAction タスクアクションのポインタがNULLです。 @retval ResultInvalidOption タスクオプションのポインタがNULL,またはoptionコードが範囲外です。 @retval ResultTaskNotExist 指定されたタスクIDが見つかりません。登録済であるか確認ください。 @retval ResultIpcNotSessionInitialized セッションが初期化されていないか、権限不適合です。@ref Initialize もしくは @ref InitailizePriviledged の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize もしくは @ref InitailizePriviledged を呼び出してください。 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 */ nn::Result GetInfo(TaskPolicy* pPolicy, TaskAction* pAction, TaskOption* pOption, u8 taskStep=CURRENT_STEP_ID); /*! @brief タスクIDを取得します。 @return タスクIDの文字列が返ります。
*/ char* GetTaskId(void); protected: friend class AccessConfig; TaskConfig m_Task; private: bool CheckTaskId(void); }; } // end of namespace boss } // end of namespace nn #endif // __cplusplus #endif /* NN_BOSS_BOSS_TASK_H_ */