/*---------------------------------------------------------------------------* 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 #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 @ref nn::act::Finalize 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 @ref nn::act::Initialize function is called multiple times, this function must be called an equal number of times to completely finalize the account library. ResultNotInitialized is returned if this function is called more times than the @ref nn::act::Initialize 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 true if there is an account in the slot, and false otherwise. Also returns false 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 n indicates that there are system accounts in slots 1 through n. @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 true if the current account is a network account, and false otherwise. Also returns false 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 NULL 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 ACT_MII_NAME_SIZE to pMiiName. 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 NULL 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 ACT_COUNTRY_SIZE to pCountry. When it is not a network account, the function succeeds and a blank string is copied to pCountry. 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 NULL 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 pAccountId to a buffer at least as big as ACT_ACCOUNT_ID_SIZE. When it is not a network account, the function succeeds and a blank string is copied to pAccountId. 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 NULL 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 false 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 true if the user of the current account is the specified age or older, and returns false if the user is younger than the specified age. Returns false if used on a local account. */ inline bool IsOverAge( u8 age ) { return static_cast(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, ACT_INVALID_PRINCIPAL_ID 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, ACT_INVALID_SIMPLE_ADDRESS_ID 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 NULL 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 ACT_INVALID_SLOT_NO if no such account exists. Also returns ACT_INVALID_SLOT_NO 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 true if the system account in the specified slot is a network account, and false otherwise. Also returns false 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 NULL 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 ACT_MII_NAME_SIZE to pMiiName. 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 NULL 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 ACT_COUNTRY_SIZE to pCountry. When it is not a network account, the function succeeds and a blank string is copied to pCountry. 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 NULL 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 pAccountId to a buffer at least as big as ACT_ACCOUNT_ID_SIZE. When it is not a network account, the function succeeds and a blank string is copied to pAccountId. 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 NULL 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 false 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 true if the user of the system account in the specified slot is the specified age or older, and returns false if the user is not of the specified age. Also returns false 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(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 ACT_INVALID_PRINCIPAL_ID is copied to pPrincipalId. @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 NULL 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 ACT_INVALID_SIMPLE_ADDRESS_ID is copied to pSimpleAddressId. 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 NULL 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 ACT_SLOT_NO_COMMON 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 NULL 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 @ref nn::act::AcquireIndependentServiceTokenV2 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 Online Interaction in Games 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 @ref nn::act::EnableParentalControlCheck 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 pServiceToken, pass a pointer to a buffer at least as big as ACT_INDEPENDENT_SERVICE_TOKEN_SIZE. 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 NULL 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 @ref nn::act::AcquireIndependentServiceTokenV2 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 Online Interaction in Games 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 @ref nn::act::EnableParentalControlCheck 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 pServiceToken, pass a pointer to a buffer at least as big as ACT_INDEPENDENT_SERVICE_TOKEN_SIZE. Note that the lifetime specified by reusableRangeInSeconds 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 reusableRangeInSeconds 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 0 for reusableRangeInSeconds 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 reusableRangeInSeconds to 0. 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 NULL 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 Wii U Overview: E-Commerce. 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 Online Interaction in Games 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 Wii U Shopping Services setting. To provide features corresponding to Parental Controls settings other than the Online Interaction in Games 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 @ref nn::act::EnableParentalControlCheck 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 ACT_INDEPENDENT_SERVICE_TOKEN_SIZE to pEcServiceToken. 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 NULL 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, @ref nn::act::AcquireIndependentServiceToken. 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 Online Interaction in Games 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 @ref nn::act::EnableParentalControlCheck 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 Parental Controls settings. Note that the lifetime specified by reusableRangeInSeconds 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 reusableRangeInSeconds 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 0 for reusableRangeInSeconds 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 reusableRangeInSeconds to 0. 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 NULL 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 Result 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 nn::Result. Do not branch processes using the values obtained from this function. @param[in] result Specifies the nn::Result returned by the account library. @return Returns the error code as a seven-digit decimal number. Returns ACT_ERROR_CODE_UNKNOWN if the account library has not been initialized, or if it is passed a success or nn::Result 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 NULL pointer) was passed as an argument. */ Result GenerateUuid( ACTUuid* pUuid ); //! @} //! @} } } #endif #endif // NN_ACT_API_H_