1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 13 #ifndef NN_TEMP_H_ 14 #define NN_TEMP_H_ 15 16 /*! 17 @defgroup nn_temp Temporary Directory (TEMP) Library 18 @brief Library for creating a temporary directory. 19 20 @section nn_temp_overview Overview 21 This library provides features that allow the application to use free space in system memory or USB storage to temporarily store data. @n 22 23 @subsection nn_temp_freespace Restricting the Amount of Data 24 You can use all of the free space in storage as a temporary directory. However, if there is no free space at all, you cannot use this feature. @n 25 You must include a sequence that covers the case that there is no free space at all when using this feature. @n 26 You cannot link and use the free space in several different storage locations as a single temporary directory. 27 28 @subsection nn_temp_ipc Sharing Data Between Processes 29 The "owner" process that creates a temporary directory can give other "referrer" processes access to any of the data in the directory. @n 30 You could use this feature to pass data from the game application to an overlay application, for example. @n 31 The owner process can also configure access permissions for specific files and subdirectories in the temporary directory independently. 32 33 @subsection nn_temp_storage Selecting Storage 34 The <tt>TEMP</tt> library determines which storage area to use when creating the temporary directory. @n 35 Have the application specify whether to prioritize access speed or the amount of free space when selecting a storage region to use when creating the temporary directory. @n 36 As a result, the application does not have to include handling for the possibility of the temporary directory being created in the wrong storage region. @n 37 The location of the temporary directory has nothing to do with the storage region where the application is installed or where the application's save data is saved. 38 39 @subsection nn_temp_lifespan Lifespan 40 The temporary directory exists only while the application is running, so the data is guaranteed not to exist at any other time. @n 41 The data in the transaction journal is also deleted. 42 43 @section nn_temp_usage_note Notes on Using the TEMP Library 44 45 @subsection nn_temp_capacity_shortage Insufficient Free Space 46 Make sure that the application continues to run smoothly even if a temporary directory could not be created because there was insufficient free space. @n 47 The amount of free space in storage varies from user to user. @n 48 If insufficient free space is detected, you can either notify the user using the error viewer (see below) or allow the application to continue running without using the temporary directory feature. 49 50 @subsection nn_temp_excessive_access High-Frequency Access to Storage Is Prohibited 51 Do not access the temporary directory with an extremely high frequency because it can decrease the lifespan of storage. @n 52 Be especially careful when leaving the temporary directory open continuously while the application is running. (For example, by continuously recording a gameplay video to the temporary directory.)@n 53 For more information about the acceptable range for storage access frequency, see the File System > Access Frequency section in the Wii U Guidelines. 54 55 @subsection nn_temp_speed_dependency Processes That Depend on Access Speed Are Prohibited 56 Do not implement processes that depend directly on the speed of access to storage. @n 57 The actual speed of access to the temporary directory varies depending on the type of storage device the user is using. @n 58 For more information about storage access speed, see the File System > Programs that Depend on Access Speed section in the Wii U Guidelines. 59 60 @section nn_temp_error_handling How to Report Errors to the Error Viewer 61 62 @subsection nn_temp_error_create_storage_full ERROR_CODE_TEMP_CREATE_STORAGE_FULL or 1660100 63 If there is an insufficient free space error when temporary data is created (<tt>TEMP_STATUS_STORAGE_FULL</tt>), either <tt>1660100</tt> or <tt>ERROR_CODE_TEMP_CREATE_STORAGE_FULL</tt> can be passed to the error viewer for display. 64 This error can occur in the following situations. 65 @li <tt>TEMP_STATUS_STORAGE_FULL</tt> is returned from <tt>TEMPCreateAndInitTempDir</tt>. 66 @li <tt>TEMP_STATUS_STORAGE_FULL</tt> is returned from <tt>TEMPOpenFile(Async)</tt> or <tt>TEMPMakeDir(Async)</tt>. 67 @li <tt>FS_STATUS_STORAGE_FULL</tt> is returned when <tt>FSAppendFile</tt> or <tt>FSWriteFile</tt> is run on the file opened by <tt>TEMPOpenFile</tt>. 68 @subsection nn_temp_error_modify_storage_full ERROR_CODE_TEMP_MODIFY_STORAGE_FULL or 1660200 69 If there is an insufficient free space error when temporary data is updated (<tt>TEMP_STATUS_STORAGE_FULL</tt>), either <tt>1660200</tt> or <tt>ERROR_CODE_TEMP_MODIFY_STORAGE_FULL</tt> can be passed to the error viewer for display. 70 This error can occur in the following situations. 71 @li <tt>TEMP_STATUS_STORAGE_FULL</tt> is returned from <tt>TEMPRemove(Async)</tt>, <tt>TEMPRename(Async)</tt>, or <tt>TEMPChangeOthersMode(Async)</tt>. 72 @{ 73 74 @defgroup nn_temp_status Temporary Directory (TEMP) Status 75 @brief A list of <tt>Status</tt> values used in the <tt>TEMP</tt> library. 76 77 78 */ 79 80 /*! 81 @} 82 */ 83 84 #include <nn/temp/temp_Api.h> 85 #include <nn/temp/temp_Types.h> 86 87 #endif // NN_TEMP_H_ 88