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_BOSSSTORAGE_H_ 14 #define NN_BOSS_BOSS_BOSSSTORAGE_H_ 15 16 #include <nn/Result.h> 17 #include <nn/boss/boss_Const.h> 18 #include <nn/boss/boss_Result.h> 19 #include <nn/boss/boss_Types.h> 20 21 #ifdef __cplusplus 22 23 namespace nn { 24 namespace boss { 25 26 /*! 27 @addtogroup nn_boss_api 28 @{ 29 */ 30 31 class NsData; 32 33 /*! 34 @brief Class that represents BOSS storage. 35 36 Used for purposes such as checking for the existence of BOSS storage, retrieving a list of the <tt>@ref NsData</tt> names in BOSS storage, and clearing the history information recorded in BOSS storage for avoiding duplicate downloads. 37 Also, when creating an instance of the <tt>@ref NsData</tt> class, you must pass the instance of this class to a constructor to specify its BOSS storage location. 38 */ 39 class Storage 40 { 41 public: 42 /*! 43 @brief Instantiates an object. The information required to use an instance is not set in this constructor. Use the <tt>@ref Initialize</tt> function to configure this class. 44 45 */ 46 explicit Storage( void ); 47 48 /*! 49 @brief Instantiates an object and calls <tt>@ref Initialize</tt>. This function targets the account that is logged in when the function is called. 50 51 @param[in] directoryName The directory. If a directory is not explicitly specified when the task is registered, the task ID is usually the same as the directory name. 52 @param[in] storageKind The storage type. If not specified, NBDL-type BOSS storage is specified by default. If you want to specify RawDL task storage, specify <tt>@ref BSKIND_RAWDL</tt>. If you want to specify <tt>DataStore</tt> task storage, specify <tt>@ref BSKIND_DATASTORE</tt>. 53 */ 54 explicit Storage( const char* directoryName, StorageKind storageKind = BSKIND_NBDL ); 55 56 /*! 57 @brief Instantiates an object and calls <tt>@ref Initialize</tt>. Specifies a slot in the target account. 58 59 @param[in] slotNo Specifies a slot in the target account. 60 @param[in] directoryName The directory. If a directory is not explicitly specified when the task is registered, the task ID is usually the same as the directory name. 61 @param[in] storageKind The storage type. If not specified, NBDL-type BOSS storage is specified by default. If you want to specify RawDL task storage, specify <tt>@ref BSKIND_RAWDL</tt>. If you want to specify <tt>DataStore</tt> task storage, specify <tt>@ref BSKIND_DATASTORE</tt>. 62 */ 63 explicit Storage( u8 slotNo, const char* directoryName, StorageKind storageKind = BSKIND_NBDL ); 64 65 /*! 66 @brief Destroys the object. 67 */ 68 virtual ~Storage( void ); 69 70 /*! 71 @brief Initializes an instance. This function targets the account that is logged in when the function is called. 72 73 @param[in] directoryName The directory. If a directory is not explicitly specified when the task is registered, the task ID is usually the same as the directory name. 74 @param[in] storageKind The storage type. If not specified, NBDL-type BOSS storage is specified by default. If you want to specify RawDL task storage, specify <tt>@ref BSKIND_RAWDL</tt>. If you want to specify <tt>DataStore</tt> task storage, specify <tt>@ref BSKIND_DATASTORE</tt>. 75 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 76 @retval Result::IsSuccess Indicates that initialization succeeded. 77 @retval ResultInvalidParameter Indicates that the task ID is invalid. 78 */ 79 nn::Result Initialize(const char* directoryName, StorageKind storageKind = BSKIND_NBDL); 80 81 /*! 82 @brief Initializes an instance. 83 84 @param[in] slotNo Specifies a slot in the target account. 85 @param[in] directoryName The directory. If a directory is not explicitly specified when the task is registered, the task ID is usually the same as the directory name. 86 @param[in] storageKind The storage type. If not specified, NBDL-type BOSS storage is specified by default. If you want to specify RawDL task storage, specify <tt>@ref BSKIND_RAWDL</tt>. If you want to specify <tt>DataStore</tt> task storage, specify <tt>@ref BSKIND_DATASTORE</tt>. 87 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 88 @retval Result::IsSuccess Indicates that initialization succeeded. 89 @retval ResultInvalidParameter Indicates that the task ID is invalid. 90 */ 91 nn::Result Initialize( u8 slotNo, const char* directoryName, StorageKind storageKind = BSKIND_NBDL); 92 93 /*! 94 @brief Finalizes the class instance. 95 96 Also called from the destructor. 97 */ 98 void Finalize( void ); 99 100 /*! 101 @brief Copy constructor. 102 */ 103 Storage( const Storage& obj ); 104 105 /*! 106 @brief Checks whether BOSS storage exists. 107 108 @return Whether BOSS storage exists. (<tt>true</tt> indicates that it exists.) 109 */ 110 bool Exist() const; 111 112 113 /*! 114 @brief Returns a list of names for NS data in the BOSS storage. 115 116 When the storage type is <tt>@ref BSKIND_NBDL</tt>, the data names are stored in the order of most recently downloaded. 117 118 @param[out] dataNameList A buffer for storing a list of data names. When the storage type is <tt>@ref BSKIND_NBDL </tt>, all of the data names can be obtained in one call by specifying a buffer with a number of elements equal to or greater than <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>. 119 @param[in] elementCount The number of elements in <var>dataNameList</var>. 120 @param[out] getDataCount Buffer where the number of data names obtained is stored. 121 @param[in] startPos Specifies the position, among all data names, of the first element of the data name to get. You can call this function repeatedly, by using a <var>dataNameList</var> with a small number of elements, to get all of the data names. If omitted, elements are obtained starting with the first element in the list of the data names. 122 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 123 @retval Result::IsSuccess Indicates that initialization succeeded. 124 @retval ResultNotExist The specified storage or directory does not exist. 125 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 126 */ 127 nn::Result GetDataList(DataName dataNameList[], u32 elementCount, u32* getDataCount, u32 startPos = 0) const; 128 129 /*! 130 @brief Returns a list of names of unread data in the BOSS storage. 131 132 When the storage type is <tt>@ref BSKIND_NBDL</tt>, the data names are stored in the order of most recently downloaded. 133 134 @param[out] dataNameList A buffer for storing a list of data names. For the <tt>BSKIND_NBDL</tt> type, you can reliably retrieve all of the data names at one time by specifying a buffer that has <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt> or more elements. 135 @param[in] elementCount The number of elements in <var>dataNameList</var>. 136 @param[out] getDataCount Buffer where the number of data names obtained is stored. 137 @param[in] startPos Specifies the position, among all data names, of the first element of the data name to get. You can call this function repeatedly, by using a <var>dataNameList</var> with a small number of elements, to get all of the data names. If omitted, elements are obtained starting with the first element in the list of the data names. 138 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 139 @retval Result::IsSuccess Indicates that initialization succeeded. 140 @retval ResultNotExist The specified directory does not exist. 141 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 142 */ 143 nn::Result GetUnreadDataList(DataName dataNameList[], u32 elementCount, u32* getDataCount, u32 startPos = 0) const; 144 145 /*! 146 @brief <b>Note:</b> Do not use this function. Use the <tt>@ref ClearAllHistories</tt> function instead. This function remains for compatibility with an earlier version of the SDK. 147 148 Clears history information that is used to avoid duplicated downloads that are stored in BOSS storage. This method can only be used for NBDL-type BOSS storage. 149 */ 150 void ClearHistory( void ); 151 152 /*! 153 @brief Clears history information recorded in BOSS storage for avoiding duplicated downloads. This method can only be used for NBDL-type BOSS storage. 154 155 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 156 @retval Result::IsSuccess Indicates that initialization succeeded. 157 @retval ResultNotExist The specified directory does not exist. 158 @retval ResultNoSupport Storage is not supported. History information is only recorded for NBDL-type BOSS storage. 159 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 160 */ 161 nn::Result ClearAllHistories( void ); 162 163 /*! 164 @brief Returns the directory name. 165 166 @return The directory name. The name specified in the constructor or the <tt>@ref Initialize</tt> function. 167 */ GetDirectoryName()168 const char* GetDirectoryName() const{return m_directoryName;} 169 170 /*! 171 @brief Returns the persistent ID for the target account. 172 173 @return Persistent ID for the target account. The ID specified in the constructor or the <tt>@ref Initialize</tt> function. 174 */ GetAccountId()175 AccountID GetAccountId() const{return m_accountId;} 176 177 /*! 178 @brief Returns the title ID for the target account. 179 180 @return Title ID for the target account. The ID specified in the constructor or the <tt>@ref Initialize</tt> function. 181 */ GetTitleId()182 TitleID GetTitleId() const{return m_titleId;} 183 184 /*! 185 @brief Returns the storage type. 186 187 @return The storage type. The ID specified in the constructor or the <tt>@ref Initialize</tt> function. 188 */ GetKind()189 StorageKind GetKind() const{return m_storageKind;} 190 191 /*! 192 @brief As a batch process, sets the already read flags for multiple data in storage to <tt>true</tt> or <tt>false</tt>. 193 194 @param[in] nsDataNames An array of data names to get the read flags for. The maximum size for a single data name is <tt>@ref NSDATA_NAME_MAX_LENGTH_WITH_NULL</tt>. The maximum number of data names is <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>. 195 @param[in] dataCount The number of data names to set. 196 @param[in] flag The flag to set. 197 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 198 @retval Result::IsSuccess Indicates success. 199 @retval Other Unexpected error. For cases such as when an error is returned from FS. 200 */ 201 nn::Result SetReadFlagToNsDatas(const DataName nsDataNames[], u32 dataCount, bool flag); 202 203 /*! 204 @brief Sets the read flag for multiple data names in storage. Specifies the flag for each data file individually. 205 206 @param[in] nsDataNames An array of data names to get the read flags for. The maximum size for a single data name is <tt>@ref NSDATA_NAME_MAX_LENGTH_WITH_NULL</tt>. The maximum number of data names is <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>. 207 @param[in] dataCount The number of data names to set. 208 @param[in] pFlags The flags to set. Each value is set according to the data in <var>nsDataNames</var>. 209 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 210 @retval Result::IsSuccess Indicates success. 211 @retval Other Unexpected error. For cases such as when an error is returned from FS. 212 */ 213 nn::Result SetReadFlagToNsDatas(const DataName nsDataNames[], u32 dataCount, bool pFlags[]); 214 215 /*! 216 @brief Gets the read flags for multiple data names in storage. 217 218 @param[in] nsDataNames An array of data names to get the read flags for. The maximum size for a single data name is <tt>@ref NSDATA_NAME_MAX_LENGTH_WITH_NULL</tt>. The maximum number of data names is <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>. 219 @param[in] dataCount The number of data names. 220 @param[in] pFlags A buffer that holds the retrieved read flags. The number of elements must be equal to or greater than <var>dataCount</var>. 221 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 222 @retval Result::IsSuccess Indicates success. 223 @retval Other Unexpected error. For cases such as when an error is returned from FS. 224 */ 225 nn::Result GetReadFlagFromNsDatas(const DataName nsDataNames[], u32 dataCount, bool pFlags[]) const; 226 227 /*! 228 @deprecated This API function is outdated. Do not use it. 229 */ 230 explicit Storage( const char* directoryName, AccountID accountId, StorageKind storageKind = BSKIND_NBDL); 231 232 /*! 233 @deprecated This API function is outdated. Do not use it. 234 */ 235 236 nn::Result Initialize(const char* directoryName, AccountID accountId, StorageKind storageKind = BSKIND_NBDL); 237 238 protected: 239 AccountID m_accountId; 240 StorageKind m_storageKind; 241 u8 padding[3]; 242 char m_directoryName[BOSSSTORAGE_DIRECTORY_NAME_MAX_LENGTH_WITH_NULL]; 243 TitleID m_titleId; 244 245 246 }; 247 248 //! @} 249 250 } // end of namespace boss 251 } // end of namespace nn 252 253 #endif // __cplusplus 254 255 #endif /* NN_BOSS_BOSS_BOSSSTORAGE_H_ */ 256