1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) 2012 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_NBDLDATALIST_H_ 14 #define NN_BOSS_BOSS_NBDLDATALIST_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_NetTaskSetting.h> 20 #include <nn/boss/boss_Task.h> 21 22 #ifdef __cplusplus 23 24 namespace nn { 25 namespace boss { 26 27 /*! 28 @addtogroup nn_boss_api 29 @{ 30 */ 31 32 /*! 33 @brief Class that bears an NBDL data list. 34 */ 35 class NbdlDataList : public NetTaskSetting 36 { 37 friend class AlmightyNbdlDataList; 38 39 public: 40 static const u32 DOWNLOAD_DEFAULT_TIMEOUT_SEC = 60; //!< Standard timeout for <tt>NbdlDataList::Download</tt> in seconds. 41 42 static const u32 ATTRIBUTE_MAX_LENGTH_WITH_NULL = 10; //!< Maximum length of the attribute value for data attributes (including the <tt>NULL</tt> terminating character). 43 static const u32 DESCRIPTION_MAX_LENGTH_WITH_NULL = 512; //!< Maximum length of the description value for data attributes (including the <tt>NULL</tt> terminating character). 44 45 /*! 46 @brief Enumerates the type of data. The value of the type of a data attribute is one of the enumerands in this type. 47 */ 48 enum DataType 49 { 50 DATATYPE_APPDATA = 0, //!< Extra Data 51 DATATYPE_MESSAGE = 1, //!< Notifications 52 }; 53 54 /*! 55 @brief Stores the attribute values of each data item. The NBDL data list is retrieved as an array of this structure. 56 57 The size is 584 bytes. 58 */ 59 struct DataAttributes 60 { 61 u64 size; //!< Data size. 62 char name[NSDATA_NAME_MAX_LENGTH_WITH_NULL]; //!< Data name. 63 char attribute1[ATTRIBUTE_MAX_LENGTH_WITH_NULL]; //!< Attribute 1 64 char attribute2[ATTRIBUTE_MAX_LENGTH_WITH_NULL]; //!< Attribute 2 65 char attribute3[ATTRIBUTE_MAX_LENGTH_WITH_NULL]; //!< Attribute 3 66 u16 type; //!< Data type. 67 char description[DESCRIPTION_MAX_LENGTH_WITH_NULL]; //!< Description 68 }; 69 70 static const u32 OPTION_GET_MESSAGE_ATTRIBUTE_TOGETHER = 0x00000001; //!< By default, only the data attributes of application data are retrieved, but this option can also be used to retrieve the data attributes of notification data. 71 72 73 /*! 74 @brief Instantiates the object. 75 */ 76 explicit NbdlDataList(void); 77 78 /*! 79 @brief Destroys the object. 80 */ 81 virtual ~NbdlDataList(void); 82 83 /*! 84 @brief Downloads an NBDL data list. 85 86 NBDL data lists run as dedicated immediate-execution tasks. <br/> 87 A different dedicated immediate-execution task cannot be registered while an NBDL data list is downloading. <br/> 88 89 This function communicates with the server and might take several seconds to complete. <br/> 90 You can cancel this function using <tt>@ref Cancel</tt>. <br/> 91 92 @param[out] pDataAttributes Pointer to the buffer that stores the NBDL data list. The maximum size of the data list is <tt>sizeof( @ref DataAttributes) * @ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>. You can always retrieve the data list if you set a buffer size of at least this amount. If the size is too small, this function downloads the amount of entries that fit in the buffer. 93 @param[in] dataAttributesSize The size of <span class="argument">pDataAttributes</span>. 94 @param[out] pDataCount The number of data items included in the NBDL data list. If the entire data list could not be retrieved because <span class="argument">pDataAttributes</span> was not large enough, this value represents the number of data items included in the data list downloaded from the server, not the number of data items stored in <span class="argument">pDataAttributes</span>. 95 @param[in] bossCode The BOSS code. (The code that is assigned to each application that uses NBDL. You can check this code from the BOSS data server management tool after your application for use of NBDL tasks has been approved by Nintendo.)) 96 @param[in] targetTaskId ID of the task for which to get the NBDL data list. 97 @param[in] directoryName The name of the directory that stores the data. Normally, you can omit this setting. When omitted, the task ID is used for the directory name. The <tt>@ref Storage</tt> class uses this directory name when retrieving a list of files. If you omit the directory name, specify the task ID in the <tt>@ref Storage</tt> class. (There are special cases where this argument must be specified explicitly. For more information, see the BOSS Programming Manual.) 98 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 99 @retval Result::IsSuccess Indicates successful download. 100 @retval ResultFail Indicates that the download failed. You can get details about the failure by calling <tt>@ref GetLastDownloadResult</tt>. 101 @retval ResultNotCompleted Specifies that the download timed out. 102 @retval ResultCanceled Specifies that the download was canceled. 103 @retval Other Specifies that an error occurred before the download began. (See <tt>@ref nn_boss_result</tt> for the error.) 104 */ 105 nn::Result Download(DataAttributes pDataAttributes[NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY], size_t dataAttributesSize, u32* pDataCount, const char* bossCode, const char* targetTaskId, const char* directoryName = NULL); 106 107 /*! 108 @brief Downloads the NBDL data list for a specific account. 109 110 NBDL data lists run as dedicated immediate-execution tasks. <br/> 111 A different dedicated immediate-execution task cannot be registered while an NBDL data list is downloading. <br/> 112 113 This function communicates with the server and might take several seconds to complete. <br/> 114 You can cancel this function using <tt>@ref Cancel</tt>. <br/> 115 116 @param[out] pDataAttributes Pointer to the buffer that stores the NBDL data list. The maximum size of the data list is <tt>sizeof( @ref DataAttributes) * @ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>. You can always retrieve the data list if you set a buffer size of at least this amount. If the size is too small, this function downloads the amount of entries that fit in the buffer. 117 @param[in] dataAttributesSize The size of <span class="argument">pDataAttributes</span>. 118 @param[out] pDataCount The number of data items included in the NBDL data list. If the entire data list could not be retrieved because <span class="argument">pDataAttributes</span> was not large enough, this value represents the number of data items included in the data list downloaded from the server, not the number of data items stored in <span class="argument">pDataAttributes</span>. 119 @param[in] bossCode The BOSS code. (The code that is assigned to each application that uses NBDL. You can check this code from the BOSS data server management tool after your application for use of NBDL tasks has been approved by Nintendo.)) 120 @param[in] slotNo Slot number of the target account. 121 @param[in] targetTaskId ID of the task for which to get the NBDL data list. 122 @param[in] directoryName The name of the directory that stores the data. Normally, you can omit this setting. When omitted, the task ID is used for the directory name. The <tt>@ref Storage</tt> class uses this directory name when retrieving a list of files. If you omit the directory name, specify the task ID in the <tt>@ref Storage</tt> class. (There are special cases where this argument must be specified explicitly. For more information, see the BOSS Programming Manual.) 123 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 124 @retval Result::IsSuccess Indicates successful download. 125 @retval ResultFail Indicates that the download failed. You can get details about the failure by calling <tt>@ref GetLastDownloadResult</tt>. 126 @retval ResultNotCompleted Specifies that the download timed out. 127 @retval ResultCanceled Specifies that the download was canceled. 128 @retval Other Specifies that an error occurred before the download began. (See <tt>@ref nn_boss_result</tt> for the error.) 129 */ 130 nn::Result Download(DataAttributes pDataAttributes[NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY], size_t dataAttributesSize, u32* pDataCount, const char* bossCode, u8 slotNo, const char* targetTaskId, const char* directoryName = NULL); 131 132 /*! 133 @brief Cancels the download of an NBDL data list. 134 135 Use this function when you want to cancel <tt>@ref NbdlDataList::Download</tt>, which is a blocking function. 136 */ 137 void Cancel(void); 138 139 /*! 140 @brief Gets details of the execution results for <tt>@ref NbdlDataList::Download</tt>. 141 142 You can get the execution results for the last time <tt>@ref NbdlDataList::Download</tt> was executed. 143 144 @return Returns the execution results for the last time <tt>@ref NbdlDataList::Download</tt> was executed. 145 */ 146 TaskResult GetLastDownloadResult(void); 147 148 /*! 149 @brief Sets the name of the file to download. Use this function to retrieve the attribute information only for a specific file. 150 151 @param[in] fileName Name of the file to download. The maximum length of the strings that can be specified for filenames (including the terminating null character) is <tt>@ref NSDATA_NAME_MAX_LENGTH_WITH_NULL</tt>. 152 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 153 @retval Result::IsSuccess Indicates successful retrieval. 154 @retval ResultInvalidParameter A parameter is invalid. (For example, <span class="argument">fileName</span> is <tt>NULL</tt>.) 155 */ 156 nn::Result SetFileName(const char* fileName); 157 158 /*! 159 @brief Sets the language code of data to include in the NBDL data list. 160 161 By default, the NBDL data list includes data that matches the language in System Settings, but you can download a data list for a specific language using this function. 162 163 @param[in] language The language to set. Set a two-character language code based on ISO 639-1 alpha-2. 164 165 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 166 @retval Result::IsSuccess Indicates success. 167 @retval ResultInvalidParameter Indicates an invalid parameter. 168 169 */ 170 nn::Result SetLanguageCodeA2(const char* language); 171 172 /*! 173 @brief Sets the country of the data to include in the NBDL data list. 174 175 By default, the NBDL data list includes data that matches the country in System Settings, but you can download a data list for a specific country using this function. 176 177 @param[in] country The country to set. Set a two-character country code based on ISO 3166-1 alpha-2. 178 179 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 180 @retval Result::IsSuccess Indicates success. 181 @retval ResultInvalidParameter Indicates an invalid parameter. 182 183 */ 184 nn::Result SetCountryCodeA2(const char* country); 185 186 /*! 187 @brief Sets the timeout time for downloading the NBDL data list. 188 189 The standard timeout time of <tt>@ref DOWNLOAD_DEFAULT_TIMEOUT_SEC</tt> is used if no value is set. 190 191 @param[in] timeoutSec Specifies the timeout value to set in seconds. 192 */ 193 void SetTimeoutSec(u32 timeoutSec); 194 195 /*! 196 @brief Sets the options that specify the functionality of NBDL data list tasks. 197 198 @param[in] option Specifies the option to set. 199 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 200 @retval Result::IsSuccess Indicates successful retrieval. 201 @retval ResultInvalidParameter Indicates an invalid parameter. 202 */ 203 nn::Result SetOption(u32 option); 204 205 private: 206 u32 m_TimeoutSec; 207 Task m_DownloadTask; 208 TaskResult m_LastResult; 209 TitleID m_TitleId; 210 211 nn::Result DoDownload(DataAttributes pDataAttributes[NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY], size_t dataAttributesSize, u32* pDataCount, const char* bossCode, u8 slotNo, const char* targetTaskId, const char* directoryName); 212 //! @} 213 214 }; 215 216 } // end of namespace boss 217 } // end of namespace nn 218 219 #endif // __cplusplus 220 221 #endif /* NN_BOSS_BOSS_NBDLDATALIST_H_ */ 222