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_H_ 14 #define NN_EC_API_H_ 15 16 #include <nn/ec/ec_Types.h> 17 #include <nn/ec/ec_DateTime.h> 18 #include <nn/ec/ec_Money.h> 19 #include <nn/ec/ec_Option.h> 20 21 namespace nn { namespace ec { 22 23 //! @addtogroup nn_ec_api 24 //! @{ 25 26 //! @name Library Initialization and Finalization 27 //! @{ 28 29 /*! 30 @brief Initializes the library. 31 32 Initialize the following libraries beforehand. @n 33 If you want to specify an allocator and options, specify them before you call this function. 34 35 @li Socket library (SO) 36 @li SSL library (NSSL) 37 @li HTTP library (CURL) 38 @li Account library (ACT) 39 @li Automatic connection library (AC) 40 41 @return The result of processing. 42 43 @retval Result::IsSuccess Indicates success. 44 @retval ResultInvalidCountry Cannot get the system's country setting. 45 @retval ResultInvalidLanguage Cannot get the system's language setting. 46 @retval ResultInvalidMeta Cannot get the application's metadata. 47 48 @see SetAllocator 49 @see SetOption 50 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48711786">Programming Manual</a> 51 */ 52 nn::Result Initialize(u32 version = NN_EC_VERSION); 53 54 /*! 55 @brief Finalizes the library. 56 57 This function calls <tt>@ref Cancel</tt> and waits until the communication process ends. 58 59 @return The result of processing. 60 61 @retval Result::IsSuccess Indicates success. 62 63 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48711829">Programming Manual</a> 64 */ 65 nn::Result Finalize(); 66 67 //! @} 68 //! @name Settings 69 //! @{ 70 71 /*! 72 @brief Sets the allocator. 73 74 This library allocates and frees memory from multiple threads. @n 75 The allocation or freeing of memory is handled exclusively in the library. It makes no difference whether the allocator is thread-safe or thread-unsafe. @n 76 If the allocator is shared with another module, however, make it thread-safe. 77 78 When not setting an allocator, this library uses <tt>MEMAllocFromDefaultHeapEx</tt> and <tt>MEMFreeToDefaultHeap</tt>. 79 80 If called after <tt>@ref Initialize</tt>, the function returns <tt>@ref ResultAlreadyInitialized</tt>. 81 82 @param[in] pAllocate Memory allocation function. 83 @param[in] pFree Memory-freeing function. 84 85 @return The result of processing. 86 87 @retval Result::IsSuccess Indicates success. 88 @retval ResultAlreadyInitialized The library is already initialized. 89 @retval ResultInvalidArgument Indicates that an argument is invalid. 90 */ 91 nn::Result SetAllocator(AllocateFunction pAllocate, FreeFunction pFree); 92 93 /*! 94 @brief Sets the options. 95 96 See <tt>@ref Option</tt> for the options that can be set. 97 98 If called after <tt>@ref Initialize</tt>, the function returns <tt>@ref ResultAlreadyInitialized</tt>. 99 100 @param[in] option Options. 101 @param[in] pValue The flag to set. 102 103 @return The result of processing. 104 105 @retval Result::IsSuccess Indicates success. 106 @retval ResultAlreadyInitialized The library is already initialized. 107 @retval ResultInvalidArgument Indicates that an argument is invalid. 108 */ 109 nn::Result SetOption(Option option, void* pValue); 110 111 /*! 112 @brief Sets the application. 113 114 If you want to list or purchase items for another title, set the information for that title in this function. @n 115 If you are not handling items for other titles, you do not need to call this function. 116 117 If the EC applet starts immediately after this function has been called, communication processes might take place inside the EC applet startup function. 118 119 If the application is modified, any license information that was synchronized with <tt>@ref SynchronizeAocRights</tt> is cleared. 120 121 @param[in] uniqueId Specifies the unique ID of the title. 122 @param[in] tin Specifies the TIN. 123 124 @return The result of processing. 125 126 @retval Result::IsSuccess Indicates success. 127 @retval ResultNotInitialized Indicates that the library is not initialized. 128 @retval ResultExcluded The EC applet is running. 129 130 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925036">Programming Manual</a> 131 */ 132 nn::Result SetApplication(u32 uniqueId, u32 tin); 133 134 /*! 135 @brief Sets the download callback for metadata. 136 137 This function blocks while the metadata download callback is being called. 138 139 @param[in] pCallback Specifies the callback. @n 140 You can clear this setting by specifying <tt>NULL</tt>. 141 @param[in] pContext Specifies the callback parameters. 142 143 @return The result of processing. 144 145 @retval Result::IsSuccess Indicates success. 146 147 @see Item::DownloadIconAsync 148 @see Item::DownloadPromotionImageAsync 149 @see ItemList::DownloadIconsAsync 150 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48923120">Programming Manual</a> 151 */ 152 nn::Result SetMetadataDownloadCallback(DownloadCallback pCallback, void* pContext); 153 154 /*! 155 @brief Creates a memory cache for metadata. 156 157 When you create a memory cache, you can store the downloaded metadata in that memory cache. 158 159 If the metadata download function finds data in the memory cache, it retrieves the data from the cache. This improves performance when repeatedly downloading the same metadata. 160 161 If the memory cache runs out of space, data is removed from the cache starting from the data that has not been accessed for the longest time. 162 163 @param[in] size Specifies the size of the memory cache. 164 165 @return The result of processing. 166 167 @retval Result::IsSuccess Indicates success. 168 @retval ResultNotInitialized Indicates that the library is not initialized. 169 @retval ResultInvalidArgument Indicates that an argument is invalid. 170 171 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48923255">Programming Manual</a> 172 173 */ 174 nn::Result CreateMetadataCache(size_t size); 175 176 /*! 177 @brief Deletes a metadata memory cache. 178 179 @return The result of processing. 180 181 @retval Result::IsSuccess Indicates success. 182 @retval ResultNotInitialized Indicates that the library is not initialized. 183 184 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48923255">Programming Manual</a> 185 */ 186 nn::Result DeleteMetadataCache(); 187 188 //! @} 189 //! @name Session 190 //! @{ 191 192 /*! 193 @brief Logs in to the eShop server. 194 195 This function gets a service token via the account library and then establishes a session between the client and the eShop server. 196 197 The session established this way may be invalidated by the eShop server for certain reasons. @n 198 Some communication API functions call this function to re-establish a session when an invalid session error has been detected. 199 200 The application must be connected to the network in advance. 201 202 This function blocks because it involves communication. 203 204 @return The result of processing. 205 206 @retval Result::IsSuccess Indicates success. 207 @retval ResultNotInitialized Indicates that the library is not initialized. 208 @retval ResultNotConnected Not connected to the Internet. 209 @retval ResultCanceled The communication process was canceled. 210 @retval ResultExcluded The EC applet is running. 211 @retval ResultEshopNotInitialized The Nintendo eShop initialization sequence has not completed. 212 @retval ResultNeedsNetworkUpdate Specifies that a system update is required. 213 @retval ResultNotInService The service is not available. 214 @retval ResultResponseError A response error occurred. 215 @retval ResultCurlError A communication error occurred. 216 @retval ResultServerError A server error occurred. 217 @retval ResultNetworkUpdateCheckError An error occurred when checking for system update. 218 @retval nn::act::Result* An error occurred in the account library. 219 For more information, see <tt>nn::act::AcquireIndependentServiceToken</tt>. 220 221 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712023">Programming Manual</a> 222 */ 223 nn::Result Login(); 224 225 /*! 226 @brief Gets the time of the eShop server. 227 228 This function uses the time when the client logged in to the eShop server and the internal clock to calculate the eShop server time. @n 229 The function cannot get the time before logging in. @n 230 In addition, accuracy of the time is not guaranteed if one or more days have elapsed since logging in. 231 232 The time might be off by a number of milliseconds to a number of seconds, depending on network latency and the accuracy of the eShop server clock. 233 234 Use this function when comparing the current time with the release date of an item. 235 236 @param[out] pServerTime The server time (UTC). 237 238 @return The result of processing. 239 240 @retval Result::IsSuccess Indicates success. 241 @retval ResultNotInitialized Indicates that the library is not initialized. 242 @retval ResultInvalidArgument Indicates that an argument is invalid. 243 @retval ResultNotLoggedIn Not logged in to the eShop server. 244 245 @see Item::GetReleaseDate 246 */ 247 nn::Result GetServerTime(DateTime* pServerTime); 248 249 //! @} 250 //! @name Communication 251 //! @{ 252 253 /*! 254 @brief Cancels the communication process. 255 256 The communication API functions in this library block until the communication process ends. Call this function from a different thread from the one running communication process. 257 258 When you cancel communication with this function, all subsequent communication API functions return <tt>@ref ResultCanceled</tt>. @n 259 To exit the canceled state, use <tt>@ref ResetCancel</tt>. 260 261 Note that this function cannot cancel the downloading of metadata. @n 262 To cancel this kind of process, use <tt>@ref CancelMetadataDownload</tt>. 263 264 This function calls <tt>nn::act::Cancel</tt>. Keep this in mind when you call this function while an account communication API function is being called. 265 266 @return The result of processing. 267 268 @retval Result::IsSuccess Indicates success. 269 @retval ResultNotInitialized Indicates that the library is not initialized. 270 @retval ResultExcluded The EC applet is running. 271 272 */ 273 nn::Result Cancel(); 274 275 /*! 276 @brief Resets the canceled state. 277 278 Calling this function makes communication API functions available again after communication was canceled. @n 279 Terminating the application without calling this function after a cancellation does not cause any problems. 280 281 @return The result of processing. 282 283 @retval Result::IsSuccess Indicates success. 284 @retval ResultNotInitialized Indicates that the library is not initialized. 285 */ 286 nn::Result ResetCancel(); 287 288 /*! 289 @brief Cancels the downloading of metadata. 290 291 Calling this function cancels all metadata download processes. @n 292 It also clears all messages registered in the download queue. 293 294 @return The result of processing. 295 296 @retval Result::IsSuccess Indicates success. 297 @retval ResultNotInitialized Indicates that the library is not initialized. 298 */ 299 nn::Result CancelMetadataDownload(); 300 301 //! @} 302 //! @name License Information 303 //! @{ 304 305 /*! 306 @brief Updates license information for downloadable content to the most recent state. 307 308 This function is used when license information is updated, such as when purchasing or redeeming items. @n 309 Note that license information can be updated due to external factors while the application is running. (For example, due to the purchase of items on Nintendo eShop.) 310 311 This function blocks because it involves communication. 312 313 @return The result of processing. 314 315 @retval Result::IsSuccess Indicates success. 316 @retval ResultInternalError An internal error occurred. 317 @retval ResultNotInitialized Indicates that the library is not initialized. 318 @retval ResultNotLoggedIn Not logged in to the eShop server. 319 @retval ResultNotConnected Not connected to the Internet. 320 @retval ResultCanceled The communication process was canceled. 321 @retval ResultExcluded The EC applet is running. 322 @retval ResultResponseError A response error occurred. 323 @retval ResultCurlError A communication error occurred. 324 @retval ResultServerError A server error occurred. 325 @retval Other Sometime an error generated by <tt>@ref Login</tt> is returned. 326 327 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712026">Programming Manual</a> 328 */ 329 nn::Result SynchronizeAocRights(); 330 331 /*! 332 @private 333 @brief Gets the content list held by the specified data title. 334 335 If a Nintendo 3DS system is linked with the Nintendo Network ID, you can get the content lists held by 3DS data titles. 336 337 This function blocks because it involves communication. 338 339 @param[out] pContentIndexes A list of content indexes. 340 @param[out] pNum The number of pieces of content. 341 @param[in] num The number of pieces of content you want to get. 342 @param[in] uniqueId The unique ID of the data title. 343 @param[in] variation The variation of the data title. 344 @param[in] platformType The platform type of the data title. 345 346 @return The result of processing. 347 348 @retval Result::IsSuccess Indicates success. 349 @retval ResultNotInitialized Indicates that the library is not initialized. 350 @retval ResultNotLoggedIn Not logged in to the eShop server. 351 @retval ResultNotConnected Not connected to the Internet. 352 @retval ResultCanceled The communication process was canceled. 353 @retval ResultExcluded The EC applet is running. 354 @retval ResultResponseError A response error occurred. 355 @retval ResultCurlError A communication error occurred. 356 @retval ResultServerError A server error occurred. 357 @retval Other Sometime an error generated by <tt>@ref Login</tt> is returned. 358 359 */ 360 nn::Result GetOwnedContents(u16* pContentIndexes, u32* pNum, u32 num, u32 uniqueId, u8 variation, PlatformType platformType); 361 362 //! @} 363 //! @name Balance 364 //! @{ 365 366 /*! 367 @brief Gets the current balance. 368 369 This function blocks because it involves communication. 370 371 @param[out] pBalance Stores the balance. 372 373 @return The result of processing. 374 375 @retval Result::IsSuccess Indicates success. 376 @retval ResultNotInitialized Indicates that the library is not initialized. 377 @retval ResultNotLoggedIn Not logged in to the eShop server. 378 @retval ResultInvalidArgument Indicates that an argument is invalid. 379 @retval ResultNotConnected Not connected to the Internet. 380 @retval ResultCanceled The communication process was canceled. 381 @retval ResultExcluded The EC applet is running. 382 @retval ResultResponseError A response error occurred. 383 @retval ResultCurlError A communication error occurred. 384 @retval ResultServerError A server error occurred. 385 @retval Other Sometime an error generated by <tt>@ref Login</tt> is returned. 386 387 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712048">Programming Manual</a> 388 */ 389 nn::Result GetBalance(Money* pBalance); 390 391 //! @} 392 //! @name Version 393 //! @{ 394 395 /*! 396 @brief Checks whether a data title is the latest version. 397 398 This function blocks because it involves communication. 399 400 @param[out] pIsLatestVersion Stores whether it is the latest version. 401 402 @return The result of processing. 403 404 @retval Result::IsSuccess Indicates success. 405 @retval ResultInternalError An internal error occurred. 406 @retval ResultNotInitialized Indicates that the library is not initialized. 407 @retval ResultNotLoggedIn Not logged in to the eShop server. 408 @retval ResultInvalidArgument Indicates that an argument is invalid. 409 @retval ResultNotConnected Not connected to the Internet. 410 @retval ResultCanceled The communication process was canceled. 411 @retval ResultExcluded The EC applet is running. 412 @retval ResultResponseError A response error occurred. 413 @retval ResultCurlError A communication error occurred. 414 @retval ResultServerError A server error occurred. 415 416 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712081">Programming Manual</a> 417 */ 418 nn::Result CheckDataTitleUpdate(bool* pIsLatestVersion); 419 420 //! @} 421 //! @name Error Handling 422 //! @{ 423 424 /*! 425 @brief Gets the error code from the processing result. 426 427 If the result of the process was <tt>@ref ResultServerError</tt>, the error code retrieved by this function must not be configured in the error viewer. 428 429 @param[in] result Specifies the <tt>result</tt>. 430 431 @return The error code. 432 433 @see GetLastServerErrorMessage 434 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925064">Programming Manual</a> 435 */ 436 s32 GetErrorCode(const nn::Result& result); 437 438 /*! 439 @brief Gets the message for the last server error that occurred. 440 441 If the result of a process was <tt>ResultServerError</tt>, configure the error viewer with the title and message retrieved with this function and display them to the user. @n 442 You do not, however, need to do this for processes that do not affect the system as a whole when they fail, such as background communication and metadata downloading. 443 444 This function blocks while communication is taking place. 445 446 @param[out] pTitle Stores the title to set in error viewer. @n 447 There must be at least <tt>@ref SERVER_ERROR_TITLE_SIZE </tt> elements in the buffer. 448 @param[out] pMessage Stores the message to set in error viewer. @n 449 There must be at least <tt>@ref SERVER_ERROR_MESSAGE_SIZE </tt> elements in the buffer. 450 451 @return The result of processing. 452 453 @retval Result::IsSuccess Indicates success. 454 @retval ResultNotInitialized Indicates that the library is not initialized. 455 @retval ResultInvalidArgument Indicates that an argument is invalid. 456 457 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925064">Programming Manual</a> 458 */ 459 nn::Result GetLastServerErrorMessage(char16* pTitle, char16* pMessage); 460 461 //! @} 462 463 //! @} 464 465 }} // namespace nn::ec 466 467 #endif // NN_EC_API_H_ 468