/*---------------------------------------------------------------------------* Copyright (C) 2013-2014 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_EC_ITEM_H_ #define NN_EC_ITEM_H_ #include #include #include #include #include namespace nn { namespace ec { //! @addtogroup nn_ec_class //! @{ /*! @brief Class for handling an item. An item has an internal reference counter that is incremented and decremented in the following cases. @li When the item is added to a cart, the reference counter is incremented by 1. @li When the item is removed from a cart, the reference counter is decremented by 1. @li When the download of item metadata starts, the reference counter is incremented by 1. @li When the download of item metadata completes, the reference counter is decremented by 1. If the reference counter is larger than 1, the memory is not released even if the item object is deleted. @see Programming Manual */ class Item : public RootObject, private NonCopyable { public: NN_EC_DECLARE_ACCESSOR; NN_EC_DECLARE_IMPL; public: /*! @brief Specifies the maximum length of the item name. (128 characters * 4 bytes) */ static const size_t NAME_LENGTH_MAX = 512; /*! @brief Specifies the size of the item name. */ static const size_t NAME_SIZE = NAME_LENGTH_MAX + 1; /*! @brief Specifies the maximum length of the item description. */ static const size_t DESCRIPTION_LENGTH_MAX = 2000; /*! @brief Specifies the size of the item description. */ static const size_t DESCRIPTION_SIZE = DESCRIPTION_LENGTH_MAX + 1; /*! @brief Specifies the maximum number of attributes. */ static const u32 ATTRIBUTE_NUM_MAX = 20; /*! @brief Specifies the maximum length of the attribute name. */ static const size_t ATTRIBUTE_NAME_LENGTH_MAX = 64; /*! @brief Specifies the size of the attribute name. */ static const size_t ATTRIBUTE_NAME_SIZE = ATTRIBUTE_NAME_LENGTH_MAX + 1; /*! @brief The maximum length of the attribute value. */ static const size_t ATTRIBUTE_VALUE_LENGTH_MAX = 2000; /*! @brief The size of the attribute value. */ static const size_t ATTRIBUTE_VALUE_SIZE = ATTRIBUTE_VALUE_LENGTH_MAX + 1; public: /*! @brief Instantiates the object. */ Item(); /*! @brief Destroys the object. */ ~Item(); /*! @brief Gets the NS-UID. @return Returns the NS-UID. */ NsUniqueId GetId() const; /*! @brief Gets the name. If no name exists, an empty string is returned. @return Returns the name. */ const char* GetName() const; /*! @brief Gets the description. If no description exists, an empty string is returned. @return Returns the description. */ const char* GetDescription() const; /*! @brief Gets the release date. This function gets the New Since value set in IMAS. @n Note that the New Since date differs from the Start Date. In addition, only the date information is valid. The hour, minute, and second values are set to 0. @return Returns the release date (UTC). */ DateTime GetReleaseDate() const; /*! @brief Gets the sales status. @return Returns the sales status. */ SalesStatus GetSalesStatus() const; /*! @brief Gets the price. If no price exists, NULL is returned. @return Returns the price. */ const Price* GetPrice() const; /*! @brief Gets the icon. You must download the icon file before calling this function. @n This function returns NULL if the icon has not been downloaded. @return Returns the icon. @see DownloadIconAsync @see GetDownloadStatus */ const Icon* GetIcon() const; /*! @brief Gets a promotional image. The promotional image must be downloaded before you call this function. @n This function returns NULL if the promotional image has not been downloaded. @param[in] index Specifies the index of the promotional image. @n Index values start from 1. @return Returns the promotional image. @see DownloadPromotionImageAsync @see GetDownloadStatus */ const ImageFile* GetPromotionImage(u32 index) const; /*! @brief Gets the download status. @param[in] type Specifies the download type. @return Returns the download status. */ DownloadStatus GetDownloadStatus(DownloadType type) const; /*! @brief Gets downloadable content information. This function returns NULL if the item is not downloadable content. @return Returns downloadable content information. */ const Aoc* GetAoc() const; /*! @brief Gets an attribute. Returns NULL when the specified attribute does not exist. @param[in] pName Specifies the attribute name. @return Returns the attribute value. */ const char* GetAttribute(const char* pName) const; /*! @brief Determines whether the item has been purchased. Before using this function to check whether the item has been purchased, you must synchronize the license information with the @ref SynchronizeAocRights function. @return Returns true if purchased, or false otherwise. */ bool IsPurchased() const; /*! @brief For items with multiple pieces of content, determines whether some of the content has been purchased already. If all of the content in the item has been purchased already, the function returns false. Before using this function to check whether the item has been purchased, you must synchronize the license information with the @ref SynchronizeAocRights function. @return Returns true if a portion of the content has been purchased, or false otherwise. @see Aoc::AllowsOverlap */ bool IsPartiallyPurchased() const; /*! @brief Checks whether the item can be purchased. Before using this function to check whether the item can be purchased, you must synchronize the license information with the @ref SynchronizeAocRights function. @return The result of processing. @retval Result::IsSuccess The item can be purchased. @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) @retval ResultItemUniqueIdMismatch The unique IDs for the application and item are different. @retval ResultItemAlreadyPurchased The item has already been purchased. @retval ResultItemPartiallyPurchased Some of the content in a multiple-content item has already been purchased. @retval ResultItemUnreleased The item has not been put on sale. @retval ResultItemNotSold The item is not for sale. @see ShoppingCatalog::RetrieveAocs */ nn::Result CheckPurchasable() const; /*! @brief Checks whether the item can be redeemed. Before using this function to check whether the item can be redeemed, you must synchronize the license information with the @ref SynchronizeAocRights function. @return The result of processing. @retval Result::IsSuccess The item can be redeemed. @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) @retval ResultItemUniqueIdMismatch The unique IDs for the application and item are different. @retval ResultItemAlreadyPurchased The item has already been purchased. @retval ResultItemNotRedeemable This item is not obtained by specifying a download code. @see ShoppingCatalog::RetrieveWithDownloadCode */ nn::Result CheckRedeemable() const; /*! @brief Checks whether the item can be downloaded again. Before using this function to check whether the item can be downloaded, you must synchronize the license information with the @ref SynchronizeAocRights function. @return The result of processing. @retval Result::IsSuccess The item can be downloaded again. @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) @retval ResultItemUniqueIdMismatch The unique IDs for the application and item are different. @retval ResultItemNotPurchased The item has not been purchased. @retval ResultItemAlreadyInstalled The item has already been installed. @see ShoppingCatalog::RetrieveAocs @see DownloadCatalog::RetrieveAocs */ nn::Result CheckDownloadable() const; /*! @brief Downloads the icon. This function adds an icon download task to the download queue. @n If the download queue is full of other download tasks, it takes a while for the icon to finish downloading. Downloaded icons are stored in a memory cache and remain there even after the item is destroyed by calling the @ref ItemList::Clear function. @n If the target icon is in the memory cache, this function ignores the download order and gets the icon from the cache. If a download task for the icon of this item already exists, that task is repositioned to the beginning or end. @n If you want to increase the priority of the download, add it to the beginning of the download queue. If the download task is successfully added (not including repositioning), the reference counter is incremented by 1. @n This guarantees that the object will exist from the time the icon download starts until it completes. After the download finishes or fails, @ref DownloadCallback is called. If this function is called by an item that already has its icon downloaded, no processing takes place. @param[in] position Specifies the position at which to add the download task. @n The task is added to the end of the download queue by default. @return The result of processing. @retval Result::IsSuccess Indicates success. @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) @retval ResultOutOfMemory Insufficient memory. */ nn::Result DownloadIconAsync(QueuePosition position = QUEUE_POSITION_TAIL); /*! @brief Downloads a promotional image. For the operations of this function, see @ref DownloadIconAsync. @n This function is generally the same, except it downloads a promotional image instead of an icon. @param[in] index Specifies the index of the promotional image. @n Index values start from 1. @param[in] position Specifies the position at which to add the download task. @n The task is added to the end of the download queue by default. @return The result of processing. @retval Result::IsSuccess Indicates success. @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) @retval ResultOutOfMemory Insufficient memory. */ nn::Result DownloadPromotionImageAsync(u32 index, QueuePosition position = QUEUE_POSITION_TAIL); private: // NN_EC_IMPL; }; //! @} }} // namespace nn::ec #endif // NN_EC_ITEM_H_