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_API_APPLET_H_ 14 #define NN_EC_API_APPLET_H_ 15 16 #include <nn/ec/ec_TypesApplet.h> 17 #include <nn/ec/ec_Money.h> 18 #include <nn/ec/ec_ShoppingCart.h> 19 #include <nn/ec/ec_DownloadCart.h> 20 21 namespace nn { namespace ec { namespace applet { 22 23 //! @addtogroup nn_ec_api 24 //! @{ 25 26 //! @name Applet 27 //! @{ 28 29 /*! 30 @brief Sets the anchor. 31 32 By setting an anchor before running the EC applet, you can have the application retrieve that anchor when control returns from the EC applet. @n 33 The application does not need to retrieve the anchor if the POWER Button is pressed and the system enters into the shutdown sequence while the EC applet is running. 34 35 Use <tt>SYSGetArguments</tt> to retrieve the set anchor. 36 37 @param[in] pAnchor Specifies the anchor. @n 38 Specify <tt>NULL</tt> to clear the anchor. 39 40 @return Returns the processing result. 41 42 @retval Result::IsSuccess Indicates success. 43 @retval ResultInvalidArgument Indicates that an argument is invalid. /< The anchor size is too large. 44 45 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925509">Programming Manual</a> 46 */ 47 nn::Result SetAnchor(const char* pAnchor); 48 49 /*! 50 @brief Sets the controller channel to give priority to controlling applets. 51 52 The EC applet can be controlled using the Wii U GamePad and the following controllers. 53 54 @li Wii Remote 55 @li Wii U Pro Controller 56 57 This function sets which controller to give priority to when multiple controllers are available. @n 58 If a controller cannot be found on the specified channel, the EC applet gives priority to the controller with the lowest channel number. 59 60 Note that the Wii U GamePad can always be used to control the applet regardless of the controller channel setting. 61 62 @param[in] channel Specifies the controller channel. @n 63 A value from 0 to 3 can be specified. 64 65 @return The result of processing. 66 67 @retval Result::IsSuccess Indicates success. 68 @retval ResultInvalidArgument Indicates that an argument is invalid. 69 70 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925545">Programming Manual</a> 71 */ 72 nn::Result SetPriorUseControllerChannel(s32 channel); 73 74 /*! 75 @brief Starts the EC applet in balance management mode. 76 77 You must close data titles before running the EC applet. @n 78 In addition, you cannot open data titles while the EC applet is running. 79 80 Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet. 81 82 @param[out] pPostBalance The balance after running the EC applet. @n 83 Specify <tt>NULL</tt> if not necessary. 84 85 @return The result of processing. 86 87 @retval Result::IsSuccess Indicates success. 88 @retval ResultInternalError An internal error occurred. 89 @retval ResultNotInitialized Indicates that the library is not initialized. 90 @retval ResultNotLoggedIn Not logged in to the eShop server. 91 @retval ResultNotInForeground The application is not in the foreground. 92 @retval ResultNotConnected Not connected to the Internet. 93 @retval ResultExcluded The EC applet is running or the system is communicating. 94 @retval ResultResponseError A response error occurred. 95 @retval ResultCurlError A communication error occurred. 96 @retval ResultServerError A server error occurred. 97 98 @see SetApplication 99 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712048">Programming Manual</a> 100 */ 101 nn::Result ManageBalance(Money* pPostBalance = NULL); 102 103 /*! 104 @brief Starts the EC applet in item purchase mode. 105 106 You must close data titles before running the EC applet. @n 107 In addition, you cannot open data titles while the EC applet is running. 108 109 Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet. 110 111 @param[in] shoppingCart Specifies a shopping cart. 112 @param[out] pPostBalance The balance after running the EC applet. @n 113 Specify <tt>NULL</tt> if not necessary. 114 115 @return The result of processing. 116 117 @retval Result::IsSuccess Indicates success. 118 @retval ResultInternalError An internal error occurred. 119 @retval ResultNotInitialized Indicates that the library is not initialized. 120 @retval ResultNotLoggedIn Not logged in to the eShop server. 121 @retval ResultNotInForeground The application is not in the foreground. 122 @retval ResultInvalidData Indicates that the data is invalid. (No items are in the cart, or an item in the cart has invalid data.) 123 @retval ResultNotConnected Not connected to the Internet. 124 @retval ResultExcluded The EC applet is running or the system is communicating. 125 @retval ResultResponseError A response error occurred. 126 @retval ResultCurlError A communication error occurred. 127 @retval ResultServerError A server error occurred. 128 129 @see SetApplication 130 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_54695908">Programming Manual</a> 131 */ 132 nn::Result Purchase(const ShoppingCart& shoppingCart, Money* pPostBalance = NULL); 133 134 /*! 135 @brief Starts the EC applet in item purchase mode. 136 137 This function is for purchasing single items only. @n 138 To purchase batches of items, use the API function that takes a <tt>@ref ShoppingCart</tt> object as an argument. 139 140 You must close data titles before running the EC applet. @n 141 In addition, you cannot open data titles while the EC applet is running. 142 143 Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet. 144 145 @param[in] pItem Specifies the item. 146 @param[out] pPostBalance The balance after running the EC applet. @n 147 Specify <tt>NULL</tt> if not necessary. 148 149 @return The result of processing. 150 151 @retval Result::IsSuccess Indicates success. 152 @retval ResultInternalError An internal error occurred. 153 @retval ResultNotInitialized Indicates that the library is not initialized. 154 @retval ResultNotLoggedIn Not logged in to the eShop server. 155 @retval ResultNotInForeground The application is not in the foreground. 156 @retval ResultInvalidArgument Indicates that an argument is invalid. 157 @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) 158 @retval ResultNotConnected Not connected to the Internet. 159 @retval ResultExcluded The EC applet is running or the system is communicating. 160 @retval ResultResponseError A response error occurred. 161 @retval ResultCurlError A communication error occurred. 162 @retval ResultServerError A server error occurred. 163 164 @see SetApplication 165 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_54695908">Programming Manual</a> 166 */ 167 nn::Result Purchase(const Item* pItem, Money* pPostBalance = NULL); 168 169 /*! 170 @brief Starts the EC applet in item redemption mode. 171 172 You must close data titles before running the EC applet. @n 173 In addition, you cannot open data titles while the EC applet is running. 174 175 Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet. 176 177 @param[out] pPostBalance The balance after running the EC applet. @n 178 If nothing has been added to the balance, the value will not change. @n 179 Specify <tt>NULL</tt> if not necessary. 180 181 @return The result of processing. 182 183 @retval Result::IsSuccess Indicates success. 184 @retval ResultInternalError An internal error occurred. 185 @retval ResultNotInitialized Indicates that the library is not initialized. 186 @retval ResultNotLoggedIn Not logged in to the eShop server. 187 @retval ResultNotInForeground The application is not in the foreground. 188 @retval ResultNotConnected Not connected to the Internet. 189 @retval ResultExcluded The EC applet is running or the system is communicating. 190 @retval ResultResponseError A response error occurred. 191 @retval ResultCurlError A communication error occurred. 192 @retval ResultServerError A server error occurred. 193 194 @see SetApplication 195 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925006">Programming Manual</a> 196 */ 197 nn::Result Redeem(Money* pPostBalance = NULL); 198 199 /*! 200 @brief Starts the EC applet in item redemption mode. 201 202 This function is used when the user selects an item that is redeemed by the application. @n 203 Use the API function that takes no arguments when an item is selected by the EC applet. 204 205 You must close data titles before running the EC applet. @n 206 In addition, you cannot open data titles while the EC applet is running. 207 208 Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet. 209 210 @param[in] pItem Specifies the item. 211 @param[in] pDownloadCode Specifies the download code of the item. @n 212 The function returns <tt>@ref ResultInvalidArgument</tt> if the specified value is not a 16-digit alphanumeric string. 213 @param[out] pPostBalance The balance after running the EC applet. @n 214 If nothing has been added to the balance, the value will not change. @n 215 Specify <tt>NULL</tt> if not necessary. 216 217 @return The result of processing. 218 219 @retval Result::IsSuccess Indicates success. 220 @retval ResultInternalError An internal error occurred. 221 @retval ResultNotInitialized Indicates that the library is not initialized. 222 @retval ResultNotLoggedIn Not logged in to the eShop server. 223 @retval ResultNotInForeground The application is not in the foreground. 224 @retval ResultInvalidArgument Indicates that an argument is invalid. 225 @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) 226 @retval ResultNotConnected Not connected to the Internet. 227 @retval ResultExcluded The EC applet is running or the system is communicating. 228 @retval ResultResponseError A response error occurred. 229 @retval ResultCurlError A communication error occurred. 230 @retval ResultServerError A server error occurred. 231 232 @see SetApplication 233 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925006">Programming Manual</a> 234 */ 235 nn::Result Redeem(const Item* pItem, const char* pDownloadCode, Money* pPostBalance = NULL); 236 237 /*! 238 @brief Starts the EC applet in item redownload mode. 239 240 You must close data titles before running the EC applet. @n 241 In addition, you cannot open data titles while the EC applet is running. 242 243 Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet. 244 245 @param[in] downloadCart Specifies the download cart. 246 247 @return The result of processing. 248 249 @retval Result::IsSuccess Indicates success. 250 @retval ResultInternalError An internal error occurred. 251 @retval ResultNotInitialized Indicates that the library is not initialized. 252 @retval ResultNotLoggedIn Not logged in to the eShop server. 253 @retval ResultNotInForeground The application is not in the foreground. 254 @retval ResultInvalidData Indicates that the data is invalid. (No items are in the cart, or an item in the cart has invalid data.) 255 @retval ResultNotConnected Not connected to the Internet. 256 @retval ResultExcluded The EC applet is running or the system is communicating. 257 @retval ResultResponseError A response error occurred. 258 @retval ResultCurlError A communication error occurred. 259 @retval ResultServerError A server error occurred. 260 261 @see SetApplication 262 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48924983">Programming Manual</a> 263 */ 264 nn::Result Download(const DownloadCart& downloadCart); 265 266 /*! 267 @brief Starts the EC applet in item redownload mode. 268 269 This function is for redownloading single items only. @n 270 To redownload multiple items at one time, use the API function that takes a <tt>@ref DownloadCart</tt> object as an argument. 271 272 You must close data titles before running the EC applet. @n 273 In addition, you cannot open data titles while the EC applet is running. 274 275 Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet. 276 277 @param[in] pItem Specifies the item. 278 279 @return The result of processing. 280 281 @retval Result::IsSuccess Indicates success. 282 @retval ResultInternalError An internal error occurred. 283 @retval ResultNotInitialized Indicates that the library is not initialized. 284 @retval ResultNotLoggedIn Not logged in to the eShop server. 285 @retval ResultNotInForeground The application is not in the foreground. 286 @retval ResultInvalidArgument Indicates that an argument is invalid. 287 @retval ResultInvalidData Indicates that the data is invalid. (Item contains invalid data.) 288 @retval ResultNotConnected Not connected to the Internet. 289 @retval ResultExcluded The EC applet is running or the system is communicating. 290 @retval ResultResponseError A response error occurred. 291 @retval ResultCurlError A communication error occurred. 292 @retval ResultServerError A server error occurred. 293 294 @see SetApplication 295 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48924983">Programming Manual</a> 296 */ 297 nn::Result Download(const Item* pItem); 298 299 /*! 300 @brief Starts the EC applet in data title update mode. 301 302 You must close data titles before running the EC applet. @n 303 In addition, you cannot open data titles while the EC applet is running. 304 305 Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet. 306 307 @return The result of processing. 308 309 @retval Result::IsSuccess Indicates success. 310 @retval ResultInternalError An internal error occurred. 311 @retval ResultNotInitialized Indicates that the library is not initialized. 312 @retval ResultNotLoggedIn Not logged in to the eShop server. 313 @retval ResultNotInForeground The application is not in the foreground. 314 @retval ResultNotConnected Not connected to the Internet. 315 @retval ResultExcluded The EC applet is running or the system is communicating. 316 @retval ResultResponseError A response error occurred. 317 @retval ResultCurlError A communication error occurred. 318 @retval ResultServerError A server error occurred. 319 320 @see SetApplication 321 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712081">Programming Manual</a> 322 */ 323 nn::Result UpdateDataTitle(); 324 325 /*! 326 @brief Determines whether the EC applet is running. 327 328 While the EC applet is running, communications, excluding the downloading of metadata, and the execution of the EC applet are restricted. 329 330 @return Returns <tt>true</tt> if the EC applet is running, or <tt>false</tt> otherwise. 331 332 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48931067">Programming Manual</a> 333 */ 334 bool IsExecuting(); 335 336 /*! 337 @brief Finishes the processing of the EC applet. 338 339 Calling this function updates both the processing result of the EC applet and the balance after running the EC applet. @n 340 It also cancels restrictions on communications and the EC applet's execution. 341 342 Call this function when the application has transitioned from the background to the foreground. @n 343 If you call this function at any other time it could cause inconsistencies. 344 345 @return The result of processing. 346 347 @retval Result::IsSuccess Indicates success. 348 349 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48931067">Programming Manual</a> 350 */ 351 nn::Result Finish(); 352 353 /*! 354 @brief Gets the processing result of the EC applet. 355 356 You must call <tt>@ref Finish</tt> before calling this function. 357 358 @return Returns the return code. 359 360 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48931067">Programming Manual</a> 361 */ 362 s32 GetReturnCode(); 363 364 //! @} 365 366 //! @} 367 368 }}} // namespace nn::ec::applet 369 370 #endif // NN_EC_API_APPLET_H_ 371