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_ACT_API_H_
14 #define NN_ACT_API_H_
15
16
17 #include "act_Types.h"
18
19 #include "act_ApiTimeZone.h"
20 #include "act_ApiParentalControls.h"
21
22 #include <nn/acp/acp_IsOverAge.h>
23
24
25 #ifdef __cplusplus
26
27 namespace nn
28 {
29 namespace act
30 {
31
32 /*!
33 @ingroup nn_act
34 @defgroup nn_act_api Account (ACT) API
35 @brief A list of Account (ACT) library members. (Includes only C++ API members.)
36 @{
37 */
38
39
40 //! @name Initializing and Finalizing the Library
41 //! @{
42
43 /*!
44 @brief Initializes the account library and prepares it for use.
45
46 This function can be called multiple times even if the account library is already initialized, but the <tt>@ref nn::act::Finalize</tt> function must be called an equal number of times to completely finalize the account library.
47
48 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
49 @retval ResultSuccess Succeeded.
50
51 */
52 Result Initialize( void );
53
54 /*!
55 @brief Finalizes the account library.
56
57 If the <tt>@ref nn::act::Initialize</tt> function is called multiple times, this function must be called an equal number of times to completely finalize the account library.
58 <tt>ResultNotInitialized</tt> is returned if this function is called more times than the <tt>@ref nn::act::Initialize</tt> function.
59
60 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
61 @retval ResultSuccess Succeeded.
62 @retval ResultNotInitialized Specifies that the account library is not initialized.
63 */
64 Result Finalize( void );
65
66
67 //! @}
68 //! @name Getting Account Slot Information
69 //! @{
70
71 /*!
72 @brief Checks whether there is a system account in the specified slot number.
73
74 @param[in] slotNo Specifies the slot number.
75
76 @return Returns <tt>true</tt> if there is an account in the slot, and <tt>false</tt> otherwise.
77 Also returns <tt>false</tt> when an out-of-bounds slot number is specified or the account library is uninitialized.
78 */
79 bool IsSlotOccupied( u8 slotNo );
80
81 /*!
82 @brief Gets the number of existing system accounts.
83
84 A return value of <tt>n</tt> indicates that there are system accounts in slots <tt>1</tt> through <tt>n</tt>.
85
86 @return Returns the number of existing system accounts.
87 */
88 u8 GetNumOfAccounts( void );
89
90
91 //! @}
92 //! @name Getting Current Account Information
93 //! @{
94
95 /*!
96 @brief Gets the slot number of the current account.
97
98 @return Returns the slot number of the current account.
99 */
100 u8 GetSlotNo( void );
101
102 /*!
103 @brief Determines whether the current account is a network account.
104
105 @return Returns <tt>true</tt> if the current account is a network account, and <tt>false</tt> otherwise.
106 Also returns <tt>false</tt> if called when the account library is uninitialized.
107 */
108 bool IsNetworkAccount( void );
109
110 /*!
111 @brief Gets the store data for the Mii character of the current account.
112
113 Gets the store data for the Mii character that is configured for the current system account.
114 Even if the system account is linked to a Nintendo Network Account, calling this function does not trigger any communication because the local copy that is used for a Mii character was synchronized separately from this function call.
115
116 The Face library is also required in order to use Mii character store data.
117
118 If the function fails, the value set in the buffer is undefined.
119
120 @param[out] pMiiData Specifies a pointer to the buffer that stores the Mii character store data.
121
122 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
123 @retval ResultSuccess Succeeded.
124 @retval ResultNotInitialized Indicates that the account library has not been initialized.
125 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
126
127 */
128 Result GetMii( FFLStoreData* pMiiData );
129
130 /*!
131 @brief Gets the Mii character name of the current account.
132
133 Gets the name of the Mii character that is configured for the current system account.
134 Even if the system account is linked to a Nintendo Network Account, calling this function does not trigger any communication because the local copy that is used for a Mii character name was synchronized separately from this function call.
135
136 Use this function to get the Mii character name directly without using the Mii Face library.
137
138 The Mii nickname might contain characters that are not supported by the application.
139 Handle this so that it does not corrupt the screen display or hinder the progress of your application.
140 For more information, see the Nicknames and Creator Names section in the Wii U Guidelines.
141
142 Pass a buffer with at least as many elements as <tt>ACT_MII_NAME_SIZE</tt> to <var>pMiiName</var>.
143
144 If the function fails, the value set in the buffer is undefined.
145
146 @param[out] pMiiName Specifies a pointer to the buffer that stores the name of the Mii character.
147
148 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
149 @retval ResultSuccess Succeeded.
150 @retval ResultNotInitialized Indicates that the account library has not been initialized.
151 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
152 @retval ResultAccountNotFound Indicates that the system account was not found in the specified slot.
153
154 */
155 Result GetMiiName( char16* pMiiName );
156
157 /*!
158 @brief Gets the country setting for the current account.
159
160 Gets the country setting of the Nintendo Network Account linked to the current account in ISO 3166-1 alpha-2 format.
161 Note that this function does not trigger any communication because it retrieves the value from the local cache.
162
163 Pass a pointer to a buffer at least as big as <tt>ACT_COUNTRY_SIZE</tt> to <var>pCountry</var>.
164
165 When it is not a network account, the function succeeds and a blank string is copied to <var>pCountry</var>.
166
167 If the function fails, the value set in the buffer is undefined.
168
169 @param[out] pCountry Specifies an out pointer to the buffer that stores the country setting.
170
171 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
172 @retval ResultSuccess Succeeded.
173 @retval ResultNotInitialized Indicates that the account library has not been initialized.
174 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
175 */
176 Result GetCountry( char* pCountry );
177
178 /*!
179 @brief Gets the account ID of the current account.
180
181 Gets the account ID (Nintendo Network ID) of the Nintendo Network Account that is linked to the current account.
182 Note that this function does not trigger any communication because it retrieves the value from the local cache.
183
184 Pass a pointer in <var>pAccountId</var> to a buffer at least as big as <tt>ACT_ACCOUNT_ID_SIZE</tt>.
185
186 When it is not a network account, the function succeeds and a blank string is copied to <var>pAccountId</var>.
187
188 If the function fails, the value set in the buffer is undefined.
189
190 @param[out] pAccountId Specifies an out pointer to the buffer that stores the account ID.
191
192 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
193 @retval ResultSuccess Succeeded.
194 @retval ResultNotInitialized Indicates that the account library has not been initialized.
195 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
196 */
197 Result GetAccountId( char* pAccountId );
198
199 /*!
200 @brief Determines whether the current account user is at least the specified age.
201
202 Determines whether the user is at least the specified age by calculating the user's age based on the current date and the birth date set for the Nintendo Network Account linked to the current account.
203 This function uses the locally cached value to determine the age, so communication is not triggered.
204 It is also not affected by manipulation of the system clock by the user.
205 In some extremely limited cases, however, this function returns <tt>false</tt> because the information required to estimate the time is unavailable due to factors such as being unable to connect to the Internet while the system RTC battery has run out.
206
207 Nintendo systems calculate the age of the user based on UTC+12 time, regardless of their country or region of residence.
208 For users in Japan, age is calculated based on 9 P.M. of the day before the date of birth.
209
210 If you want to get the age of a user directly, please contact Nintendo support.
211 Avoid identifying the ages of users through repeated calls to this function.
212
213 @param[in] age Specifies the age to compare.
214
215 @return Returns <tt>true</tt> if the user of the current account is the specified age or older, and returns <tt>false</tt> if the user is younger than the specified age.
216 Returns <tt>false</tt> if used on a local account.
217 */
IsOverAge(u8 age)218 inline bool IsOverAge( u8 age )
219 {
220 return static_cast<bool>(ACPIsOverAgeEx( age, ACT_SLOT_NO_CURRENT ));
221 }
222
223 /*!
224 @brief Gets the principal ID of the current account.
225
226 Gets the principal ID of the Nintendo Network Account that is linked to the current account.
227 Note that this function does not trigger any communication because it retrieves the value from the local cache.
228
229 @return Returns the principal ID of the current account.
230 If this function is called on a non-network account or while the account library is uninitialized, <tt>ACT_INVALID_PRINCIPAL_ID</tt> is returned.
231 */
232 u32 GetPrincipalId( void );
233
234 /*!
235 @brief Gets the residence information for the current account.
236
237 Gets the residence information for the Nintendo Network Account that is linked to the current account.
238 Note that this function does not trigger any communication because it retrieves the value from the local cache.
239
240 @return Returns a 32-bit ID that indicates the residence information for the current account.
241 If this function is called on a non-network account or while the account library is uninitialized, <tt>ACT_INVALID_SIMPLE_ADDRESS_ID</tt> is returned.
242 */
243 u32 GetSimpleAddressId( void );
244
245 /*!
246 @brief Gets the UUID of the current account.
247
248 Gets the UUID of the current system account.
249
250 The system account UUID is assigned when the account is created and does not change until the system account is deleted. However, because the ID spaces of these UUIDs are different for each title, if the function is called by a different title, a different UUID is returned even for the same system account.
251 Contact Nintendo support if you want to identify a system account by UUID from multiple titles.
252
253 The UUID obtained by this function conforms to RFC 4122 version 1, but the ID format can be changed within a scope that maintains its uniqueness.
254 Be sure to handle the ID in its entirety as a single value. Do not use any individual parts of the ID as a timestamp or device identifier.
255
256 If the function fails, the value set in the buffer is undefined.
257
258 @param[out] pUuid Specifies an out pointer to the buffer that stores the UUID.
259
260 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
261 @retval ResultSuccess Succeeded.
262 @retval ResultNotInitialized Indicates that the account library has not been initialized.
263 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
264
265
266 */
267 Result GetUuid( ACTUuid* pUuid );
268
269 //! @}
270 //! @name Getting Other Account Information
271 //! @{
272
273 /*!
274 @brief Gets the slot number for the system account with the specified UUID.
275
276 @param[in] uuid Specifies the UUID.
277
278 @return Returns the slot number if a system account exists for the specified UUID, and returns <tt>ACT_INVALID_SLOT_NO</tt> if no such account exists.
279 Also returns <tt>ACT_INVALID_SLOT_NO</tt> if called when the account library is uninitialized.
280 */
281 u8 GetSlotNoEx( const ACTUuid& uuid );
282
283 /*!
284 @brief Determines whether the specified system account is a network account.
285
286 @param[in] slotNo Specifies the slot number.
287
288 @return Returns <tt>true</tt> if the system account in the specified slot is a network account, and <tt>false</tt> otherwise.
289 Also returns <tt>false</tt> if no system account exists in the specified slot or if the account library is uninitialized.
290 */
291 bool IsNetworkAccountEx( u8 slotNo );
292
293 /*!
294 @brief Gets the Mii character store data for the system account in the specified slot.
295
296 Gets the store data for the Mii character that is configured for the system account in the specified slot.
297 Even if the system account is linked to a Nintendo Network Account, calling this function does not trigger any communication because the local copy that is used for a Mii character was synchronized separately from this function call.
298
299 The Mii Face library is also required to use Mii character store data.
300
301 If the function fails, the value set in the buffer is undefined.
302
303 @param[out] pMiiData Specifies a pointer to the buffer that stores the Mii character store data.
304 @param[in] slotNo Specifies the slot number.
305
306 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
307 @retval ResultSuccess Succeeded.
308 @retval ResultNotInitialized Indicates that the account library has not been initialized.
309 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
310 @retval ResultAccountNotFound Indicates that the system account was not found in the specified slot.
311
312 */
313 Result GetMiiEx( FFLStoreData* pMiiData, u8 slotNo );
314
315 /*!
316 @brief Gets the Mii character name for the system account in the specified slot.
317
318 Gets the name of the Mii character that is configured for the system account in the specified slot.
319 Even if the system account is linked to a Nintendo Network Account, calling this function does not trigger any communication because the local copy that is used for a Mii character name was synchronized separately from this function call.
320
321 Use this function to get the Mii character name directly, without using the Mii Face library.
322
323 The Mii nickname might contain characters that are not supported by the application.
324 Handle this so that it does not corrupt the screen display or hinder the progress of your application.
325 For more information, see the Nicknames and Creator Names section in the Wii U Guidelines.
326
327 Pass a buffer with at least as many elements as <tt>ACT_MII_NAME_SIZE</tt> to <var>pMiiName</var>.
328
329 If the function fails, the value set in the buffer is undefined.
330
331 @param[out] pMiiName Specifies a pointer to the buffer that stores the name of the Mii character.
332 @param[in] slotNo Specifies the slot number.
333
334 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
335 @retval ResultSuccess Succeeded.
336 @retval ResultNotInitialized Indicates that the account library has not been initialized.
337 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
338 @retval ResultAccountNotFound Indicates that the system account was not found in the specified slot.
339
340 */
341 Result GetMiiNameEx( char16* pMiiName, u8 slotNo );
342
343 /*!
344 @brief Gets the country setting for the account in the specified slot.
345
346 Gets the country setting in ISO 3166-1 alpha-2 format for the Nintendo Network Account linked to the system account in the specified slot.
347 Note that this function does not trigger any communication because it retrieves the value from the local cache.
348
349 Pass a pointer to a buffer at least as big as <tt>ACT_COUNTRY_SIZE</tt> to <var>pCountry</var>.
350
351 When it is not a network account, the function succeeds and a blank string is copied to <var>pCountry</var>.
352
353 If the function fails, the value set in the buffer is undefined.
354
355 @param[out] pCountry Specifies an out pointer to the buffer that stores the country setting.
356 @param[in] slotNo Specifies the slot number.
357
358 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
359 @retval ResultSuccess Succeeded.
360 @retval ResultNotInitialized Indicates that the account library has not been initialized.
361 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
362 @retval ResultAccountNotFound Indicates that the system account was not found in the specified slot.
363 */
364 Result GetCountryEx( char* pCountry, u8 slotNo );
365
366 /*!
367 @brief Gets the account ID for the account in the specified slot.
368
369 Gets the account ID (Nintendo Network ID) of the Nintendo Network Account that is linked to the system account in the specified slot.
370 Note that this function does not trigger any communication because it retrieves the value from the local cache.
371
372 Pass a pointer in <var>pAccountId</var> to a buffer at least as big as <tt>ACT_ACCOUNT_ID_SIZE</tt>.
373
374 When it is not a network account, the function succeeds and a blank string is copied to <var>pAccountId</var>.
375
376 If the function fails, the value set in the buffer is undefined.
377
378 @param[out] pAccountId Specifies an out pointer to the buffer that stores the account ID.
379 @param[in] slotNo Specifies the slot number.
380
381 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
382 @retval ResultSuccess Succeeded.
383 @retval ResultNotInitialized Indicates that the account library has not been initialized.
384 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
385 @retval ResultAccountNotFound Indicates that the system account was not found in the specified slot.
386 */
387 Result GetAccountIdEx( char* pAccountId, u8 slotNo );
388
389 /*!
390 @brief Determines whether the account user for the specified slot is at least the specified age.
391
392 Determines whether the user is at least the specified age by calculating the user's age based on the current date and the birth date set for the Nintendo Network Account linked to the system account in the specified slot.
393 This function uses the locally cached value to determine the age, so it does not trigger any communication and is not affected by manipulation of the system clock by the user.
394 In some extremely limited cases, however, this function returns <tt>false</tt> because the information required to estimate the time is unavailable due to factors such as being unable to connect to the Internet while the system RTC battery has run out.
395
396 Nintendo systems calculate the age of the user based on UTC+12 time, regardless of their country or region of residence.
397 For users in Japan, age is calculated based on 9 P.M. of the day before the date of birth.
398
399 If you want to get the age of a user directly, please contact Nintendo support.
400 Avoid identifying the ages of users through repeated calls to this function.
401
402 @param[in] age Specifies the age to compare.
403 @param[in] slotNo Specifies the slot number.
404
405 @return Returns <tt>true</tt> if the user of the system account in the specified slot is the specified age or older, and returns <tt>false</tt> if the user is not of the specified age.
406 Also returns <tt>false</tt> if called on a local account, if no system account exists in the specified slot, and if the account library is uninitialized.
407 */
IsOverAgeEx(u8 age,u8 slotNo)408 inline bool IsOverAgeEx( u8 age, u8 slotNo )
409 {
410 return static_cast<bool>(ACPIsOverAgeEx( age, slotNo ));
411 }
412
413 /*!
414 @brief Gets the principal ID for the account in the specified slot.
415
416 Gets the principal ID of the Nintendo Network Account that is linked to the system account in the specified slot.
417 Note that this function does not trigger any communication because it retrieves the value from the local cache.
418
419 When it is not a network account, the function succeeds and <tt>ACT_INVALID_PRINCIPAL_ID</tt> is copied to <var>pPrincipalId</var>.
420
421 @param[out] pPrincipalId Specifies an out pointer to the buffer that stores the principal ID.
422 @param[in] slotNo Specifies the slot number.
423
424 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
425 @retval ResultSuccess Succeeded.
426 @retval ResultNotInitialized Indicates that the account library has not been initialized.
427 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
428 @retval ResultAccountNotFound Indicates that the system account was not found in the specified slot.
429 */
430 Result GetPrincipalIdEx( u32* pPrincipalId, u8 slotNo );
431
432 /*!
433 @brief Gets the residence information for the account in the specified slot.
434
435 Gets the residence information of the Nintendo Network Account that is linked to the system account in the specified slot.
436 Note that this function does not trigger any communication because it retrieves the value from the local cache.
437
438 When it is not a network account, the function succeeds and <tt>ACT_INVALID_SIMPLE_ADDRESS_ID</tt> is copied to <var>pSimpleAddressId</var>.
439
440 If the function fails, the value set in the buffer is undefined.
441
442 @param[out] pSimpleAddressId Specifies an out pointer to the buffer that stores the residence information.
443 @param[in] slotNo Specifies the slot number.
444
445 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
446 @retval ResultSuccess Succeeded.
447 @retval ResultNotInitialized Indicates that the account library has not been initialized.
448 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
449 @retval ResultAccountNotFound Indicates that the system account was not found in the specified slot.
450 */
451 Result GetSimpleAddressIdEx( u32* pSimpleAddressId, u8 slotNo );
452
453 /*!
454 @brief Gets the UUID of the system account in the specified slot.
455
456 Gets the UUID of the system account in the specified slot.
457 Specify <tt>ACT_SLOT_NO_COMMON</tt> for the slot number to get the UUID assigned to the system instead of the account.
458
459 The UUID of the system account is assigned at the time of account creation and does not change until the system account is deleted.
460 The UUID of the console, however, is assigned at initial setup and is replaced with a new value if the system is restored to factory defaults.
461 However, because the ID spaces of these UUIDs are different for each title, if the function is called by a different title, a different UUID is returned even for the same account and system.
462 Contact Nintendo support if you want to identify a system account or the system itself by UUIDs from multiple titles.
463
464 The UUID obtained by this function conforms to RFC 4122 version 1, but the ID format can be changed within a scope that maintains its uniqueness.
465 Each of these IDs is intended to serve as a single, complete ID. Please do not use parts of the IDs for purposes such as time or device identifiers.
466
467 In a development environment that has not run through the initial Wii U setup, the UUID parameter assigned to the console is not saved and a different UUID could be returned every time the system starts up.
468 If this occurs, perform a normal shutdown once after acquiring the initial UUID assigned to the system.
469 This procedure is effective until the next time the development hardware is initialized, and does not need to be repeated for every development title.
470
471 If the function fails, the value set in the buffer is undefined.
472
473 @param[out] pUuid Specifies an out pointer to the buffer that stores the UUID.
474 @param[in] slotNo Specifies the slot number.
475
476 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
477 @retval ResultSuccess Succeeded.
478 @retval ResultNotInitialized Indicates that the account library has not been initialized.
479 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
480 @retval ResultAccountNotFound Indicates that the system account was not found in the specified slot.
481
482 */
483 Result GetUuidEx( ACTUuid* pUuid, u8 slotNo );
484
485
486 //! @}
487 //! @name Getting Service Tokens
488 //! @{
489
490 /*!
491 @brief Gets a service token for an independent service.
492
493 To get a service token using this function, you must register the service and title information on OMAS and receive a client ID issued by Nintendo in advance, and use the Wii U Application Configuration Tool and other tools to set the Unique ID for your application as registered.
494
495 Unless there are compatibility issues for past titles, we recommend using the <tt>@ref nn::act::AcquireIndependentServiceTokenV2</tt> function.
496
497 When you start an application on the development hardware without going through the Wii U Menu, there is no opportunity to enter a password. Authentication will fail if you do not set the current account to remember the password.
498
499 By default, this function checks the <b>Online Interaction in Games</b> setting in Parental Controls and fails without performing any communication if interaction is restricted.
500 To ignore this restriction and get a service token, for example for a non-game application or to temporarily disable Parental Controls, call the <tt>@ref nn::act::EnableParentalControlCheck</tt> function in advance to lift the restriction.
501 However, follow all the requirements in Guidelines when canceling parental control.
502 Configure applications as needed to implement functionality corresponding to the other Parental Controls settings.
503
504 For <var>pServiceToken</var>, pass a pointer to a buffer at least as big as <tt>ACT_INDEPENDENT_SERVICE_TOKEN_SIZE</tt>.
505
506 This function causes communication with the server, during which time processing is blocked.
507
508 If the function fails, the value set in the buffer is undefined.
509
510 @param[out] pServiceToken Specifies an out pointer to the buffer that stores the service token.
511 @param[in] pClientId Specifies a pointer to the buffer that stores the client ID for the independent service.
512
513 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
514 @retval ResultSuccess Succeeded.
515 @retval ResultNotInitialized Indicates that the account library has not been initialized.
516 @retval ResultNotNetworkAccount Indicates that the account is not a network account.
517 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
518 @retval ResultInvalidClientId Indicates that the client ID is not registered on the server.
519 @retval ResultAuthenticationError Indicates that authentication failed.
520
521
522 */
523 Result AcquireIndependentServiceToken
524 (
525 char* pServiceToken,
526 const char* pClientId
527 );
528
529 /*!
530 @brief Gets a service token for an independent service.
531
532 To get a service token using this function, you must register the service and title information on OMAS and receive a client ID issued by Nintendo in advance. Use the Wii U Application Configuration Tool and other tools to set the Unique ID for your application as registered.
533
534 Unless there are compatibility issues for past titles, we recommend using the <tt>@ref nn::act::AcquireIndependentServiceTokenV2</tt> function.
535
536 When you start an application on the development hardware without going through the Wii U Menu, there is no opportunity to enter a password. Authentication will fail if you do not set the current account to remember the password.
537
538 By default, this function checks the <b>Online Interaction in Games</b> setting in Parental Controls and fails without performing any communication if interaction is restricted.
539 To ignore this restriction and get a service token, for example for a non-game application or to temporarily disable Parental Controls, call the <tt>@ref nn::act::EnableParentalControlCheck</tt> function in advance to lift the restriction.
540 However, follow all the requirements in Guidelines when canceling parental control.
541 Configure applications as needed to implement functionality corresponding to the other Parental Controls settings.
542
543 For <var>pServiceToken</var>, pass a pointer to a buffer at least as big as <tt>ACT_INDEPENDENT_SERVICE_TOKEN_SIZE</tt>.
544
545 Note that the lifetime specified by <var>reusableRangeInSeconds</var> does not define the cache expiration period for the service token obtained with this function. Instead, it specifies how long a previously retrieved cache is to remain valid.
546 Service tokens obtained from the account server must be stored in a cached within the system. If the cache includes a service token that was obtained within <var>reusableRangeInSeconds</var> seconds, the function returns that service token and does not communicate with the account server.
547 To get a service token again because it has expired or was rejected by the independent server for another reason, specify <tt>0</tt> for <var>reusableRangeInSeconds</var> to make sure that you get a new token from the server.
548
549 Nintendo strongly recommends implementing a means of obtaining service tokens again when using the service token cache, so that errors do not continue to occur until the token expires in the event that a cached token is illegal or invalid.
550 To obtain service tokens again without using the cache, set <tt>reusableRangeInSeconds</tt> to <tt>0</tt>.
551
552 This function sometimes causes communication with the server, during which the function blocks.
553
554 If the function fails, the value set in the buffer is undefined.
555
556 @param[out] pServiceToken Specifies an out pointer to the buffer that stores the service token.
557 @param[in] pClientId Specifies a pointer to the buffer that stores the client ID for the independent service.
558 @param[in] reusableRangeInSeconds Specifies how many seconds ago a cache can have been obtained for a service token and still be valid.
559
560 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
561 @retval ResultSuccess Succeeded.
562 @retval ResultNotInitialized Indicates that the account library has not been initialized.
563 @retval ResultNotNetworkAccount Indicates that the account is not a network account.
564 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
565 @retval ResultInvalidClientId Indicates that the client ID is not registered on the server.
566 @retval ResultAuthenticationError Indicates that authentication failed.
567
568
569
570 */
571 Result AcquireIndependentServiceToken
572 (
573 char* pServiceToken,
574 const char* pClientId,
575 u32 reusableRangeInSeconds
576 );
577
578 /*!
579 @brief Gets a service token for an e-commerce service.
580
581 Currently, this function can be used only to implement features for purchasing service items through an independent server.
582 For more information, see <i>Wii U Overview: E-Commerce</i>.
583
584 When you start an application on the development hardware without going through the Wii U Menu, there is no opportunity to enter a password. Authentication will fail if you do not set the current account to remember the password.
585
586 By default, this function checks the <b>Online Interaction in Games</b> setting in Parental Controls and fails without performing any communication if interaction is restricted.
587 However, this function does not check other Parental Controls settings such as the <b>Wii U Shopping Services</b> setting.
588 To provide features corresponding to Parental Controls settings other than the <b>Online Interaction in Games</b> setting, make the appropriate settings in the application.
589 To ignore this restriction and get a service token, for example for a non-game application or to temporarily disable Parental Controls, you must call the <tt>@ref nn::act::EnableParentalControlCheck</tt> function in advance to lift the restriction.
590 However, follow all the requirements in Guidelines when suspending Parental Controls.
591
592 Pass a pointer to a buffer at least as big as <tt>ACT_INDEPENDENT_SERVICE_TOKEN_SIZE</tt> to <var>pEcServiceToken</var>.
593
594 This function causes communication with the server, during which time processing is blocked.
595
596 If the function fails, the value set in the buffer is undefined.
597
598 @param[out] pEcServiceToken Specifies an out pointer to the buffer that stores the service token.
599
600 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
601 @retval ResultSuccess Succeeded.
602 @retval ResultNotInitialized Indicates that the account library has not been initialized.
603 @retval ResultNotNetworkAccount Indicates that the account is not a network account.
604 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
605 @retval ResultAuthenticationError Indicates that authentication failed.
606
607 */
608 Result AcquireEcServiceToken
609 (
610 char* pEcServiceToken
611 );
612
613 /*!
614 @brief Gets a service token (version 2) for an independent service.
615
616 To get a service token using this function, you must register the service and title information on OMAS and receive a client ID issued by Nintendo in advance. Use the Wii U Application Configuration Tool and other tools to set the Unique ID for your application as registered.
617
618 This function's security has been improved over that of the prior token function, <tt>@ref nn::act::AcquireIndependentServiceToken</tt>.
619 Unless there are compatibility issues for past titles, use this function.
620
621 For more information about the use of service tokens, see the Account System Developer's Guide.
622
623 When you start an application on the development hardware without going through the Wii U Menu, there is no opportunity to enter a password. Authentication will fail if you do not set the current account to remember the password.
624
625 By default, this function checks the <b>Online Interaction in Games</b> setting in <b>Parental Controls</b> and fails without performing any communication if interaction is restricted.
626 To ignore this restriction and get a service token, for example for a non-game application or to temporarily disable <b>Parental Controls</b>, call the <tt>@ref nn::act::EnableParentalControlCheck</tt> function in advance to lift the restriction.
627 However, follow all the requirements in the guidelines when canceling parental control.
628 Configure applications as needed to implement functionality corresponding to the other <b>Parental Controls</b> settings.
629
630 Note that the lifetime specified by <var>reusableRangeInSeconds</var> does not define the cache expiration period for the service token obtained with this function. Instead, it specifies how long a previously retrieved cache is to remain valid.
631 Service tokens obtained from the account server must be stored in a cache within the system. If the cache includes a service token that was obtained within <var>reusableRangeInSeconds</var> seconds, the function returns that service token and does not communicate with the account server.
632 To get a service token again, because it has expired or was rejected by the independent server for another reason, specify <tt>0</tt> for <var>reusableRangeInSeconds</var> to make sure that you get a new token from the server.
633
634 Nintendo strongly recommends implementing a means of reobtaining service tokens when using the service token cache, so that errors do not continue to occur until the token expires in the event that a cached token is illegal or invalid.
635 To obtain service tokens again without using the cache, set <tt>reusableRangeInSeconds</tt> to <tt>0</tt>.
636
637 This function sometimes causes communication with the server, during which the function blocks.
638
639 If the function fails, the value set in the buffer is undefined.
640
641 @param[out] pServiceToken Specifies an out pointer to the buffer that stores the service token.
642 @param[in] pClientId Specifies a pointer to the buffer that stores the client ID for the independent service.
643 @param[in] reusableRangeInSeconds Specifies the amount of seconds in the past that a cache can have been obtained for a service token and still be valid.
644
645 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
646 @retval ResultSuccess Succeeded.
647 @retval ResultNotInitialized Indicates that the account library has not been initialized.
648 @retval ResultNotNetworkAccount Indicates that the account is not a network account.
649 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
650 @retval ResultInvalidClientId Indicates that the client ID is not registered on the server.
651 @retval ResultAuthenticationError Indicates that authentication failed.
652
653
654
655 */
656 Result AcquireIndependentServiceTokenV2
657 (
658 ACTServiceTokenV2* pServiceToken,
659 const char* pClientId,
660 u32 reusableRangeInSeconds = 0
661 );
662
663
664 /*!
665 @brief Cancels communication tasks with the account server that are waiting for completion.
666
667 Cancels all communication tasks with the account server waiting for completion that were registered by the process that called this function.
668 Use in a different thread than the one from which the API function that communicates with the server was called.
669
670 The API function that canceled the task returns a <tt>Result</tt> and error code according to the state at that point.
671 Note that if the cancellation is not in time, success may be returned.
672 The failure error code that results from the cancellation does not need to be displayed in the error viewer.
673
674 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
675 @retval ResultSuccess Succeeded.
676 @retval ResultNotInitialized Indicates that the account library has not been initialized.
677 */
678 Result Cancel( void );
679
680
681 //! @}
682 //! @name Getting Error Codes
683 //! @{
684
685 /*!
686 @brief Gets error codes to display to the user.
687
688 Pass the value acquired from this function to the error viewer to display the error.
689
690 The results from each API function are handled based on <tt>nn::Result</tt>. Do not branch processes using the values obtained from this function.
691
692 @param[in] result Specifies the <tt>nn::Result</tt> returned by the account library.
693
694 @return Returns the error code as a seven-digit decimal number.
695 Returns <tt>ACT_ERROR_CODE_UNKNOWN</tt> if the account library has not been initialized, or if it is passed a success or <tt>nn::Result</tt> that was not returned by the account library.
696 */
697 u32 GetErrorCode( const Result& result );
698
699 //! @}
700 //! @name Generating UUIDs
701 //! @{
702
703 /*!
704 @brief Generates a new UUID.
705
706 This function can be used to generate a UUID when you want to assign a unique identifier to data or objects that are created by the application as needed.
707
708 The UUID obtained by this function conforms to RFC 4122 version 1, but the ID format can be changed within a scope that maintains its uniqueness.
709 Each of these IDs is intended to serve as a single, complete ID. Please do not use parts of the IDs for purposes such as time or device identifiers.
710
711 If the function fails, the value set in the buffer is undefined.
712
713 @param[out] pUuid Specifies an out pointer to the buffer that stores the generated UUID.
714
715 @return Returns the result of the function. If the result is used for branching, follow the method described in @ref nn_act_communication_errorhandling "Error Handling".
716 @retval ResultSuccess Succeeded.
717 @retval ResultNotInitialized Indicates that the account library has not been initialized.
718 @retval ResultInvalidPointer Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
719
720 */
721 Result GenerateUuid( ACTUuid* pUuid );
722
723
724 //! @}
725
726 //! @}
727
728 }
729 }
730
731 #endif
732
733
734 #endif // NN_ACT_API_H_
735