NANDReadDirAsync

Syntax

#include <revolution/nand.h>

#define NAND_MAX_NAME          12

typedef void (*NANDCallback)( s32 result, NANDCommandBlock *block );

s32 NANDReadDirAsync( const char *dirName, char *nameList, u32 *num, NANDCallback cb, NANDCommandBlock *block );

Arguments

dirName Directory name.

nameList Buffer start address for storing a list of the files and directories contained in the specified directory. This buffer must be 32-byte aligned. No list is stored if NULL is specified.

num When NULL is given for nameList, *num stores the number of files and directories that are contained in dirName. When a buffer address (non-NULL) is given for nameList, the file and directory names are written to the nameList buffer with the value of *num as the upper limit. The number of files and directories that were actually gotten from dirName is stored in *num.

cb Callback function to call when this function completes processing.

block Command block structure to be passed to the callback function.

dirName	Directory name.
nameList	Buffer start address for storing a list of the files and directories contained in the specified directory. This buffer must be 32-byte aligned. No list is stored if `NULL` is specified.
num	When `NULL` is given for nameList, num stores the number of files and directories that are contained in dirName. When a buffer address (non-`NULL`) is given for nameList, the file and directory names are written to the nameList buffer with the value of num as the upper limit. The number of files and directories that were actually gotten from dirName is stored in *num.
cb	Callback function to call when this function completes processing.
block	Command block structure to be passed to the callback function.

Return Values

The result codes that may be returned by NANDReadDirAsync are listed below. Returns NAND_RESULT_OK when the request begins normally.

NAND_RESULT_OK NAND_RESULT_ACCESS NAND_RESULT_ALLOC_FAILED NAND_RESULT_BUSY NAND_RESULT_INVALID NAND_RESULT_FATAL_ERROR

The result codes that may be passed to the callback function are listed below.

NAND_RESULT_OK NAND_RESULT_ACCESS NAND_RESULT_INVALID NAND_RESULT_NOEXISTS NAND_RESULT_UNKNOWN NAND_RESULT_FATAL_ERROR

Description

Asynchronously gets a list of files and directories contained in the specified directory. If the list size is unknown, retrieve the list using the following steps.

Call this function with NULL specified as the second argument. The number of elements in the list will be written to the memory region indicated by num.
Allocate a memory region whose size is = (Number of elements) * (NAND_MAX_NAME+1) rounded up to a multiple of 32 bytes.
Call this function again with the allocated memory start address as the second argument.
The number of retrieved list elements is stored in num (this value may be less than its value obtained the first call to this function), and the list of files and directories is stored in the allocated memory using null character separators.

NAND_RESULT_BUSY is returned and this function call is denied when the library's internal queue for accepting requests is full.

Revision History

2008/08/01 Revised the result codes that are passed to the callback function.
2008/05/13 Described the result codes passed to the callback function.
2007/06/xx The description of the third argument was revised because it was insufficient.
2006/09/07 Added text about allocating memory of a size rounded up to a multiple of 32 bytes.
2006/06/16 Initial version.