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_EC_ITEM_H_ 14 #define NN_EC_ITEM_H_ 15 16 #include <nn/ec/ec_Types.h> 17 #include <nn/ec/ec_DateTime.h> 18 #include <nn/ec/ec_ImageFile.h> 19 #include <nn/ec/ec_Price.h> 20 #include <nn/ec/ec_Aoc.h> 21 22 namespace nn { namespace ec { 23 24 //! @addtogroup nn_ec_class 25 //! @{ 26 27 /*! 28 @brief Class for handling an item. 29 30 An item has an internal reference counter that is incremented and decremented in the following cases. 31 32 @li When the item is added to a cart, the reference counter is incremented by 1. 33 @li When the item is removed from a cart, the reference counter is decremented by 1. 34 @li When the download of item metadata starts, the reference counter is incremented by 1. 35 @li When the download of item metadata completes, the reference counter is decremented by 1. 36 37 If the reference counter is larger than 1, the memory is not released even if the item object is deleted. 38 39 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48924251">Programming Manual</a> 40 */ 41 class Item : public RootObject, private NonCopyable<Item> 42 { 43 public: 44 NN_EC_DECLARE_ACCESSOR; 45 NN_EC_DECLARE_IMPL; 46 47 public: 48 /*! 49 @brief Specifies the maximum length of the item name. (128 characters * 4 bytes) 50 */ 51 static const size_t NAME_LENGTH_MAX = 512; 52 /*! 53 @brief Specifies the size of the item name. 54 */ 55 static const size_t NAME_SIZE = NAME_LENGTH_MAX + 1; 56 /*! 57 @brief Specifies the maximum length of the item description. 58 */ 59 static const size_t DESCRIPTION_LENGTH_MAX = 2000; 60 /*! 61 @brief Specifies the size of the item description. 62 */ 63 static const size_t DESCRIPTION_SIZE = DESCRIPTION_LENGTH_MAX + 1; 64 /*! 65 @brief Specifies the maximum number of attributes. 66 */ 67 static const u32 ATTRIBUTE_NUM_MAX = 20; 68 /*! 69 @brief Specifies the maximum length of the attribute name. 70 */ 71 static const size_t ATTRIBUTE_NAME_LENGTH_MAX = 64; 72 /*! 73 @brief Specifies the size of the attribute name. 74 */ 75 static const size_t ATTRIBUTE_NAME_SIZE = ATTRIBUTE_NAME_LENGTH_MAX + 1; 76 /*! 77 @brief The maximum length of the attribute value. 78 */ 79 static const size_t ATTRIBUTE_VALUE_LENGTH_MAX = 2000; 80 /*! 81 @brief The size of the attribute value. 82 */ 83 static const size_t ATTRIBUTE_VALUE_SIZE = ATTRIBUTE_VALUE_LENGTH_MAX + 1; 84 85 public: 86 /*! 87 @brief Instantiates an object. 88 */ 89 Item(); 90 91 /*! 92 @brief Destroys the object. 93 */ 94 ~Item(); 95 96 /*! 97 @brief Gets the NS-UID. 98 99 @return Returns the NS-UID. 100 */ 101 NsUniqueId GetId() const; 102 103 /*! 104 @brief Gets the name. 105 106 If no name exists, an empty string is returned. 107 108 @return Returns the name. 109 */ 110 const char* GetName() const; 111 112 /*! 113 @brief Gets the description. 114 115 If no description exists, an empty string is returned. 116 117 @return Returns the description. 118 */ 119 const char* GetDescription() const; 120 121 /*! 122 @brief Gets the release date. 123 124 This function gets the <b>New Since</b> value set in IMAS. @n 125 Note that the <b>New Since</b> date differs from the <b>Start Date</b>. 126 127 In addition, only the date information is valid. The hour, minute, and second values are set to <tt>0</tt>. 128 129 @return Returns the release date (UTC). 130 */ 131 DateTime GetReleaseDate() const; 132 133 /*! 134 @brief Gets the sales status. 135 136 @return Returns the sales status. 137 */ 138 SalesStatus GetSalesStatus() const; 139 140 /*! 141 @brief Gets the price. 142 143 If no price exists, <tt>NULL</tt> is returned. 144 145 @return Returns the price. 146 */ 147 const Price* GetPrice() const; 148 149 /*! 150 @brief Gets the icon. 151 152 You must download the icon file before calling this function. @n 153 This function returns <tt>NULL</tt> if the icon has not been downloaded. 154 155 @return Returns the icon. 156 157 @see DownloadIconAsync 158 @see GetDownloadStatus 159 */ 160 const Icon* GetIcon() const; 161 162 /*! 163 @brief Gets a promotional image. 164 165 The promotional image must be downloaded before you call this function. @n 166 This function returns <tt>NULL</tt> if the promotional image has not been downloaded. 167 168 @param[in] index Specifies the index of the promotional image. @n 169 Index values start from <tt>1</tt>. 170 171 @return Returns the promotional image. 172 173 @see DownloadPromotionImageAsync 174 @see GetDownloadStatus 175 */ 176 const ImageFile* GetPromotionImage(u32 index) const; 177 178 /*! 179 @brief Gets the download status. 180 181 @param[in] type Specifies the download type. 182 183 @return Returns the download status. 184 */ 185 DownloadStatus GetDownloadStatus(DownloadType type) const; 186 187 /*! 188 @brief Gets downloadable content information. 189 190 This function returns <tt>NULL</tt> if the item is not downloadable content. 191 192 @return Returns downloadable content information. 193 */ 194 const Aoc* GetAoc() const; 195 196 /*! 197 @brief Gets an attribute. 198 199 Returns <tt>NULL</tt> when the specified attribute does not exist. 200 201 @param[in] pName Specifies the attribute name. 202 203 @return Returns the attribute value. 204 */ 205 const char* GetAttribute(const char* pName) const; 206 207 /*! 208 @brief Determines whether the item has been purchased. 209 210 Before using this function to check whether the item has been purchased, you must synchronize the license information with the <tt>@ref SynchronizeAocRights</tt> function. 211 212 @return Returns <tt>true</tt> if purchased, or <tt>false</tt> otherwise. 213 */ 214 bool IsPurchased() const; 215 216 /*! 217 @brief For items with multiple pieces of content, determines whether some of the content has been purchased already. 218 219 If all of the content in the item has been purchased already, the function returns <tt>false</tt>. 220 221 Before using this function to check whether the item has been purchased, you must synchronize the license information with the <tt>@ref SynchronizeAocRights</tt> function. 222 223 @return Returns <tt>true</tt> if a portion of the content has been purchased, or <tt>false</tt> otherwise. 224 225 @see Aoc::AllowsOverlap 226 */ 227 bool IsPartiallyPurchased() const; 228 229 /*! 230 @brief Checks whether the item can be purchased. 231 232 Before using this function to check whether the item can be purchased, you must synchronize the license information with the <tt>@ref SynchronizeAocRights</tt> function. 233 234 @return The result of processing. 235 236 @retval Result::IsSuccess The item can be purchased. 237 @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) 238 @retval ResultItemUniqueIdMismatch The unique IDs for the application and item are different. 239 @retval ResultItemAlreadyPurchased The item has already been purchased. 240 @retval ResultItemPartiallyPurchased Some of the content in a multiple-content item has already been purchased. 241 @retval ResultItemUnreleased The item has not been put on sale. 242 @retval ResultItemNotSold The item is not for sale. 243 244 @see ShoppingCatalog::RetrieveAocs 245 */ 246 nn::Result CheckPurchasable() const; 247 248 /*! 249 @brief Checks whether the item can be redeemed. 250 251 Before using this function to check whether the item can be redeemed, you must synchronize the license information with the <tt>@ref SynchronizeAocRights</tt> function. 252 253 @return The result of processing. 254 255 @retval Result::IsSuccess The item can be redeemed. 256 @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) 257 @retval ResultItemUniqueIdMismatch The unique IDs for the application and item are different. 258 @retval ResultItemAlreadyPurchased The item has already been purchased. 259 @retval ResultItemNotRedeemable This item is not obtained by specifying a download code. 260 261 @see ShoppingCatalog::RetrieveWithDownloadCode 262 */ 263 nn::Result CheckRedeemable() const; 264 265 /*! 266 @brief Checks whether the item can be downloaded again. 267 268 Before using this function to check whether the item can be downloaded, you must synchronize the license information with the <tt>@ref SynchronizeAocRights</tt> function. 269 270 @return The result of processing. 271 272 @retval Result::IsSuccess The item can be downloaded again. 273 @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) 274 @retval ResultItemUniqueIdMismatch The unique IDs for the application and item are different. 275 @retval ResultItemNotPurchased The item has not been purchased. 276 @retval ResultItemAlreadyInstalled The item has already been installed. 277 278 @see ShoppingCatalog::RetrieveAocs 279 @see DownloadCatalog::RetrieveAocs 280 */ 281 nn::Result CheckDownloadable() const; 282 283 /*! 284 @brief Downloads the icon. 285 286 This function adds an icon download task to the download queue. @n 287 If the download queue is full of other download tasks, it takes a while for the icon to finish downloading. 288 289 Downloaded icons are stored in a memory cache and remain there even after the item is destroyed by calling the <tt>@ref ItemList::Clear</tt> function. @n 290 If the target icon is in the memory cache, this function ignores the download order and gets the icon from the cache. 291 292 If a download task for the icon of this item already exists, that task is repositioned to the beginning or end. @n 293 If you want to increase the priority of the download, add it to the beginning of the download queue. 294 295 If the download task is successfully added (not including repositioning), the reference counter is incremented by 1. @n 296 This guarantees that the object will exist from the time the icon download starts until it completes. 297 298 After the download finishes or fails, <tt>@ref DownloadCallback</tt> is called. 299 300 If this function is called by an item that already has its icon downloaded, no processing takes place. 301 302 @param[in] position Specifies the position at which to add the download task. @n 303 The task is added to the end of the download queue by default. 304 305 @return The result of processing. 306 307 @retval Result::IsSuccess Indicates success. 308 @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) 309 @retval ResultOutOfMemory Insufficient memory. 310 */ 311 nn::Result DownloadIconAsync(QueuePosition position = QUEUE_POSITION_TAIL); 312 313 /*! 314 @brief Downloads a promotional image. 315 316 For the operations of this function, see <tt>@ref DownloadIconAsync</tt>. @n 317 This function is generally the same, except it downloads a promotional image instead of an icon. 318 319 @param[in] index Specifies the index of the promotional image. @n 320 Index values start from <tt>1</tt>. 321 @param[in] position Specifies the position at which to add the download task. @n 322 The task is added to the end of the download queue by default. 323 324 @return The result of processing. 325 326 @retval Result::IsSuccess Indicates success. 327 @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) 328 @retval ResultOutOfMemory Insufficient memory. 329 */ 330 nn::Result DownloadPromotionImageAsync(u32 index, QueuePosition position = QUEUE_POSITION_TAIL); 331 332 private: 333 // 334 NN_EC_IMPL; 335 }; 336 337 //! @} 338 339 }} // namespace nn::ec 340 341 #endif // NN_EC_ITEM_H_ 342