1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: boss_NsData.h 4 5 Copyright (C)2009 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: 34507 $ 14 *---------------------------------------------------------------------------*/ 15 16 #ifndef NN_BOSS_BOSS_NSDATA_H_ 17 #define NN_BOSS_BOSS_NSDATA_H_ 18 19 #include <nn/fnd/fnd_DateTime.h> 20 #include <nn/boss/boss_Const.h> 21 #include <nn/boss/boss_Result.h> 22 #include <nn/boss/boss_Types.h> 23 24 #ifdef __cplusplus 25 26 namespace nn { 27 namespace boss { 28 29 /*! 30 @brief NSデータを表すクラスです。NSデータの操作(Readなど)に利用します。 31 */ 32 class NsData 33 { 34 public: 35 static const s32 NN_BOSS_NSDATA_READ_ERROR_GET_HEADER = -1; //!< NSデータのReadNsDataエラー定義。NSデータヘッダの取得に失敗した。 36 static const s32 NN_BOSS_NSDATA_READ_ERROR_READ_DATA = -2; //!< NSデータのReadNsDataエラー定義。NSデータの読み込みに失敗した。 37 static const s32 NN_BOSS_NSDATA_READ_ERROR_IPC = -3; //!< NSデータのReadNsDataエラー定義。IPCでエラーが発生した。 38 static const s32 NN_BOSS_NSDATA_READ_ERROR_UPDATED = -4; //!< NSデータのReadNsDataエラー定義。前回のデータ取得時以降に、対象NSDのバージョンが更新された。 39 NN_PADDING4; 40 41 /*! 42 @brief コンストラクタです。 43 */ 44 explicit NsData(void); 45 46 /*! 47 @brief デストラクタです。 48 */ 49 virtual ~NsData(void); 50 51 /*! 52 @brief シリアルIDを指定してNSデータを初期化します。(一度使用したインスタンスであっても、本関数を実行することで再度使用可能となります。) 53 54 @param[in] serial シリアルIDを指定します。 55 @return 関数の実行結果を返します。以下に挙げる Result を返します。 56 @retval ResultSuccess 初期化に成功しました。 57 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 58 */ 59 nn::Result Initialize(u32 serial); 60 61 /*! 62 @brief NSDを削除します。 63 64 他のアプリがすでに削除したり、NSAダウンロード時に領域が足らなくなり、自動削除された場合など、対象のNSデータが見つからない場合がありますので、ご注意ください。 65 66 @return 関数の実行結果を返します。以下に挙げる Result を返します。 67 @retval ResultSuccess 削除に成功しました。 68 @retval ResultNsDataNotFound 指定されたNSデータが見つかりません。自動削除によって削除された可能性があります。 69 @retval ResultIpcNotSessionInitialized セッションが初期化されていません。@ref Initialize の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize を呼び出してください。 70 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 71 */ 72 nn::Result Delete(void); 73 74 /*! 75 @brief NSAヘッダ情報を読込みます。 76 77 下記のNSAヘッダ情報の種類を指定すると、相当する値が取得できます。 78 このとき、必要な領域が確保しておく必要があります。必要な領域のバイト以下であると @ref ResultInvalidNsDataGetHeadSize エラーが返ります。 79 NSD_TITLEID 64ビットのタイトルIDです。(s64) 80 NSD_FLAGS NSDのフラグです。 (bit32) 81 NSD_DATATYPE NSDのデータタイプです。 (bit32) 82 NSD_LENGTH NSDの長さです。 (s32) 83 NSD_SERIALID NSDのシリアルIDです。 (u32) 84 NSD_VERSION NSDのバージョン番号です。 (u32) 85 他のアプリがすでに削除したり、NSAダウンロード時に領域が足らなくなり、 86 自動削除された場合など、対象のNSデータが見つからない場合がありますので、ご注意ください。 87 88 @param[in] type ヘッダの要素種別を指定します。 89 @param[out] pValue ヘッダ情報の格納バッファを指定します。 90 @param[in] size バッファサイズを指定します。 91 @return 関数の実行結果を返します。以下に挙げる Result を返します。 92 @retval ResultSuccess 読込みに成功しました。 93 @retval ResultInvalidNsDataValue NSDATA格納領域のポインタがNULLです。 94 @retval ResultNsDataNotFound 指定されたNSデータが見つかりません。自動削除によって削除された可能性があります。 95 @retval ResultInvalidNsDataGetHeadSize GetHeaderInfo関数で指定したヘッダタイプに対応するサイズが一致しません。通常発生することはありませんが、何らかの異常が発生した可能性があります。 96 @retval ResultStorageAccessPermission ストレージのアクセス権がありません。拡張セーブ領域へのアクセスできません、アクセス権があるかどうか再確認をしてください。 97 @retval ResultIpcNotSessionInitialized セッションが初期化されていません。@ref Initialize の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize を呼び出してください。 98 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 99 */ 100 nn::Result GetHeaderInfo(HeaderInfoType type, void* pValue, size_t size); 101 102 /*! 103 @brief NSDのデータ部を読込みます。 104 105 あらかじめ、適当なサイズのバッファを用意した後、繰り返し呼び出すことのより、NSデータ全体を読み込むことができます。 106 終端に達したときは 0 が返りますので、終了判定が可能です。 107 アプリは、一時点で1つのNSデータしか読み込めませんが、大きなNSDを読み込んでいても、同じNSデータをアクセスしない限り、 108 他のアプリのNSデータの読み込みをブロックしません。 109 他のアプリがすでに削除したり、NSAダウンロード時に領域が足らなくなり、 110 自動削除された場合など、対象のNSデータが見つからない場合は、エラーが返りますので、ご注意ください。 111 また、稀に前回のデータ取得時以降に、対象NSDのバージョンが更新された場合、NN_BOSS_NSDATA_READ_ERROR_UPDATED が返ります。 112 この場合の対処方法は、@ref Initialize を呼び出した後、読み直しを行ってください。 113 114 @param[out] pDataBuf NSデータのバッファを指定します。 115 @param[in] bufLen NSデータのバッファ長を指定します。 116 @return 読み込んだバイト数を返します。終端に達したときは 0 を返します。 117 @retval NN_BOSS_NSDATA_READ_ERROR_GET_HEADER NSデータヘッダの取得に失敗しました。 118 @retval NN_BOSS_NSDATA_READ_ERROR_READ_DATA NSデータの読み込みに失敗しました。 119 @retval NN_BOSS_NSDATA_READ_ERROR_IPC 内部エラーが発生しました。 120 @retval NN_BOSS_NSDATA_READ_ERROR_UPDATED 前回のデータ取得時以降に、対象NSDのバージョンが更新されました。 121 */ 122 s32 ReadData(u8* pDataBuf, size_t bufLen); 123 124 /*! 125 @brief NSDの読み込み位置を変更します。 126 127 読み込み位置の変更する基準は、@ref PositionBase を参照ください。 128 129 @param[in] position 読み込み位置の変更する位置を指定します。 130 @param[in] base 読み込み位置の変更する基準を指定します。 131 @return 関数の実行結果を返します。以下に挙げる Result を返します。 132 @retval ResultSuccess 読み込み位置を変更に成功しました。 133 @retval ResultInvalidNsDataSeekPosition NSデータのシーク位置がデータサイズを超えています。 134 @retval ResultNsDataNotFound 指定されたNSデータが見つかりません。自動削除によって削除された可能性があります。 135 @retval ResultStorageAccessPermission ストレージのアクセス権がありません。拡張セーブ領域へのアクセスできません、アクセス権があるかどうか再確認をしてください。 136 @retval ResultIpcNotSessionInitialized セッションが初期化されていません。@ref Initialize の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize を呼び出してください。 137 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 138 */ 139 nn::Result SetReadDataPosition(s64 position, PositionBase base); 140 141 /*! 142 @brief NSデータの付加情報を設定します。 143 144 NSデータの付加情報は、アプリが自由に使用できる情報ですが、この付加情報は、新しいバージョンのNSデータのダウンロードがされると初期化されますので、ご注意ください。 145 146 @param[in] info 設定する付加情報を指定します。 147 @return 関数の実行結果を返します。以下に挙げる Result を返します。 148 @retval ResultSuccess 設定に成功しました。 149 @retval ResultNsDataNotFound 指定されたNSデータが見つかりません。自動削除によって削除された可能性があります。 150 @retval ResultStorageAccessPermission ストレージのアクセス権がありません。拡張セーブ領域へのアクセスできません、アクセス権があるかどうか再確認をしてください。 151 @retval ResultIpcNotSessionInitialized セッションが初期化されていません。@ref Initialize の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize を呼び出してください。 152 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 153 */ 154 nn::Result SetAdditionalInfo(u32 info); 155 156 /*! 157 @brief NSデータの付加情報を取得します。 158 159 NSデータの付加情報は、アプリが自由に使用できる情報ですが、この付加情報は、新しいバージョンのNSデータのダウンロードがされると初期化されますので、ご注意ください。 160 161 @param[in] pInfo 現在の付加情報が返ります。 162 @return 関数の実行結果を返します。以下に挙げる Result を返します。 163 @retval ResultSuccess 取得に成功しました。 164 @retval ResultInvalidNsDataInfo NSデータ追加情報を格納するポインタがNULLです。 165 @retval ResultNsDataNotFound 指定されたNSデータが見つかりません。自動削除によって削除された可能性があります。 166 @retval ResultStorageAccessPermission ストレージのアクセス権がありません。拡張セーブ領域へのアクセスできません、アクセス権があるかどうか再確認をしてください。 167 @retval ResultIpcNotSessionInitialized セッションが初期化されていません。@ref Initialize の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize を呼び出してください。 168 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 169 */ 170 nn::Result GetAdditionalInfo(u32* pInfo); 171 172 /*! 173 @brief NSデータの既読フラグを設定します。 174 175 アプリの判断で既読に設定できますが、新しいバージョンのNSデータのダウンロードがされると未読に戻りますので、ご注意ください。 176 177 @param[in] flag 設定するフラグを指定します。 178 @return 関数の実行結果を返します。以下に挙げる Result を返します。 179 @retval ResultSuccess 設定に成功しました。 180 @retval ResultNsDataNotFound 指定されたNSデータが見つかりません。自動削除によって削除された可能性があります。 181 @retval ResultStorageAccessPermission ストレージのアクセス権がありません。拡張セーブ領域へのアクセスできません、アクセス権があるかどうか再確認をしてください。 182 @retval ResultIpcNotSessionInitialized セッションが初期化されていません。@ref Initialize の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize を呼び出してください。 183 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 184 */ 185 nn::Result SetReadFlag(bool flag); 186 187 /*! 188 @brief NSデータの既読フラグを取得します。 189 190 @param[out] pFlag 取得したフラグが返ります。既読の場合、trueが返ります。 191 @return 関数の実行結果を返します。以下に挙げる Result を返します。 192 @retval ResultSuccess 取得に成功しました。 193 @retval ResultInvalidNsDataReadFlag NSデータリードフラグの格納領域のポインタがNULLです。 194 @retval ResultNsDataNotFound 指定されたNSデータが見つかりません。自動削除によって削除された可能性があります。 195 @retval ResultStorageAccessPermission ストレージのアクセス権がありません。拡張セーブ領域へのアクセスできません、アクセス権があるかどうか再確認をしてください。 196 @retval ResultIpcNotSessionInitialized セッションが初期化されていません。@ref Initialize の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize を呼び出してください。 197 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 198 */ 199 nn::Result GetReadFlag(bool* pFlag); 200 201 /*! 202 @brief NSDの更新日時を取得します。 203 204 更新日時とは、実際にダウンロードした日時ですのでご注意ください。 205 206 @param[out] pTime 更新したタイムスタンプが返ります。 207 @return 関数の実行結果を返します。以下に挙げる Result を返します。 208 @retval ResultSuccess 取得に成功しました。 209 @retval ResultInvalidNsDataTime NSデータのUPDATEタイムの格納領域のポインタがNULLです。 210 @retval ResultNsDataNotFound 指定されたNSデータが見つかりません。自動削除によって削除された可能性があります。 211 @retval ResultStorageAccessPermission ストレージのアクセス権がありません。拡張セーブ領域へのアクセスできません、アクセス権があるかどうか再確認をしてください。 212 @retval ResultIpcNotSessionInitialized セッションが初期化されていません。@ref Initialize の呼び出し前に本関数が呼び出されると、このResultが返ります。BOSSライブラリを利用する際には、必ず初めに@ref Initialize を呼び出してください。 213 @retval 上記以外 想定外のエラー(エラー内容については、@ref boss_Result.h を参照)。 214 */ 215 nn::Result GetLastUpdated(nn::fnd::DateTime* pTime); 216 217 protected: 218 bool m_Privileged; 219 NN_PADDING3; 220 u32 m_SerialId; 221 s32 m_dataSize; 222 u32 m_DataVersion; 223 AppIdType m_AppId; 224 s64 m_ReadDataPos; 225 }; 226 227 228 } // end of namespace boss 229 } // end of namespace nn 230 231 #endif // __cplusplus 232 233 #endif /* NN_BOSS_BOSS_NSDATA_H_ */ 234