xref: /CafeSDK-2.12.13/system/include/nn/nfp/nfp_Api.h

/*---------------------------------------------------------------------------*
  Project:  Cafe
  File:     nfp_Api.h

  Copyright (C) 2014 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_NFP_API_H_
#define NN_NFP_API_H_

#include <cafe/sysapp.h>

#include <nn/Result.h>
#include <nn/nfp/nfp_Types.h>

namespace nn {
namespace nfp {

/*!
    @ingroup    nn_nfp
    @defgroup   nn_nfp_api  Nintendo Figurine Platform (NFP) API
    @brief A list of Nintendo Figurine Platform (NFP) library members. (Includes only C++ API members.)
    @{
*/

/*!
      @name Initialization and Finalization

      @{
*/

/*!
@brief Initializes the Nintendo Figurine Platform (NFP) library.

@retval ResultSuccess  Initialization successful.
@retval ResultInvalidOperation  The library is already initialized.
@retval ResultOperationFailed  Initialization failed.
@retval ResultNoBackupFile  There is no backup file.

@details This function must be called before using any of the features in the NFP library.
The initialization process takes approximately one second.

Backup data is automatically created the first time the NFP library is initialized on the console where the application is running.
The save data creation process takes approximately five seconds.

@sa Finalize

*/
nn::Result Initialize( void );

/*!
@brief Finalizes the Nintendo Figurine Platform (NFP) library.

@retval ResultSuccess  Finalized successfully.
@retval ResultInvalidOperation  Already finalized.

@details Call this function when you are done using the NFP library.

If this function is called while a tag is detected, the Deactivate event is signaled.

@sa Initialize
*/
nn::Result Finalize( void );

/*!
      @}
 */

/*!
@name RW Mode API
      @{

*/

/*!
@brief Starts detecting a tag.

@retval ResultSuccess  Started detecting the tag.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultOperationFailed  Unable to start tag detection. The console has been disconnected from the Wii U GamePad (DRC), or the communication environment is poor.

@details Before using this function, call <tt>@ref SetActivateEvent</tt> and <tt>@ref SetDeactivateEvent</tt> to get the library ready to receive tag detection and tag loss events.

@sa SetActivateEvent
@sa SetDeactivateEvent
@sa StopDetection

*/
nn::Result StartDetection( void );

/*!
@brief Stops detecting a tag.

@retval ResultSuccess  Stopped detecting the tag successfully.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultOperationFailed  Unable to stop tag detection. The signal between the Wii U GamePad (DRC) and console may be weak.

@details If this function is called while a tag is detected, the Deactivate event is signaled.

If it is called while a tag is mounted, <tt>@ref Unmount</tt> is called automatically.

@sa StartDetection
*/
nn::Result StopDetection( void );

/*!
@brief Mounts a tag. This function returns <tt>@ref ResultNotSupported</tt> for non-NFP NOFT tags.

@retval ResultSuccess  Mount succeeded.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultNotSupported  Not an NFP NOFT tag. Check the tag being used.
@retval ResultNeedRetry  An error occurred in the mount process. Remount the tag.
@retval ResultNeedRestore  The tag data is corrupted. The tag must be restored.
@retval ResultNeedFormat  The tag data is corrupted but there is no backup data. The tag must be reformatted.
@retval ResultTagNotFound  Target tag not found. The tag may have been replaced with another tag during the write process.
@retval ResultInvalidFormatVersion  Unsupported tag version. Notify the user that the tag is not supported.
@retval ResultBackupError  Failed to access the backup file.

@details This function must be called while a tag is being detected before any API functions that require the tag to be mounted can be called.

The backup data is updated if the tag is being read the first time by the tag being mounted, or if the tag was overwritten using another console.

@sa GetNfpCommonInfo
@sa GetNfpRegisterInfo
@sa Flush
@sa OpenApplicationArea
@sa ReadApplicationArea
@sa WriteApplicationArea
@sa Unmount


*/
nn::Result Mount( void );

/*!
@brief Mounts a tag in a state where only the ROM region can be accessed.
This function returns <tt>@ref ResultNotSupported</tt> for non-NFP NOFT tags.

@retval ResultSuccess  Mount succeeded.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultNotSupported  Not an NFP NOFT tag. Check the tag being used.
@retval ResultTagNotFound  Target tag not found. The tag may have been replaced with another tag during the write process.
@retval ResultInvalidFormatVersion  Unsupported tag version. Notify the user that the tag is not supported.

@details The behavior of this function has the following differences when compared to <tt>@ref Mount</tt>.
@li Can only access the ROM region (<tt>@ref GetNfpRomInfo</tt>, <tt>@ref GetTagInfo</tt>).
@li Can be called even if the tag data is corrupted (<tt>@ref Mount</tt> returns <tt>@ref ResultNeedRestore</tt> or <tt>@ref ResultNeedFormat</tt>).
@li Does not update backup data.

@sa GetNfpRomInfo
@sa Unmount
*/
nn::Result MountRom( void );

/*!
@brief Unmounts a tag.

@retval ResultSuccess  Unmounted successfully.
@retval ResultInvalidOperation  The library is not in the correct state.

@details When a tag is unmounted, API functions that require a mounted tag can no longer be used.
Call the <tt>@ref Mount</tt> function again to use API functions that require a mounted tag.

The tag is automatically unmounted if <tt>@ref StopDetection</tt> is called or the tag is lost (deactivate) without unmounting it.

@sa     Mount

*/
nn::Result Unmount( void );

/*!
@brief Enables access to the application area.

@param[in] accessID  The ID to use to access the application area.

@retval ResultSuccess  Access to the application area was enabled.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultAccessIdMisMatch  Cannot access the application area because the access IDs do not match.
@retval ResultNeedCreate  No application area. The application area must be created.
@retval ResultNotSupported  Unsupported format.

@sa Mount
@sa ReadApplicationArea
@sa WriteApplicationArea
*/
nn::Result OpenApplicationArea( u32 accessID );

/*!
@brief Reads the data in the application area on a tag.

@param[out] pReadBuf  A buffer to load the data into.
@param[in] readSize  The size of the data to read.

@retval ResultSuccess  Read successful.
@retval ResultInvalidArgument  Invalid argument.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.

@details To use this API function, you must first mount the tag and call <tt>@ref OpenApplicationArea</tt>.

Use <tt>@ref CommonInfo::applicationAreaSize</tt> for the maximum size of data that can be read.

@sa CommonInfo
@sa GetNfpCommonInfo
@sa Mount
@sa OpenApplicationArea

*/
nn::Result ReadApplicationArea( void* pReadBuf, u32 readSize );

/*!
@brief Writes data to the application area on a tag.

@param[in] pWriteBuf  The data to write.
@param[in] writeSize  The size of the data to write.
@param[in] tagId  The UID of the tag to write the data to. Use the <tt>@ref TagId</tt> that is retrieved from the <tt>@ref GetTagInfo</tt> function.

@retval ResultSuccess  Read successful.
@retval ResultInvalidArgument  Invalid argument. Or, the size of the data to write exceeds the size of the application area.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultUidMisMatch  The specified UID does not match the tag's UID.

@details To use this API function, you must first mount the tag and call <tt>@ref OpenApplicationArea</tt>.

If the size of the data to write is smaller than <tt>@ref CommonInfo::applicationAreaSize</tt>, the remaining space is filled with random numbers.

You must call <tt>@ref Flush</tt> to finalize the write operation.

@sa Flush
@sa Mount
@sa OpenApplicationArea

*/
nn::Result WriteApplicationArea( const void* pWriteBuf,
                                 u32 writeSize,
                                 const TagId& tagId );

/*!
@brief      Writes the data in an internal buffer to the tag.
The data is not actually written to the tag until this function is called.
@retval ResultSuccess           Data written successfully.
@retval     ResultInvalidOperation  The library is not in the correct state.
@retval ResultNotSupported      Non-NFP NOFT tag, or invalid tag format. Check the tag being used.
@retval ResultNeedRetry         Failed to write the data. Try writing the data again.
@retval ResultTimeOutError      The write process timed out. Try writing the data again. Use the <tt>@ref ResultNeedRetry</tt> function to handle this result.
@retval ResultTagNotFound       Target tag not found. The tag may have been replaced with another tag during the write process.
@retval ResultOperationFailed   An error occurred while writing to the tag. The tag data may have been corrupted.
@retval ResultBackupError       Failed to access the backup file.
@details    This function writes data to the tag and to the backup file.
The write process takes at least one to two seconds.
When writing to a tag, display a message or animation that lets the user know a write operation is in progress.
@note       The write time might take longer depending on system load and whether other files are being accessed.
@sa     WriteApplicationArea





*/
nn::Result Flush( void );

/*!
@brief Formats a corrupted tag and restores the tag data using the backup data.

@retval ResultSuccess  Data restored successfully.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultNotSupported  Non-NFP NOFT tag, or invalid tag format. Check the tag being used.
@retval ResultNotBroken  Tag data does not need to be restored because it is not corrupted.
@retval ResultNeedRetry  An error occurred during the restore process. Call this function again.
@retval ResultTimeOutError  The write process timed out. Try writing the data again. Use the <tt>@ref ResultNeedRetry</tt> function to handle this result.
@retval ResultTagNotFound  Target tag not found. The tag may have been replaced with another tag during the write process.
@retval ResultOperationFailed  An error occurred while writing to the tag. The tag data may not have been restored correctly.
@retval ResultBackupError  Failed to access the backup file.

@details Tag data must be restored if it gets corrupted for any reason. @n
This function formats the tag and then writes the backup data to the tag.

The <tt>@ref Flush</tt> function is also executed when a tag is restored.

@sa Flush
@sa Mount
*/
nn::Result Restore( void );

/*!
@brief Creates the application area on a tag.
The application area must be created before using a blank tag for the first time.

@param[in] createInfo  The application area creation info. Use the <tt>@ref InitializeCreateInfo</tt> function to initialize the data before passing it to this function.

@retval ResultSuccess  Creation successful.
@retval ResultInvalidArgument  Invalid argument.
@retval ResultInvalidPointer  An invalid pointer to the creation info was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultNotSupported  Non-NFP NOFT tag, or invalid tag format. Check the tag being used.
@retval ResultAlreadyCreated  The application area has already been created.
@retval ResultNeedRetry  An error occurred during creation. Call this function again.
@retval ResultTimeOutError  The write process timed out. Call this function again. Use the <tt>@ref ResultNeedRetry</tt> function to handle this result.
@retval ResultTagNotFound  Target tag not found. The tag may have been replaced with another tag during the write process.
@retval ResultOperationFailed  An error occurred while writing to the tag. The tag data may have been corrupted.
@retval ResultBackupError  Failed to access the backup file.

@details You must call the <tt>@ref InitializeCreateInfo</tt> function to initialize the argument before passing it to this function.

To call this function, the tag must be mounted and not currently have an application area.
Use the <tt>@ref OpenApplicationArea</tt> function to check whether the tag has an application area.

The <tt>@ref Flush</tt> function is also executed when the application area is created.

@sa ApplicationAreaCreateInfo
@sa Flush
@sa InitializeCreateInfo
@sa Mount
@sa OpenApplicationArea
*/
nn::Result CreateApplicationArea( const ApplicationAreaCreateInfo& createInfo );

/*!
@brief Gets tag information.

@param[out] pTagInfo  Pointer to the <tt>@ref TagInfo</tt> object in which the retrieved data was stored.

@retval ResultSuccess  Obtained successfully.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultTagNotFound  Target tag not found. The tag may have been replaced with another tag during the write process.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultNotSupported  Not an NFP NOFT tag. Check the tag being used.

@details Gets the tag ID and tag type.
Use this function to get the tag ID that is used in functions such as <tt>@ref WriteApplicationArea</tt>.

A tag must be detected to call this API function.

This API function gets unique value for each tag.

@sa TagInfo
@sa WriteApplicationArea
*/
nn::Result GetTagInfo( TagInfo* pTagInfo );

/*!
@brief Gets initial NFP tag registration info.

@param[out] pRegData  Pointer to the <tt>@ref RegisterInfo</tt> object in which the retrieved data was stored.

@retval ResultSuccess  Obtained successfully.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultNeedRegister  The tag has not been registered. The tag must be registered in <tt>Cabinet</tt>.
@retval ResultNotSupported  Non-NFP NOFT tag, or invalid tag format. Check the tag being used.

@details A tag must be mounted to call this API function.

Tag nicknames may sometimes include characters that are not supported in the application.
When that happens, you must handle it such that the screen display is not adversely affected and there are no hindrances to the application's progress.
For more details, see the section on Nicknames and Creator Names in the Wii U Guidelines.

@sa Mount
@sa RegisterInfo
*/
nn::Result GetNfpRegisterInfo( RegisterInfo* pRegData );

/*!
@brief Gets the data in the common region on the NFP tag.

@param[out] pCommonData  Pointer to the <tt> @ref CommonInfo</tt> object in which the retrieved data was stored.

@retval ResultSuccess  Obtained successfully.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.
@retval ResultNotSupported  Non-NFP NOFT tag, or invalid tag format. Check the tag being used.

@details A tag must be mounted to call this API function.

Use <tt>@ref CommonInfo::applicationAreaSize</tt> to get the application-specific region size used by the <tt>@ref ReadApplicationArea</tt> and <tt>@ref WriteApplicationArea</tt> function.

@sa CommonInfo
@sa Mount


*/
nn::Result GetNfpCommonInfo( CommonInfo* pCommonData );

/*!
@brief Gets the information in the common region of the tag.

@param[out] pRomInfo  Stores the ROM information.

@retval ResultSuccess  Obtained successfully.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.

@details The <tt>@ref Mount</tt> or <tt>@ref MountRom</tt> function must be called before calling this API function.

@sa RomInfo
@sa Mount
@sa MountRom
*/
nn::Result GetNfpRomInfo( RomInfo* pRomInfo );

/*!
      @}
 */

/*!
@brief Gets the error code that is shown to users from the specified <tt>nn::Result</tt> object.

@param[in] result  The <tt>nn::Result</tt> instance to get the error code from. Specify a <tt>nn::Result</tt> returned by the NFP library.

@return Returns the error code as a seven-digit decimal number (168XXXX).
If <tt>nn::ResultSuccess</tt> or a <tt>nn::Result</tt> instance not from the NFP library is passed as an argument, this function returns <tt>@ref nn::nfp::ERROR_CODE_UNKNOWN</tt>.

@details Use this API function to get the error code that is passed to the error viewer.

*/
u32 GetErrorCode( const nn::Result& result );

/*!
@brief Gets the state of the NFP library.

@return Returns the current state of the NFP library.

@sa NfpState
*/
NfpState GetNfpState( void );

/*!
@brief Sets an event indicating that a tag was detected (Activate).

@param[in,out] pEvent  Specifies an event to use for tag detection notification.

@retval ResultSuccess  Event set successfully.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.

@details When a tag is detected, a notification with the event specified in this function is sent.

The event is initialized in auto-mode (<tt>OS_EVENT_AUTO</tt>) in this function. You do not need to call <tt>OSInitEvent[Ex]</tt> in advance.

This API function can be used when the library state is <tt>@ref INIT</tt>.

@sa SetDeactivateEvent
*/
nn::Result SetActivateEvent( OSEvent* pEvent );

/*!
@brief Sets an event indicating that a tag was lost (Deactivate).

@param[in,out] pEvent  Sets an event to use for the notification for when the tag is lost.

@retval ResultSuccess  Event set successfully.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.

@details When a tag that has been detected is removed from the reader, a notification with the event specified in this function is sent.

The event is initialized in auto-mode (<tt>OS_EVENT_AUTO</tt>) in this function. You do not need to call <tt>OSInitEvent[Ex]</tt> in advance.

This API function can be used when the library state is <tt>@ref INIT</tt>.

@sa SetActivateEvent
*/
nn::Result SetDeactivateEvent( OSEvent* pEvent );

/*!
@brief Gets the connection status for the tag.

@param[out] pConnectionStatus  A pointer to the <tt>ConnectionStatus</tt> object in which the retrieved data was stored.

@retval ResultSuccess  Obtained successfully.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.

@sa ConnectionStatus
*/
nn::Result GetConnectionStatus( ConnectionStatus* pConnectionStatus );

/*!
@brief Initializes application area creation info.

@param[out] pCreateInfo  The application area creation info.

@retval ResultSuccess  Initialization successful.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.
@retval ResultInvalidOperation  The library is not in the correct state.

@details After using this function to initialize the creation info, set the members to the necessary values before passing the creation info to the <tt>@ref CreateApplicationArea</tt> function.

@sa ApplicationAreaCreateInfo
@sa CreateApplicationArea
*/
nn::Result InitializeCreateInfo( ApplicationAreaCreateInfo* pCreateInfo );


/*!
      @name amiibo Settings API
      @{
 */

/*!
@brief  Initializes the structure that is passed when calling amiibo Settings.

@param[out]  pArgs  The structure to initialize.

@details The argument that is passed to the <tt>@ref SwitchToAmiiboSettings</tt> function must be initialized using this API function beforehand.

@retval ResultSuccess  Indicates that initialization succeeded.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result.

@sa SwitchToAmiiboSettings

*/
nn::Result InitializeAmiiboSettingsArgsIn( AmiiboSettingsArgsIn* pArgs );

/*!
@brief Issues a process transition (application jump) request to go to amiibo Settings.

@param[in] args  The arguments to pass to the process. Must be initialized by <tt>@ref InitializeAmiiboSettingsArgsIn</tt> in advance.
@param[in] pAnchor  The anchor string received by the application when control returns from the jump. You can specify a value up to <tt>OS_ARGS_SIZE - 1</tt> bytes.
@param[in] anchorSize  The size of the data in <tt><em>pAnchor</em></tt> (in bytes). Specify a size that includes a string terminator.

@retval ResultSuccess  Issued the transition request.
@retval ResultInvalidArgument  Invalid argument.
@retval ResultOperationFailed  Failed to issue the transition request. (This never occurs in the production environment.)

@details After the process transition request has been issued, <tt>@ref Finalize</tt> is called on the NFP library and the system prepares for the process transition.

After preparations are complete, a <tt>PROCUI_MESSAGE_RELEASE</tt> message is issued.
When your application receives this message, release the foreground.
For more information, see the ProcUI Library section of the Cafe SDK Reference Manual.

After the process transition is complete, the current process moves to the background.

@note By specifying an anchor string, you can determine whether control was returned by the application to which it jumped.
If control returned from the application that was jumped to, you can get the anchor string by calling the <tt>SYSGetArguments</tt> function with <tt>SYS_ARG_ID_ANCHOR</tt> specified.
The anchor string can be omitted, but specify it for applications that use multiple overlay applications (such as Miiverse) to determine whether control was returned by amiibo Settings.

@note When this API function is called and the <tt>@ref Finalize</tt> function is called on the NFP library, any registered tag detection/loss events are cleared.

@attention Do not call this API function from the background.

@sa InitializeAmiiboSettingsArgsIn

*/
nn::Result SwitchToAmiiboSettings( const AmiiboSettingsArgsIn& args,
                                   const char* pAnchor,
                                   u32 anchorSize );

/*!
@overload

@details Use this API function for cases where an anchor string is unnecessary.

This API function is handled the same as <tt>@ref SwitchToAmiiboSettings</tt> with <tt>NULL</tt> specified for <tt><em>pAnchor</em></tt> and <tt>0</tt> specified for <tt><em>anchorSize</em></tt>.

@attention Do not call this API function from the background.

*/
nn::Result SwitchToAmiiboSettings( const AmiiboSettingsArgsIn& args );

/*!
@brief Gets the return value from amiibo Settings.

@param[out] pResult  Stores the return value.
@param[in] resultDataBlock  Specifies the data block of the result data retrieved with the <tt>SYSGetArguments</tt> function. To get the result data, call the <tt>SYSGetArguments</tt> function with <tt>SYS_ARG_ID_RESULT</tt> specified.

@retval ResultSuccess  Obtained successfully.
@retval ResultInvalidPointer  An invalid pointer was specified. Use the <tt>@ref ResultInvalidArgument</tt> function to handle this result. If this result is returned, the <tt>@ref Initialize</tt> function of the NFP library is not called.
@retval ResultNoData  No data can be retrieved because the result data is not from amiibo Settings.

@details This function receives the result data (<tt>_blk</tt> member of the <tt>SysArgSlot</tt> structure) that is returned when <tt>SYS_ARG_ID_RESULT</tt> is specified in the <tt>SYSGetArguments</tt> function, and stores the return value only if it is in a format that can be retrieved as an <tt>@ref AmiiboSettingsResult</tt> object.
However, if the previous application was not amiibo Settings but returned a value in a format that can be recognized as an <tt>@ref AmiiboSettingsResult</tt> object, an unexpected value could be retrieved.

If your application calls multiple overlay applications (such as Miiverse), call the <tt>SYSGetArguments</tt> function in advance and check the anchor string to make sure control was returned from amiibo Settings before calling this function.

The <tt>@ref Initialize</tt> function is automatically called on the NFP library when this API function is called.
This function takes about one second to execute. we recommend displaying an animation or something similar when calling this function to avoid any stuttering or pauses in the application.

@note The <tt>@ref Initialize</tt> function is automatically called on the NFP library, so the library cannot be restored to the state prior to the process transition.
Any registered events are cleared and must be reregistered using <tt>@ref SetActivateEvent</tt> and <tt>@ref SetDeactivateEvent</tt>.






*/
nn::Result GetAmiiboSettingsResult( AmiiboSettingsResult* pResult,
                                    const SysArgDataBlock& resultDataBlock );

/*!
      @}
 */

/*!
    @}
*/


}  // namespace nfp
}  // namespace nn

#endif // ifndef NN_NFP_API_H_