FatFs - f_findfirst

f_findfirst

ディレクトリ内のオブジェクトの検索を開始します。

FRESULT f_findfirst (
  DIR* dp,              /* [OUT] ディレクトリ オブジェクト構造体へのポインタ */
  FILINFO* fno,         /* [OUT] ファイル情報構造体へのポインタ */
  const TCHAR* path,    /* [IN] ディレクトリ名へのポインタ */
  const TCHAR* pattern  /* [IN] マッチ パターン文字列へのポインタ */
);

引数

dp: 空のディレクトリオブジェクト構造体へのポインタを指定します。
fno: 最初にマッチしたディレクトリ項目を格納するファイル情報構造体へのポインタを指定します。
path: オープンするディレクトリのパス名を示すヌル文字'\0'終端の文字列へのポインタを指定します。
pattern: 検索する名前を示すヌル文字'\0'終端の文字列へのポインタを指定します。この文字列は、続くf_findnext関数でも参照されるため、一連の処理が終了するまで有効でなければなりません。

戻り値

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_PATH, FR_INVALID_NAME, FR_INVALID_OBJECT, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES

解説

pathで指定されるディレクトリを開き、そのディレクトリ内の項目の検索を開始します。正常終了すると、ディレクトリオブジェクト構造体が作成され、最初に検索名文字列に名前がマッチした項目の情報がfnoの指定するファイル情報構造体にストアされます。名前のマッチする項目が見つからなかった場合は、fno->fname[]にヌル文字列が返されます。ファイル情報構造体の使い方については、f_readdir関数を参照してください。

マッチパターン文字列は、ワイルドカード文字(?と*)を含むことができます。?は任意の1文字に、*は0文字以上の任意の文字列にマッチします。LFN構成では、_USE_FIND = 1のときfname[]のみテストし、_USE_FIND = 2のときはaltname[]もテストします。現リビジョンではパターンマッチングにおいて次の点で標準システムとは異なる動作となります。

"*.*"は拡張子なしの名前にマッチしない。(標準システムでは全ての名前にマッチ)
ピリオドで終わるパターンは、どの名前にもマッチしない。(標準システムでは拡張子無しの名前にマッチ)
DBCS拡張文字については、LFN構成でも非Unicode API構成ではケースセンシティブとなる。

対応情報

この関数は、f_opendir関数およびf_readdir関数のラッパー関数です。_USE_FIND >= 1で、かつ_FS_MINIMIZE <= 1のとき使用可能になります。

使用例

/* ディレクトリ内のjpegファイルの検索 */

void find_image_file (void)
{
    FRESULT fr;     /* API戻り値 */
    DIR dj;         /* ディレクトリ オブジェクト */
    FILINFO fno;    /* ファイル情報 */

    fr = f_findfirst(&dj, &fno, "", "dsc*.jpg");  /* "dsc"で始まるJPEGファイルを検索 */

    while (fr == FR_OK && fno.fname[0]) {         /* 見つかる間繰り返し */
        printf("%s\n", fno.fname);                /* 見つけた項目の名前を表示 */
        fr = f_findnext(&dj, &fno);               /* 次を検索 */
    }

    f_closedir(&dj);
}