/*---------------------------------------------------------------------------* Copyright (C) 2012 Nintendo. 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. *---------------------------------------------------------------------------*/ #ifndef NN_BOSS_BOSS_NSDATA_H_ #define NN_BOSS_BOSS_NSDATA_H_ #include #include #include #include #ifdef __cplusplus namespace nn { namespace boss { /*! @addtogroup nn_boss_api @{ */ /*! @brief Class that represents data in BOSS storage. Used for accessing and deleting data and for retrieving and updating attribute values. */ class NsData { public: /*! @brief Instantiates the object. */ explicit NsData( void ); /*! @brief Instantiates the object and calls @ref Initialize. @param[in] storage Specifies the BOSS storage where the data is stored. @param[in] dataName Specifies the data name. You can omit this parameter for RawDL task data that has not been explicitly named. (That is, if the type of BOSS storage is BSKIND_RAWDL, you can specify NULL to set RAWDL_DEFAULT_FILE_NAME in the library.) */ explicit NsData( const Storage& storage, const char* dataName = NULL); /*! @brief Destroys the object. */ virtual ~NsData( void ); /*! @brief Returns whether the data exists. @return Returns whether the data exists. true indicates that it exists. */ bool Exist() const; /*! @brief Initializes the instance. @param[in] storage Specifies the BOSS storage where the data is stored. @param[in] dataName Specifies the data name. You can omit this parameter for RawDL task data that has not been explicitly named. (That is, if the type of BOSS storage is BSKIND_RAWDL, you can specify NULL to set RAWDL_DEFAULT_FILE_NAME in the library.) @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates that initialization succeeded. @retval ResultInvalidParameter Indicates that the task name is invalid. */ nn::Result Initialize(const Storage& storage, const char* dataName = NULL); /*! @brief Finalizes the class instance. Also called from the destructor. */ void Finalize( void ); /*! @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.) If the deletion is successful, records related to the applicable NS data are deleted from the NS data management file. For RawDL task data, the data itself is deleted. @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates that initialization succeeded. @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval Other Indicates an unexpected error. (For more information, see @ref nn_boss_result.) */ nn::Result Delete(void); /*! @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.) If the deletion is successful, records related to the applicable NS data are deleted from the NS data management file. For RawDL task data, the data itself is deleted. @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates that initialization succeeded. @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval Other Indicates an unexpected error. (For more information, see @ref nn_boss_result.) */ nn::Result DeleteWithHistory(void); /*! @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.) Because the data itself is deleted, it cannot be read from a different account. If the deletion is successful, records related to the applicable NS data are deleted from the NS data management file. NS data-related records are also deleted from the NS data management files of other accounts. For RawDL task data, the data itself is deleted. @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates that initialization succeeded. @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval Other Indicates an unexpected error. (For more information, see @ref nn_boss_result.) */ nn::Result DeleteRealFile(void); /*! @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.) Because the data itself is deleted, it cannot be read from a different account. If the deletion is successful, records related to the applicable NS data are deleted from the NS data management file. NS data-related records are also deleted from the NS data management files of other accounts. For RawDL task data, the data itself is deleted. @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates that initialization succeeded. @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval Other Indicates an unexpected error. (For more information, see @ref nn_boss_result.) */ nn::Result DeleteRealFileWithHistory(void); /*! @brief Loads the data into a buffer of the specified size. Up to size bytes of data are read from the file read position and copied to the region at the address specified by buffer. The file read position starts right after all of the data that has already been read. @param[out] pOut Stores the number of bytes that were actually copied. The value 0 is stored if the function reaches the end of the file. @param[in] buffer Specifies a pointer to the buffer being copied to. @param[in] size Specifies the maximum number of bytes to copy. @return Returns the result of the function. @retval Result::IsSuccess Indicates success. @retval ResultFsErrorEndOfFile Indicates that the file has already been read to the end. @retval ResultNotPermitted Indicates that the operation is not allowed. (This result applies to directories and files opened in WRITE mode.) @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval ResultNotInitialized Indicates that Open has not been called on the file. @retval ResultFail Indicates failure for an unknown reason. */ nn::Result Read(s64* pOut, void* buffer, size_t size); /*! @brief Loads the data into a buffer of the specified size. An overload of the @ref Read function without a pOut parameter. Up to size bytes of data are read from the file read position and copied to the region at the address specified by buffer. The file read position starts right after all of the data that has already been read. @param[in] buffer Specifies a pointer to the buffer being copied to. @param[in] size Specifies the maximum number of bytes to copy. @return Returns the result of the function. @retval Result::IsSuccess Indicates success. @retval ResultFsErrorEndOfFile Indicates that the file has already been read to the end. @retval ResultNotPermitted Indicates that the operation is not allowed. (This result applies to directories and files opened in WRITE mode.) @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval ResultNotInitialized Indicates that Open has not been called on the file. @retval ResultFail Indicates failure for an unknown reason. */ nn::Result Read(void* buffer, size_t size); /*! @brief Changes the read position of a file. Sets the read position to position, relative to base. @param[in] base Specifies the base from which to change the read position. @param[in] position Specifies the new read position. @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates success. @retval Other Indicates an unexpected error. (For more information, see @ref nn_boss_result.) */ nn::Result Seek(s64 position, PositionBase base); /*! @brief Gets the current read position relative to the start of the file. @return Gets the current read position counting from the start of the file. */ s64 GetPosition(void) const; /*! @brief Returns the file size. (Returns 0 (zero) if this method is executed for data that does not exist.) @return Returns the file size. */ s64 GetSize(void) const; /*! @brief Gets the time that the data was created. The time is a value that represents the number of seconds that have passed since 00:00:00 on January 1, 2000. 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. The creation time of RawDL task data, however, is based on the time in System Settings. This time is incorrect if the time in System Settings is incorrect. Returns 0 (zero) if this member function is executed for data that does not exist. @return Returns the time the data was created (as the number of seconds since 00:00:00 on January 1, 2000). (Returns 0 (zero) if this method is executed for data that does not exist.) */ s64 GetCreatedTime(void) const; /*! @brief Sets the supplemental information for the NS data. You can use this function only for NBDL task data. The application can set the supplemental information for NS data to anything. @param[in] memo Specifies the supplemental information to set. @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates that initialization succeeded. @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval ResultNoSupport Indicates not supported. This result is returned for RawDL task data. @retval Other Indicates an unexpected error. (For more information, see @ref nn_boss_result.) */ nn::Result SetMemo(u32 memo); /*! @brief Sets the supplemental information for the NS data. You can use this function only for NBDL task data. The application can set the supplemental information for NS data to anything. Returns 0 if this member function is executed on data that does not exist or on RawDL task data. @return Returns the supplemental information. The value of the supplemental information is 0 (zero) for data immediately after it is downloaded. If a value is set using the @ref SetMemo function, that value is returned. */ u32 GetMemo(void) const; /*! @brief Sets the read flag of the NS data. You can use this function only for NBDL task data. If the data has been overwritten by download data, the read flag returns false. @param[in] flag Specifies the read flag value to set. @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates that initialization succeeded. @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval ResultNoSupport Indicates not supported. This result is returned for RawDL task data. @retval Other Indicates an unexpected error. (For more information, see @ref nn_boss_result.) */ nn::Result SetReadFlag(bool flag); /*! @brief Gets the read flag of the NS data. You can use this function only for NBDL task data. Returns false if this member function is executed on data that does not exist or on RawDL task data. @return Returns the flag that indicates whether the data has been read. The value of the read flag is false for data immediately after it is downloaded. If this value was set to true by using the @ref SetReadFlag function, this function returns true. */ bool GetReadFlag(void) const; /*! @brief Sets the flag that prevents automatic deletion of the NS data. You can use this function only for NBDL task data. Files with the automatic delete protection flag set to true are excluded from the BOSS quota. When NS data storage is full, BOSS automatically deletes old files unless this flag is set. This prevents these files from being automatically deleted from BOSS. @param[in] flag Specifies the sticky flag value to set. @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates that initialization succeeded. @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval ResultNoSupport Indicates not supported. This result is returned for RawDL task data. @retval Other Indicates an unexpected error. (For more information, see @ref nn_boss_result.) */ nn::Result SetDeleteProtectionFlag(bool flag); /*! @brief Gets the flag that prevents automatic deletion of the NS data. You can use this function only for NBDL task data. Returns false if this member function is executed on data that does not exist or on RawDL task data. @return Returns the value of the automatic delete protection flag. The value of the automatic delete protection flag is false for data immediately after it is downloaded. If this value has been set to true using the @ref SetDeleteProtectionFlag function, this function returns true. */ bool GetDeleteProtectionFlag( void ) const; /*! @brief Gets the data name. @return Returns the data name. */ const char* GetName( void ) const{return m_DataName.name;} /*! @brief Gets a hash of the NS data. Currently, only SHA-1 is supported. @param[out] pHash Specifies the buffer that stores the hash value that was calculated. @param[in] hashSize Specifies the size of pHash. @param[in] hashType Specifies the type of algorithm to calculate the hash value. Currently, you can only specify SHA1. SHA1 requires a pHash of 20 bytes or greater. That size must be set in hashSize. @return Returns the result of the function. Returns one of the following Result values. @retval Result::IsSuccess Indicates success. @retval ResultNotExist Indicates that the specified data does not exist.
(To get a more detailed grasp of the cause, check whether it matches the ResultNotExist subresult. The subresults have the following meanings.
ResultFileNotExist - Indicates that the data does not exist.
ResultBossStorageNotExist - Indicates that the BOSS storage does not exist.
ResultDbNotExist - 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 BSKIND_NBDL type is the target. )
ResultRecordNotExist - Indicates that the data does not exist. (The meaning is the same as for ResultFileNotExist, but this error is returned in some cases when BOSS storage data is of the BSKIND_NBDL type. )
) @retval ResultNoSupport Indicates that this hash type is unsupported. @retval ResultNotCompleted Indicates that the pHash size (hashSize) is insufficient to receive the hash value specified by hashType. */ nn::Result GetHash(u8 pHash[], size_t hashSize, u8 hashType = HT_SHA1); protected: DataName m_DataName; Storage m_Storage; s64 m_ReadSize; }; // end of namespace class //! @} } // end of namespace boss } // end of namespace nn #endif // __cplusplus #endif /* NN_BOSS_BOSS_NSDATA_H_ */