nn/act/act_Api.h

/*---------------------------------------------------------------------------*

Copyright (C) Nintendo.  All rights reserved.

These coded instructions, statements, and computer programs contain
proprietary information of Nintendo of America Inc. and/or Nintendo
Company Ltd., and are protected by Federal copyright law.  They may
not be disclosed to third parties or copied or duplicated in any form,
in whole or in part, without the prior written consent of Nintendo.

 *---------------------------------------------------------------------------*/

#ifndef NN_ACT_API_H_
#define NN_ACT_API_H_


#include "act_Types.h"

#include "act_ApiTimeZone.h"
#include "act_ApiParentalControls.h"

#include <nn/acp/acp_IsOverAge.h>


#ifdef __cplusplus

namespace nn
{
namespace act
{

/*!
@ingroup  nn_act
@defgroup nn_act_api  Account (ACT) API
@brief  A list of Account (ACT) library members. (Includes only C++ API members.)
    @{
*/


//! @name  Initializing and Finalizing the Library
//! @{

/*!
@brief  Initializes the account library and prepares it for use.

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.

@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".
@retval ResultSuccess  Succeeded.

*/
Result Initialize( void );

/*!
@brief  Finalizes the account library.

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.
<tt>ResultNotInitialized</tt> is returned if this function is called more times than the <tt>@ref nn::act::Initialize</tt> function.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Specifies that the account library is not initialized.
*/
Result Finalize( void );


//! @}
//! @name  Getting Account Slot Information
//! @{

/*!
@brief  Checks whether there is a system account in the specified slot number.

@param[in] slotNo  Specifies the slot number.

@return  Returns <tt>true</tt> if there is an account in the slot, and <tt>false</tt> otherwise.
Also returns <tt>false</tt> when an out-of-bounds slot number is specified or the account library is uninitialized.
*/
bool IsSlotOccupied( u8 slotNo );

/*!
@brief  Gets the number of existing system accounts.

A return value of <tt>n</tt> indicates that there are system accounts in slots <tt>1</tt> through <tt>n</tt>.

@return  Returns the number of existing system accounts.
*/
u8 GetNumOfAccounts( void );


//! @}
//! @name  Getting Current Account Information
//! @{

/*!
@brief  Gets the slot number of the current account.

@return  Returns the slot number of the current account.
*/
u8 GetSlotNo( void );

/*!
@brief  Determines whether the current account is a network account.

@return  Returns <tt>true</tt> if the current account is a network account, and <tt>false</tt> otherwise.
Also returns <tt>false</tt> if called when the account library is uninitialized.
*/
bool IsNetworkAccount( void );

/*!
@brief  Gets the store data for the Mii character of the current account.

Gets the store data for the Mii character that is configured for the current system account.
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.

The Face library is also required in order to use Mii character store data.

If the function fails, the value set in the buffer is undefined.

@param[out] pMiiData  Specifies a pointer to the buffer that stores the Mii character store data.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.

*/
Result GetMii( FFLStoreData* pMiiData );

/*!
@brief  Gets the Mii character name of the current account.

Gets the name of the Mii character that is configured for the current system account.
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.

Use this function to get the Mii character name directly without using the Mii Face library.

The Mii nickname might contain characters that are not supported by the application.
Handle this so that it does not corrupt the screen display or hinder the progress of your application.
For more information, see the Nicknames and Creator Names section in the Wii U Guidelines.

Pass a buffer with at least as many elements as <tt>ACT_MII_NAME_SIZE</tt> to <var>pMiiName</var>.

If the function fails, the value set in the buffer is undefined.

@param[out] pMiiName  Specifies a pointer to the buffer that stores the name of the Mii character.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultAccountNotFound  Indicates that the system account was not found in the specified slot.

*/
Result GetMiiName( char16* pMiiName );

/*!
@brief  Gets the country setting for the current account.

Gets the country setting of the Nintendo Network Account linked to the current account in ISO 3166-1 alpha-2 format.
Note that this function does not trigger any communication because it retrieves the value from the local cache.

Pass a pointer to a buffer at least as big as <tt>ACT_COUNTRY_SIZE</tt> to <var>pCountry</var>.

When it is not a network account, the function succeeds and a blank string is copied to <var>pCountry</var>.

If the function fails, the value set in the buffer is undefined.

@param[out] pCountry  Specifies an out pointer to the buffer that stores the country setting.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
*/
Result GetCountry( char* pCountry );

/*!
@brief  Gets the account ID of the current account.

Gets the account ID (Nintendo Network ID) of the Nintendo Network Account that is linked to the current account.
Note that this function does not trigger any communication because it retrieves the value from the local cache.

Pass a pointer in <var>pAccountId</var> to a buffer at least as big as <tt>ACT_ACCOUNT_ID_SIZE</tt>.

When it is not a network account, the function succeeds and a blank string is copied to <var>pAccountId</var>.

If the function fails, the value set in the buffer is undefined.

@param[out] pAccountId  Specifies an out pointer to the buffer that stores the account ID.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
*/
Result GetAccountId( char* pAccountId );

/*!
@brief  Determines whether the current account user is at least the specified age.

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.
This function uses the locally cached value to determine the age, so communication is not triggered.
It is also not affected by manipulation of the system clock by the user.
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.

Nintendo systems calculate the age of the user based on UTC+12 time, regardless of their country or region of residence.
For users in Japan, age is calculated based on 9 P.M. of the day before the date of birth.

If you want to get the age of a user directly, please contact Nintendo support.
Avoid identifying the ages of users through repeated calls to this function.

@param[in] age  Specifies the age to compare.

@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.
Returns <tt>false</tt> if used on a local account.
*/
inline bool IsOverAge( u8 age )
{
    return static_cast<bool>(ACPIsOverAgeEx( age, ACT_SLOT_NO_CURRENT ));
}

/*!
@brief  Gets the principal ID of the current account.

Gets the principal ID of the Nintendo Network Account that is linked to the current account.
Note that this function does not trigger any communication because it retrieves the value from the local cache.

@return  Returns the principal ID of the current account.
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.
*/
u32 GetPrincipalId( void );

/*!
@brief  Gets the residence information for the current account.

Gets the residence information for the Nintendo Network Account that is linked to the current account.
Note that this function does not trigger any communication because it retrieves the value from the local cache.

@return  Returns a 32-bit ID that indicates the residence information for the current account.
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.
*/
u32 GetSimpleAddressId( void );

/*!
@brief  Gets the UUID of the current account.

Gets the UUID of the current system account.

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.
Contact Nintendo support if you want to identify a system account by UUID from multiple titles.

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.
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.

If the function fails, the value set in the buffer is undefined.

@param[out] pUuid  Specifies an out pointer to the buffer that stores the UUID.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.


*/
Result GetUuid( ACTUuid* pUuid );

//! @}
//! @name  Getting Other Account Information
//! @{

/*!
@brief  Gets the slot number for the system account with the specified UUID.

@param[in] uuid  Specifies the UUID.

@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.
Also returns <tt>ACT_INVALID_SLOT_NO</tt> if called when the account library is uninitialized.
*/
u8 GetSlotNoEx( const ACTUuid& uuid );

/*!
@brief  Determines whether the specified system account is a network account.

@param[in] slotNo  Specifies the slot number.

@return  Returns <tt>true</tt> if the system account in the specified slot is a network account, and <tt>false</tt> otherwise.
Also returns <tt>false</tt> if no system account exists in the specified slot or if the account library is uninitialized.
*/
bool IsNetworkAccountEx( u8 slotNo );

/*!
@brief  Gets the Mii character store data for the system account in the specified slot.

Gets the store data for the Mii character that is configured for the system account in the specified slot.
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.

The Mii Face library is also required to use Mii character store data.

If the function fails, the value set in the buffer is undefined.

@param[out] pMiiData  Specifies a pointer to the buffer that stores the Mii character store data.
@param[in] slotNo  Specifies the slot number.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultAccountNotFound  Indicates that the system account was not found in the specified slot.

*/
Result GetMiiEx( FFLStoreData* pMiiData, u8 slotNo );

/*!
@brief  Gets the Mii character name for the system account in the specified slot.

Gets the name of the Mii character that is configured for the system account in the specified slot.
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.

Use this function to get the Mii character name directly, without using the Mii Face library.

The Mii nickname might contain characters that are not supported by the application.
Handle this so that it does not corrupt the screen display or hinder the progress of your application.
For more information, see the Nicknames and Creator Names section in the Wii U Guidelines.

Pass a buffer with at least as many elements as <tt>ACT_MII_NAME_SIZE</tt> to <var>pMiiName</var>.

If the function fails, the value set in the buffer is undefined.

@param[out] pMiiName  Specifies a pointer to the buffer that stores the name of the Mii character.
@param[in] slotNo  Specifies the slot number.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultAccountNotFound  Indicates that the system account was not found in the specified slot.

*/
Result GetMiiNameEx( char16* pMiiName, u8 slotNo );

/*!
@brief  Gets the country setting for the account in the specified slot.

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.
Note that this function does not trigger any communication because it retrieves the value from the local cache.

Pass a pointer to a buffer at least as big as <tt>ACT_COUNTRY_SIZE</tt> to <var>pCountry</var>.

When it is not a network account, the function succeeds and a blank string is copied to <var>pCountry</var>.

If the function fails, the value set in the buffer is undefined.

@param[out] pCountry  Specifies an out pointer to the buffer that stores the country setting.
@param[in] slotNo  Specifies the slot number.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultAccountNotFound  Indicates that the system account was not found in the specified slot.
*/
Result GetCountryEx( char* pCountry, u8 slotNo );

/*!
@brief  Gets the account ID for the account in the specified slot.

Gets the account ID (Nintendo Network ID) of the Nintendo Network Account that is linked to the system account in the specified slot.
Note that this function does not trigger any communication because it retrieves the value from the local cache.

Pass a pointer in <var>pAccountId</var> to a buffer at least as big as <tt>ACT_ACCOUNT_ID_SIZE</tt>.

When it is not a network account, the function succeeds and a blank string is copied to <var>pAccountId</var>.

If the function fails, the value set in the buffer is undefined.

@param[out] pAccountId  Specifies an out pointer to the buffer that stores the account ID.
@param[in] slotNo  Specifies the slot number.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultAccountNotFound  Indicates that the system account was not found in the specified slot.
*/
Result GetAccountIdEx( char* pAccountId, u8 slotNo );

/*!
@brief  Determines whether the account user for the specified slot is at least the specified age.

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.
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.
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.

Nintendo systems calculate the age of the user based on UTC+12 time, regardless of their country or region of residence.
For users in Japan, age is calculated based on 9 P.M. of the day before the date of birth.

If you want to get the age of a user directly, please contact Nintendo support.
Avoid identifying the ages of users through repeated calls to this function.

@param[in] age  Specifies the age to compare.
@param[in] slotNo  Specifies the slot number.

@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.
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.
*/
inline bool IsOverAgeEx( u8 age, u8 slotNo )
{
    return static_cast<bool>(ACPIsOverAgeEx( age, slotNo ));
}

/*!
@brief  Gets the principal ID for the account in the specified slot.

Gets the principal ID of the Nintendo Network Account that is linked to the system account in the specified slot.
Note that this function does not trigger any communication because it retrieves the value from the local cache.

When it is not a network account, the function succeeds and <tt>ACT_INVALID_PRINCIPAL_ID</tt> is copied to <var>pPrincipalId</var>.

@param[out] pPrincipalId  Specifies an out pointer to the buffer that stores the principal ID.
@param[in] slotNo  Specifies the slot number.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultAccountNotFound  Indicates that the system account was not found in the specified slot.
*/
Result GetPrincipalIdEx( u32* pPrincipalId, u8 slotNo );

/*!
@brief  Gets the residence information for the account in the specified slot.

Gets the residence information of the Nintendo Network Account that is linked to the system account in the specified slot.
Note that this function does not trigger any communication because it retrieves the value from the local cache.

When it is not a network account, the function succeeds and <tt>ACT_INVALID_SIMPLE_ADDRESS_ID</tt> is copied to <var>pSimpleAddressId</var>.

If the function fails, the value set in the buffer is undefined.

@param[out] pSimpleAddressId  Specifies an out pointer to the buffer that stores the residence information.
@param[in] slotNo  Specifies the slot number.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultAccountNotFound  Indicates that the system account was not found in the specified slot.
*/
Result GetSimpleAddressIdEx( u32* pSimpleAddressId, u8 slotNo );

/*!
@brief  Gets the UUID of the system account in the specified slot.

Gets the UUID of the system account in the specified slot.
Specify <tt>ACT_SLOT_NO_COMMON</tt> for the slot number to get the UUID assigned to the system instead of the account.

The UUID of the system account is assigned at the time of account creation and does not change until the system account is deleted.
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.
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.
Contact Nintendo support if you want to identify a system account or the system itself by UUIDs from multiple titles.

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.
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.

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.
If this occurs, perform a normal shutdown once after acquiring the initial UUID assigned to the system.
This procedure is effective until the next time the development hardware is initialized, and does not need to be repeated for every development title.

If the function fails, the value set in the buffer is undefined.

@param[out] pUuid  Specifies an out pointer to the buffer that stores the UUID.
@param[in] slotNo  Specifies the slot number.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultAccountNotFound  Indicates that the system account was not found in the specified slot.

*/
Result GetUuidEx( ACTUuid* pUuid, u8 slotNo );


//! @}
//! @name  Getting Service Tokens
//! @{

/*!
@brief  Gets a service token for an independent service.

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.

Unless there are compatibility issues for past titles, we recommend using the <tt>@ref nn::act::AcquireIndependentServiceTokenV2</tt> function.

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.

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.
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.
However, follow all the requirements in Guidelines when canceling parental control.
Configure applications as needed to implement functionality corresponding to the other Parental Controls settings.

For <var>pServiceToken</var>, pass a pointer to a buffer at least as big as <tt>ACT_INDEPENDENT_SERVICE_TOKEN_SIZE</tt>.

This function causes communication with the server, during which time processing is blocked.

If the function fails, the value set in the buffer is undefined.

@param[out] pServiceToken  Specifies an out pointer to the buffer that stores the service token.
@param[in] pClientId  Specifies a pointer to the buffer that stores the client ID for the independent service.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultNotNetworkAccount  Indicates that the account is not a network account.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultInvalidClientId  Indicates that the client ID is not registered on the server.
@retval ResultAuthenticationError  Indicates that authentication failed.


*/
Result AcquireIndependentServiceToken
(
    char*               pServiceToken,
    const char*         pClientId
);

/*!
@brief  Gets a service token for an independent service.

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.

Unless there are compatibility issues for past titles, we recommend using the <tt>@ref nn::act::AcquireIndependentServiceTokenV2</tt> function.

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.

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.
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.
However, follow all the requirements in Guidelines when canceling parental control.
Configure applications as needed to implement functionality corresponding to the other Parental Controls settings.

For <var>pServiceToken</var>, pass a pointer to a buffer at least as big as <tt>ACT_INDEPENDENT_SERVICE_TOKEN_SIZE</tt>.

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.
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.
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.

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.
To obtain service tokens again without using the cache, set <tt>reusableRangeInSeconds</tt> to <tt>0</tt>.

This function sometimes causes communication with the server, during which the function blocks.

If the function fails, the value set in the buffer is undefined.

@param[out] pServiceToken  Specifies an out pointer to the buffer that stores the service token.
@param[in] pClientId  Specifies a pointer to the buffer that stores the client ID for the independent service.
@param[in] reusableRangeInSeconds  Specifies how many seconds ago a cache can have been obtained for a service token and still be valid.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultNotNetworkAccount  Indicates that the account is not a network account.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultInvalidClientId  Indicates that the client ID is not registered on the server.
@retval ResultAuthenticationError  Indicates that authentication failed.


*/
Result AcquireIndependentServiceToken
(
    char*               pServiceToken,
    const char*         pClientId,
    u32                 reusableRangeInSeconds
);

/*!
@brief  Gets a service token for an e-commerce service.

Currently, this function can be used only to implement features for purchasing service items through an independent server.
For more information, see <i>Wii U Overview: E-Commerce</i>.

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.

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.
However, this function does not check other Parental Controls settings such as the <b>Wii U Shopping Services</b> setting.
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.
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.
However, follow all the requirements in Guidelines when suspending Parental Controls.

Pass a pointer to a buffer at least as big as <tt>ACT_INDEPENDENT_SERVICE_TOKEN_SIZE</tt> to <var>pEcServiceToken</var>.

This function causes communication with the server, during which time processing is blocked.

If the function fails, the value set in the buffer is undefined.

@param[out] pEcServiceToken  Specifies an out pointer to the buffer that stores the service token.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultNotNetworkAccount  Indicates that the account is not a network account.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultAuthenticationError  Indicates that authentication failed.

*/
Result AcquireEcServiceToken
(
    char*               pEcServiceToken
);

/*!
@brief  Gets a service token (version 2) for an independent service.

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.

This function's security has been improved over that of the prior token function, <tt>@ref nn::act::AcquireIndependentServiceToken</tt>.
Unless there are compatibility issues for past titles, use this function.

For more information about the use of service tokens, see the Account System Developer's Guide.

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.

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.
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.
However, follow all the requirements in the guidelines when canceling parental control.
Configure applications as needed to implement functionality corresponding to the other <b>Parental Controls</b> settings.

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.
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.
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.

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.
To obtain service tokens again without using the cache, set <tt>reusableRangeInSeconds</tt> to <tt>0</tt>.

This function sometimes causes communication with the server, during which the function blocks.

If the function fails, the value set in the buffer is undefined.

@param[out] pServiceToken  Specifies an out pointer to the buffer that stores the service token.
@param[in] pClientId  Specifies a pointer to the buffer that stores the client ID for the independent service.
@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.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultNotNetworkAccount  Indicates that the account is not a network account.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.
@retval ResultInvalidClientId  Indicates that the client ID is not registered on the server.
@retval ResultAuthenticationError  Indicates that authentication failed.


*/
Result AcquireIndependentServiceTokenV2
(
    ACTServiceTokenV2*  pServiceToken,
    const char*         pClientId,
    u32                 reusableRangeInSeconds = 0
);


/*!
@brief  Cancels communication tasks with the account server that are waiting for completion.

Cancels all communication tasks with the account server waiting for completion that were registered by the process that called this function.
Use in a different thread than the one from which the API function that communicates with the server was called.

The API function that canceled the task returns a <tt>Result</tt> and error code according to the state at that point.
Note that if the cancellation is not in time, success may be returned.
The failure error code that results from the cancellation does not need to be displayed in the error viewer.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
*/
Result Cancel( void );


//! @}
//! @name  Getting Error Codes
//! @{

/*!
@brief  Gets error codes to display to the user.

Pass the value acquired from this function to the error viewer to display the error.

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.

@param[in] result  Specifies the <tt>nn::Result</tt> returned by the account library.

@return  Returns the error code as a seven-digit decimal number.
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.
*/
u32 GetErrorCode( const Result& result );

//! @}
//! @name  Generating UUIDs
//! @{

/*!
@brief  Generates a new UUID.

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.

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.
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.

If the function fails, the value set in the buffer is undefined.

@param[out] pUuid  Specifies an out pointer to the buffer that stores the generated UUID.

@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".
@retval ResultSuccess  Succeeded.
@retval ResultNotInitialized  Indicates that the account library has not been initialized.
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument.

*/
Result GenerateUuid( ACTUuid* pUuid );


//! @}

//! @}

}
}

#endif


#endif  // NN_ACT_API_H_