FF_FindFirst()

Opens opens the specified directory, and returns the first item in the directory (if any) via the provided FF_DIRENT object.

Prototype

2.x.x Series

FF_ERROR FF_FindFirst(FF_IOMAN *pIoman, FF_DIRENT *pDirent, const FF_T_INT8 *path);   // Standard API
FF_ERROR FF_FindFirst(FF_IOMAN *pIoman, FF_DIRENT *pDirent, const FF_T_WCHAR *path);  // UTF-16 (Unicode) API

Note this prototype is binary compatible with the 1.0.x and 1.1.x series, as FF_ERROR is a FF_T_SINT32 type.

1.1.x Series

FF_T_SINT32 FF_FindFirst(FF_IOMAN *pIoman, FF_DIRENT *pDirent, const FF_T_INT8 *path);

Where path may include a wild card, when ff_config.h has defined FF_FINDAPI_ALLOW_WILDCARDS. Otherwise FF_FindFirst() behaves as in 1.0.x Series.

1.0.x Series

FF_T_SINT32 FF_FindFirst(FF_IOMAN *pIoman, FF_DIRENT *pDirent, const FF_T_INT8 *path);
// As of 1.0.0 return type is FF_T_SINT32, it was FF_T_SINT8

Back to API.

Parameters

pIoman

Pointer to an FF_IOMAN object, as returned from the FF_CreateIOMAN() function.

pDirent

A pointer to an FF_DIRENT object to be populated.

path

Absolute path of the directory to be opened.

1.1.x Series

This can now include a wildCard, to filter items in a directory. The wildcards can be intelligent. /*-*.mp?

Return Value

Returns 0 on success. Returns -2 if dir was not found.

Example

#include "fullfat.h"
 
FF_DIRENT mydir;
 
FF_FindFirst(pIoman, &mydir, "\\"); // Open the root dir.
FF_FindFirst(pIoman, &mydir, "\\test"); // Open the \test dir.

After the call, and 0 was returned, then mydir will be populated with entries describing the file. To extract this information please see the FF_DIRENT information.

WildCard Searching

FullFAT now includes comprehensive wildCard searching feature. Using this in your own projects will provide huge performance benefits, where comparisons outside of the API would have been very expensive. FullFAT now optimises wildCard matching at the lowest possible level, using a well-tested and very optimised wildCard algorithm.

If FF_FINDAPI_ALLOW_WILDCARDS is defined (in FF_CONFIG, then path will have the following behaviour:

 path = "\"                      - Open the root dir, and iterate through all items.
 path = "\*.c"                   - Open the root dir, showing only files matching *.c wildcard.
 path = "\sub1\newdir"           - Get the DIRENT for the newdir directory in /sub1/ if one exists.   
 path = "\sub1\newdir\"          - Open the directory /sub1/newdir/ and iterate through all items.   
 path = "\sub1\newdir\*.c"       - Open the directory /sub1/newdir/ and iterate through all items matching the *.c wildcard.

It is important to distinguish the differences in behaviour between opening a Find operation on a path like /sub1 and /sub1/. (/sub1 gets the sub1 dirent from the / dir, whereas /sub/ opens the sub1 dir).

Note, as compatible with other similar APIs, FullFAT also accepts \sub1\* for the same behaviour as /sub1/.

Back to API.

See Also

• FF_FindFirst()
• FF_FindNext()
• FF_FindPrevious()
• FF_RmDir()
• FF_isDirEmpty()
• FF_DIRENT