1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 13 #ifndef NN_BOSS_BOSS_NSDATA_H_ 14 #define NN_BOSS_BOSS_NSDATA_H_ 15 16 #include <nn/boss/boss_Const.h> 17 #include <nn/boss/boss_Result.h> 18 #include <nn/boss/boss_Types.h> 19 #include <nn/boss/boss_Storage.h> 20 21 #ifdef __cplusplus 22 23 namespace nn { 24 namespace boss { 25 26 /*! 27 @addtogroup nn_boss_api 28 @{ 29 */ 30 31 /*! 32 @brief Class that represents data in BOSS storage. 33 34 Used for accessing and deleting data and for retrieving and updating attribute values. 35 */ 36 class NsData 37 { 38 public: 39 40 /*! 41 @brief Instantiates an object. 42 */ 43 explicit NsData( void ); 44 45 /*! 46 @brief Instantiates an object and calls <tt>@ref Initialize</tt>. 47 48 @param[in] storage Specifies the BOSS storage where the data is stored. 49 @param[in] dataName Specifies the data name. You can omit this parameter for <tt>RawDL</tt> task data that has not been explicitly named. (That is, if the type of BOSS storage is <tt>BSKIND_RAWDL</tt>, you can specify <tt>NULL</tt> to set <tt>RAWDL_DEFAULT_FILE_NAME</tt> in the library.) 50 */ 51 explicit NsData( const Storage& storage, const char* dataName = NULL); 52 53 /*! 54 @brief Destroys the object. 55 */ 56 virtual ~NsData( void ); 57 58 /*! 59 @brief Returns whether the data exists. 60 61 @return Returns whether the data exists. <tt>true</tt> indicates that it exists. 62 */ 63 bool Exist() const; 64 65 /*! 66 @brief Initializes an instance. 67 68 @param[in] storage Specifies the BOSS storage where the data is stored. 69 @param[in] dataName Specifies the data name. You can omit this parameter for <tt>RawDL</tt> task data that has not been explicitly named. (That is, if the type of BOSS storage is <tt>BSKIND_RAWDL</tt>, you can specify <tt>NULL</tt> to set <tt>RAWDL_DEFAULT_FILE_NAME</tt> in the library.) 70 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 71 @retval Result::IsSuccess Indicates that initialization succeeded. 72 @retval ResultInvalidParameter Indicates that the task name is invalid. 73 */ 74 nn::Result Initialize(const Storage& storage, const char* dataName = NULL); 75 76 77 /*! 78 @brief Finalizes the class instance. 79 80 Also called from the destructor. 81 */ 82 void Finalize( void ); 83 84 /*! 85 @brief Deletes data from BOSS storage. (For NBDL tasks, the data itself is not deleted, so that it can be read from a different account. The reception history for the data is preserved, so that the same data is not received again.) 86 87 If the deletion is successful, records related to the applicable NS data are deleted from the NS data management file. 88 89 For <tt>RawDL</tt> task data, the data itself is deleted. 90 91 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 92 @retval Result::IsSuccess Indicates that initialization succeeded. 93 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 94 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 95 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 96 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br /> 97 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 98 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 99 ) 100 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 101 */ 102 nn::Result Delete(void); 103 104 105 /*! 106 @brief Deletes data from BOSS storage. (For NBDL tasks, the data itself is not deleted, so it can be read from a different account. The data reception history is also deleted, so the same data is received again.) 107 108 If the deletion is successful, records related to the applicable NS data are deleted from the NS data management file. 109 110 For <tt>RawDL</tt> task data, the data itself is deleted. 111 112 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 113 @retval Result::IsSuccess Indicates that initialization succeeded. 114 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 115 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 116 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 117 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br/> 118 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 119 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 120 ) 121 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 122 */ 123 nn::Result DeleteWithHistory(void); 124 125 /*! 126 @brief Deletes data from BOSS storage. (For NBDL tasks, each item of the actual data is deleted from BOSS storage. The reception history for the data is preserved, so that the same data is not received again.) 127 128 Because the data itself is deleted, it cannot be read from a different account. 129 If the deletion is successful, records related to the applicable NS data are deleted from the NS data management file. 130 NS data-related records are also deleted from the NS data management files of other accounts. 131 132 For <tt>RawDL</tt> task data, the data itself is deleted. 133 134 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 135 @retval Result::IsSuccess Indicates that initialization succeeded. 136 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 137 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 138 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 139 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br/> 140 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 141 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 142 ) 143 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 144 */ 145 nn::Result DeleteRealFile(void); 146 147 /*! 148 @brief Deletes data from BOSS storage. (For NBDL tasks, each item of the actual data is deleted from BOSS storage. The data reception history is also deleted, so the same data is received again.) 149 150 Because the data itself is deleted, it cannot be read from a different account. 151 If the deletion is successful, records related to the applicable NS data are deleted from the NS data management file. 152 NS data-related records are also deleted from the NS data management files of other accounts. 153 154 For <tt>RawDL</tt> task data, the data itself is deleted. 155 156 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 157 @retval Result::IsSuccess Indicates that initialization succeeded. 158 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 159 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 160 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 161 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br/> 162 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 163 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 164 ) 165 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 166 */ 167 nn::Result DeleteRealFileWithHistory(void); 168 169 170 /*! 171 @brief Loads the data into a buffer of the specified size. 172 173 Up to <var>size</var> bytes of data are read from the file read position and copied to the region at the address specified by <var>buffer</var>. 174 The file read position starts right after all of the data that has already been read. 175 176 @param[out] pOut Stores the number of bytes that were actually copied. The value <tt>0</tt> is stored if the function reaches the end of the file. 177 @param[in] buffer Specifies a pointer to the buffer being copied to. 178 @param[in] size Specifies the maximum number of bytes to copy. 179 180 @return Returns the result of the function. 181 @retval Result::IsSuccess Indicates success. 182 @retval ResultFsErrorEndOfFile Indicates that the file has already been read to the end. 183 @retval ResultNotPermitted Indicates that the operation is not allowed. (This result applies to directories and files opened in <tt>WRITE</tt> mode.) 184 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 185 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 186 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 187 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br/> 188 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 189 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 190 ) 191 @retval ResultNotInitialized Indicates that <tt>Open</tt> has not been called on the file. 192 @retval ResultFail Indicates failure for an unknown reason. 193 */ 194 nn::Result Read(s64* pOut, void* buffer, size_t size); 195 196 197 /*! 198 @brief Loads the data into a buffer of the specified size. 199 200 An overload of the <tt>@ref Read</tt> function without a <var>pOut</var> parameter. 201 Up to <var>size</var> bytes of data are read from the file read position and copied to the region at the address specified by <var>buffer</var>. 202 The file read position starts right after all of the data that has already been read. 203 204 @param[in] buffer Specifies a pointer to the buffer being copied to. 205 @param[in] size Specifies the maximum number of bytes to copy. 206 207 @return Returns the result of the function. 208 @retval Result::IsSuccess Indicates success. 209 @retval ResultFsErrorEndOfFile Indicates that the file has already been read to the end. 210 @retval ResultNotPermitted Indicates that the operation is not allowed. (This result applies to directories and files opened in <tt>WRITE</tt> mode.) 211 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 212 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 213 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 214 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br/> 215 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 216 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 217 ) 218 @retval ResultNotInitialized Indicates that <tt>Open</tt> has not been called on the file. 219 @retval ResultFail Indicates failure for an unknown reason. 220 */ 221 nn::Result Read(void* buffer, size_t size); 222 223 224 /*! 225 @brief Changes the read position of a file. 226 227 Sets the read position to <var>position</var>, relative to <var>base</var>. 228 229 @param[in] base Specifies the base from which to change the read position. 230 @param[in] position Specifies the new read position. 231 232 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 233 @retval Result::IsSuccess Indicates success. 234 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 235 */ 236 nn::Result Seek(s64 position, PositionBase base); 237 238 /*! 239 @brief Gets the current read position relative to the start of the file. 240 241 @return Gets the current read position counting from the start of the file. 242 */ 243 s64 GetPosition(void) const; 244 245 /*! 246 @brief Returns the file size. 247 (Returns <tt>0</tt> (zero) if this method is executed for data that does not exist.) 248 249 @return Returns the file size. 250 */ 251 s64 GetSize(void) const; 252 253 254 /*! 255 @brief Gets the time that the data was created. 256 257 The time is a value that represents the number of seconds that have passed since 00:00:00 on January 1, 2000. 258 The creation time of NBDL task data is based on the time kept by the server on the network. It does not depend on the time in System Settings. 259 The creation time of <tt>RawDL</tt> task data, however, is based on the time in System Settings. This time is incorrect if the time in System Settings is incorrect. 260 261 Returns <tt>0</tt> (zero) if this member function is executed for data that does not exist. 262 263 @return Returns the time the data was created (as the number of seconds since 00:00:00 on January 1, 2000). (Returns <tt>0</tt> (zero) if this method is executed for data that does not exist.) 264 265 */ 266 s64 GetCreatedTime(void) const; 267 268 269 /*! 270 @brief Sets the supplemental information for the NS data. You can use this function only for NBDL task data. 271 272 The application can set the supplemental information for NS data to anything. 273 274 @param[in] memo Specifies the supplemental information to set. 275 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 276 @retval Result::IsSuccess Indicates that initialization succeeded. 277 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 278 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 279 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 280 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br/> 281 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 282 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 283 ) 284 @retval ResultNoSupport Indicates not supported. This result is returned for <tt>RawDL</tt> task data. 285 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 286 */ 287 nn::Result SetMemo(u32 memo); 288 289 290 291 /*! 292 @brief Sets the supplemental information for the NS data. You can use this function only for NBDL task data. 293 294 The application can set the supplemental information for NS data to anything. 295 Returns <tt>0</tt> if this member function is executed on data that does not exist or on <tt>RawDL</tt> task data. 296 297 @return Returns the supplemental information. The value of the supplemental information is <tt>0</tt> (zero) for data immediately after it is downloaded. If a value is set using the <tt>@ref SetMemo</tt> function, that value is returned. 298 */ 299 u32 GetMemo(void) const; 300 301 302 /*! 303 @brief Sets the read flag of the NS data. You can use this function only for NBDL task data. 304 305 If the data has been overwritten by download data, the read flag returns <tt>false</tt>. 306 307 @param[in] flag Specifies the read flag value to set. 308 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 309 @retval Result::IsSuccess Indicates that initialization succeeded. 310 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 311 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 312 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 313 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br/> 314 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 315 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 316 ) 317 @retval ResultNoSupport Indicates not supported. This result is returned for <tt>RawDL</tt> task data. 318 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 319 */ 320 nn::Result SetReadFlag(bool flag); 321 322 /*! 323 @brief Gets the read flag of the NS data. You can use this function only for NBDL task data. 324 325 Returns <tt>false</tt> if this member function is executed on data that does not exist or on <tt>RawDL</tt> task data. 326 327 @return Returns the flag that indicates whether the data has been read. The value of the read flag is <tt>false</tt> for data immediately after it is downloaded. If this value was set to <tt>true</tt> by using the <tt>@ref SetReadFlag</tt> function, this function returns <tt>true</tt>. 328 */ 329 bool GetReadFlag(void) const; 330 331 332 /*! 333 @brief Sets the flag that prevents automatic deletion of the NS data. You can use this function only for NBDL task data. 334 335 Files with the automatic delete protection flag set to <tt>true</tt> are excluded from the BOSS quota. When NS data storage is full, BOSS automatically deletes old files unless this flag is set. 336 This prevents these files from being automatically deleted from BOSS. 337 338 @param[in] flag Specifies the sticky flag value to set. 339 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 340 @retval Result::IsSuccess Indicates that initialization succeeded. 341 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 342 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 343 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 344 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br/> 345 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 346 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 347 ) 348 @retval ResultNoSupport Indicates not supported. This result is returned for <tt>RawDL</tt> task data. 349 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 350 */ 351 nn::Result SetDeleteProtectionFlag(bool flag); 352 353 354 /*! 355 @brief Gets the flag that prevents automatic deletion of the NS data. You can use this function only for NBDL task data. 356 357 Returns <tt>false</tt> if this member function is executed on data that does not exist or on <tt>RawDL</tt> task data. 358 359 @return Returns the value of the automatic delete protection flag. The value of the automatic delete protection flag is <tt>false</tt> for data immediately after it is downloaded. If this value has been set to <tt>true</tt> using the <tt>@ref SetDeleteProtectionFlag</tt> function, this function returns <tt>true</tt>. 360 */ 361 bool GetDeleteProtectionFlag( void ) const; 362 363 /*! 364 @brief Gets the data name. 365 366 @return Returns the data name. 367 */ GetName(void)368 const char* GetName( void ) const{return m_DataName.name;} 369 370 /*! 371 @brief Gets a hash of the NS data. 372 373 Currently, only SHA-1 is supported. 374 375 @param[out] pHash Specifies the buffer that stores the hash value that was calculated. 376 @param[in] hashSize Specifies the size of <var>pHash</var>. 377 @param[in] hashType Specifies the type of algorithm to calculate the hash value. Currently, you can only specify <tt>SHA1</tt>. <tt>SHA1</tt> requires a <var>pHash</var> of 20 bytes or greater. That size must be set in <var>hashSize</var>. 378 379 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 380 @retval Result::IsSuccess Indicates success. 381 @retval ResultNotExist Indicates that the specified data does not exist. <br/> 382 (To get a more detailed grasp of the cause, check whether it matches the <tt>ResultNotExist</tt> subresult. The subresults have the following meanings. <br/> 383 <tt>ResultFileNotExist</tt> - Indicates that the data does not exist. <br/> 384 <tt>ResultBossStorageNotExist</tt> - Indicates that the BOSS storage does not exist. <br/> 385 <tt>ResultDbNotExist</tt> - Indicates that the database file managing the information for the data does not exist. (This result can occur only if the BOSS storage data of the <tt>BSKIND_NBDL</tt> type is the target. ) <br /> 386 <tt>ResultRecordNotExist</tt> - Indicates that the data does not exist. (The meaning is the same as for <tt>ResultFileNotExist</tt>, but this error is returned in some cases when BOSS storage data is of the <tt>BSKIND_NBDL</tt> type. ) <br /> 387 ) 388 @retval ResultNoSupport Indicates that this hash type is unsupported. 389 @retval ResultNotCompleted Indicates that the <var>pHash</var> size (<var>hashSize</var>) is insufficient to receive the hash value specified by <var>hashType</var>. 390 */ 391 nn::Result GetHash(u8 pHash[], size_t hashSize, u8 hashType = HT_SHA1); 392 393 protected: 394 DataName m_DataName; 395 Storage m_Storage; 396 s64 m_ReadSize; 397 398 }; // end of namespace class 399 400 //! @} 401 402 } // end of namespace boss 403 } // end of namespace nn 404 405 #endif // __cplusplus 406 407 #endif /* NN_BOSS_BOSS_NSDATA_H_ */ 408