FSResult

Definition


#include <nitro/fs.h>

typedef	enum FSResult
{
    FS_RESULT_SUCCESS = 0,
    FS_RESULT_FAILURE = 1,
    FS_RESULT_BUSY = 2,
    FS_RESULT_CANCELED = 3,
    FS_RESULT_UNSUPPORTED = 4,
    FS_RESULT_ERROR = 5,
    FS_RESULT_INVALID_PARAMETER = 6,
    FS_RESULT_NO_MORE_RESOURCE = 7,
    FS_RESULT_ALREADY_DONE = 8,
    FS_RESULT_PERMISSION_DENIED = 9,
    FS_RESULT_MEDIA_FATAL = 10,
    FS_RESULT_NO_ENTRY = 11,
    FS_RESULT_MEDIA_NOTHING = 12,
    FS_RESULT_MEDIA_UNKNOWN = 13,
    FS_RESULT_BAD_FORMAT = 14,

    FS_RESULT_PROC_ASYNC = 256,
    FS_RESULT_PROC_DEFAULT,
    FS_RESULT_PROC_UNKNOWN,

    FS_RESULT_CANCELLED = FS_RESULT_CANCELED
}
FSResult;

Description

These enumerator types represent the results of the file system API and the user procedures of the archive.
They are defined as follows.

The following values can be returned as results from the FS library functions.
FS_RESULT_SUCCESS Indicates success as a result of the function's correct processing.
Example: Suppose that FS_ReadFile attempts to read 100 bytes of data, but reaches the end of the file after only reading 50 bytes. This is normal behavior and is recorded as successful.
FS_RESULT_FAILURE Indicates failure as a result of the function's correct processing.
Example: This indicates a failure as one of the expected return values for the process when you have read to the end using the FS_ReadDir function.
FS_RESULT_BUSY Indicates that the current command is busy.
Strictly speaking, this is not an error because the operation is incomplete. However, we have included this with the errors for the sake of convenience.
FS_RESULT_CANCELED Indicates that the command was canceled.

There are two types of cancels: (1) explicit command cancels by the user, and (2) forced cancel when the archive is unloaded.
FS_RESULT_UNSUPPORTED Indicates that the archive is not supported by the specified command.
This error occurs when the archive that ignores certain commands explicitly returns this as a return value of a user procedure.
If this error gets returned unexpectedly, you should double-check for any unique specifications of the archive in question.
FS_RESULT_INVALID_PARAMETER Indicates that one of the arguments provided is invalid or outside the allowed range. This mostly occurs with NULL pointers or when an invalid handle is specified.
FS_RESULT_NO_MORE_RESOURCE Indicates that certain resources required for the operation turned out to be insufficient internally. The number of handles that can be opened simultaneously, as well as the upper limit for dynamic memory consumed internally, are different for each archive.
FS_RESULT_ALREADY_DONE Indicates that the requested operation has already been performed. This will occur if the file specified to FS_CreateFile() already exists, for example, or if the directory specified to FS_DeleteDirectory() didn't exist to begin with.
FS_RESULT_PERMISSION_DENIED Indicates that the requested process failed due to a problem of access rights.
This primarily happens in the following cases:
  • An attempt is made to open with write permission a read-only file
  • An attempt is made to delete a directory that is not empty
  • An attempt is made to open a TWL-exclusive file (as specified by the Put parameter of the makerom tool) in the NITRO environment
  • An SD Card is write-protected
  • An attempt is made to open a file that is larger than 2 GB, which is not supported by the FS library
FS_RESULT_MEDIA_FATAL Indicates that a fatal device error is detected in writable media such as a NAND archive or an SD Card archive. Processing cannot continue. Prompt the user to replace or re-insert the SD card, or, if the error is in system save memory (NAND), to have the system repaired.
FS_RESULT_BAD_FORMAT This will occur if corruption in the file system is detected in writable media such as a NAND archive or an SD Card library. Processing cannot continue. Prompt the user to replace or re-insert the SD card, or, if the error is in system save memory (NAND), reformat the archive using the NA_FormatTitleArchive function.
FS_RESULT_NO_ENTRY Indicates that the specified path does not exist. This error will also occur when trying to create a file under a directory that doesn't exist.
FS_RESULT_MEDIA_NOTHING The specified archive is located on removable media, and that device was not inserted. Currently, this error is only returned by SD Card archives.
FS_RESULT_MEDIA_UNKNOWN The specified archive is located on removable media, and an unknown device has been inserted that doesn't have a known file system. Currently, this error is only returned by SD Card archives.
FS_RESULT_ERROR Indicates that some other detectable error occurred during an operation.

The following are used only as user procedure return values:
FS_RESULT_PROC_ASYNC Return value when the user procedure returns a temporary control for asynchronous processing.
When this value is returned, you must notify the read/write callback as well as the process completion using the FS_NotifyArchiveAsyncEnd function.
FS_RESULT_PROC_DEFAULT The default return value passed to a user procedure. This is the value passed unless a different value/type is called explicitly. The user procedure for the corresponding command will be called the next time as well. If you simply want to hook an existing command, this value is returned every time.
FS_RESULT_PROC_UNKNOWN The default return value passed to a user procedure when the procedure call flag to the associated command is canceled. The command will not be called again.
FS_RESULT_SUCCESSYou must follow the rules described above to determine about the specific archive in question and return from the procedure accordingly.
FS_RESULT_FAILURE
FS_RESULT_UNSUPPORTED
FS_RESULT_INVALID_PARAMETER
FS_RESULT_NO_MORE_RESOURCE
FS_RESULT_ALREADY_DONE
FS_RESULT_PERMISSION_DENIED
FS_RESULT_MEDIA_FATAL
FS_RESULT_NO_ENTRY
FS_RESULT_ERROR

See Also

FSArchive
FS_ARCHIVE_PROC_FUNC
FS_SetArchiveProc

Revision History

2009/06/08 Added link to explanation of TWL-exclusive files.
2009/02/05 Expanded explanation of FS_RESULT_PERMISSION_DENIED.
2008/10/21 Added a detailed description of FS_RESULT_MEDIA_FATAL and FS_RESULT_BAD_FORMAT.
2008/07/16 Added conditions for issuing FS_RESULT_PERMISSION_DENIED.
2008/06/25 Added FS_RESULT_MEDIA_NOTHING, FS_RESULT_MEDIA_UNKNOWN, and FS_RESULT_BAD_FORMAT.
2008/05/13 Added FS_RESULT_NO_ENTRY.
2008/04/42 Clarified the correspondence between error codes and numerical values.
2008/03/12 Added FS_RESULT_MEDIA_FATAL.
2007/09/18 Added a value and its description to the enumerated type.
2004/07/12 Added a value and its description to the enumerated type.
2004/07/01 Initial version.

CONFIDENTIAL