FatFs - f_forward

## f_forward

ファイルからデータを読み出し、送信ストリームに直接転送します。

    FRESULT f_forward (
      FIL* FileObject,                 /* ファイル・オブジェクト構造体 */
      UINT (*Func)(const BYTE*,UINT),  /* データ転送関数 */
      UINT ByteToFwd,                  /* 転送するバイト数 */
      UINT* ByteFwd                    /* 転送されたバイト数 */
    );

#### 引数

FileObject
  ファイル・オブジェクト構造体へのポインタを指定します。
Func
  データを渡すユーザ定義関数へのポインタを指定します。この関数の仕様はサンプルを参照してください。
ByteToRead
  転送するバイト数(0〜UINTの最大値)を指定します。
ByteRead
  実際に転送されたバイト数を格納する変数を指すポインタを指定します。

#### 戻り値

FR_OK (0)
  正常終了。
FR_DENIED
  非読み込みモードで開いたファイルから読み込もうとした。
FR_DISK_ERR
  ディスク・エラーによる失敗。
FR_INT_ERR
  不正なFAT構造または内部エラーによる失敗。
FR_NOT_READY
  メディアがセットされていないなど、ディスク・ドライブが動作不能状態。
FR_INVALID_OBJECT
  無効なファイル・オブジェクト。

#### 解説

ファイルのデータをバッファに読み出さずに送信ストリームに直接転送します。アプリケーション側でデータ・バッファを必要としないので、メモリの限られた環境で有効です。転送開始位置は、現在のファイルR/Wポインタからになります。ファイルR/Wポインタは転送されたバイト数だけ進みます。指定されたバイト数の転送中にファイルの終端に達した場合や送信ストリームがビジーになった場合、`*ByteFwd`は`ByteToFwd`よりも小さくなります。

#### 対応情報

`_USE_FORWARD == 1`で、且つ`_FS_TINY == 1`のときに使用可能です。

#### 使用例（オーディオ再生）

    /*-----------------------------------------------------------------------*/
    /* f_forward関数から呼ばれるデータ送信関数の例                           */
    /*-----------------------------------------------------------------------*/

    UINT out_stream (   /* 戻り値: 転送されたバイト数またはストリームの状態 */
        const BYTE *p,  /* 転送するデータを指すポインタ */
        UINT btf        /* >0: 転送を行う(バイト数). 0: ストリームの状態を調べる */
    )
    {
        UINT cnt = 0;

        if (btf == 0) {     /* センス要求 */
            /* ストリームの状態を返す (0: ビジー, 1: レディ) */
            /* 一旦、レディを返したら、続く転送要求で少なくとも1バイトは */
            /* 転送されないと f_forward関数は FR_RW_ERROR となる。 */
            if (FIFO_READY) cnt = 1;
        }
        else {              /* 転送要求 */
            do {    /* 全てのバイトを転送するか、ストリームがビジーになるまで繰り返す */
                FIFO_PORT = *p++;
                cnt++;
            } while (cnt < btf && FIFO_READY);
        }

        return cnt;
    }

    /*-----------------------------------------------------------------------*/
    /* f_forward関数の使用例                                                 */
    /*-----------------------------------------------------------------------*/

    FRESULT play_file (
        char *fn        /* 再生するオーディオ・ファイル名を指すポインタ */
    )
    {
        FRESULT rc;
        FIL fil;
        UINT dmy;

        /* ファイルを読み出しモードで開く */
        rc = f_open(&fil, fn, FA_READ);

        /* 全てのデータが転送されるかエラーが発生するまで続ける */
        while (rc == FR_OK && fil.fptr < fil.fsize) {

            /* ほかの処理... */

            /* 定期的または要求に応じてデータをストリームに送出する */
            rc = f_forward(&fil, out_stream, 1000, &dmy);
        }

        return rc;	/* FR_OK: 正常終了, ほか:異常終了 */
    }

#### 参照

`f_open, fgets, f_write, f_close, FIL`

戻る