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 execution 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 execution 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 execution 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 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 <span class="argument">pMiiName</span>.

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

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

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 execution 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, and use the Wii U Application Configuration Tool and other tools to set the Unique ID for your application as registered.

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 are always stored in system cache, and this function will return a cached service token without performing communications if one exists that was obtained less than <var>reusableRangeInSeconds</var> seconds ago.
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 execution 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 execution 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 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 execution 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.
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 generated UUID.

@return Returns the execution 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_