FreeRTOS/Common/FileSystem/FatFs-0.7e/doc/en/forward.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html lang="en">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <link rel="up" title="FatFs" href="../00index_e.html">
   7 <link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">
   8 <title>FatFs - f_forward</title>
   9 </head>
  10
  11 <body>
  12
  13 <div class="para">
  14 <h2>f_forward</h2>
  15 <p>The f_forward function reads the file data and forward it to the data streaming device.</p>
  16 <pre>
  17 FRESULT f_forward (
  18   FIL* <em>FileObject</em>,                 /* File object */
  19   UINT (*<em>Func</em>)(const BYTE*,UINT),  /* Data streaming function */
  20   UINT <em>ByteToFwd</em>,                  /* Number of bytes to forward */
  21   UINT* <em>ByteFwd</em>                    /* Number of bytes forwarded */
  22 );
  23 </pre>
  24 </div>
  25
  26 <div class="para">
  27 <h4>Parameters</h4>
  28 <dl class="par">
  29 <dt>FileObject</dt>
  30 <dd>Pointer to the open file object.</dd>
  31 <dt>Func</dt>
  32 <dd>Pointer to the user-defined data streaming function. For details, refer to the sample code.</dd>
  33 <dt>ByteToFwd</dt>
  34 <dd>Number of bytes to forward in range of UINT.</dd>
  35 <dt>ByteFwd</dt>
  36 <dd>Pointer to the UINT variable to return number of bytes forwarded.</dd>
  37 </dl>
  38 </div>
  39
  40
  41 <div class="para">
  42 <h4>Return Values</h4>
  43 <dl class="ret">
  44 <dt>FR_OK (0)</dt>
  45 <dd>The function succeeded.</dd>
  46 <dt>FR_DENIED</dt>
  47 <dd>The function denied due to the file has been opened in non-read mode.</dd>
  48 <dt>FR_DISK_ERR</dt>
  49 <dd>The function failed due to an error in the disk function.</dd>
  50 <dt>FR_INT_ERR</dt>
  51 <dd>The function failed due to a wrong FAT structure or an internal error.</dd>
  52 <dt>FR_NOT_READY</dt>
  53 <dd>The disk drive cannot work due to no medium in the drive or any other reason.</dd>
  54 <dt>FR_INVALID_OBJECT</dt>
  55 <dd>The file object is invalid.</dd>
  56 </dl>
  57 </div>
  58
  59
  60 <div class="para">
  61 <h4>Description</h4>
  62 <p>The f_forward function reads the data from the file and forward it to the outgoing stream without data buffer. This is suitable for small memory system because it does not require any data buffer at application module. The file pointer of the file object increases in number of bytes forwarded. In case of <tt>*ByteFwd &lt; ByteToFwd</tt> without error, it means the requested bytes could not be transferred due to end of file or stream goes busy during data transfer.</p>
  63 </div>
  64
  65
  66 <div class="para">
  67 <h4>QuickInfo</h4>
  68 <p>Available when <tt>_USE_FORWARD == 1</tt> and <tt>_FS_TINY == 1</tt>.</p>
  69 </div>
  70
  71
  72 <div class="para">
  73 <h4>Example (Audio playback)</h4>
  74 <pre>
  75 /*-----------------------------------------------------------------------*/
  76 /* Sample code of data transfer function to be called from f_forward     */
  77 /*-----------------------------------------------------------------------*/
  78
  79 UINT out_stream (   /* Returns number of bytes sent or stream status */
  80     const BYTE *p,  /* Pointer to the data block to be sent */
  81     UINT btf        /* &gt;0: Transfer call (Number of bytes to be sent). 0: Sense call */
  82 )
  83 {
  84     UINT cnt = 0;
  85
  86
  87     if (btf == 0) {     /* Sense call */
  88         /* Return stream status (0: Busy, 1: Ready) */
  89         /* When once it returned ready to sense call, it must accept a byte at least */
  90         /* at subsequent transfer call, or f_forward will fail with FR_INT_ERROR. */
  91         if (FIFO_READY) cnt = 1;
  92     }
  93     else {              /* Transfer call */
  94         do {    /* Repeat while there is any data to be sent and the stream is ready */
  95             FIFO_PORT = *p++;
  96             cnt++;
  97         } while (cnt &lt; btf &amp;&amp; FIFO_READY);
  98     }
  99
 100     return cnt;
 101 }
 102
 103
 104 /*-----------------------------------------------------------------------*/
 105 /* Sample code using f_forward function                                  */
 106 /*-----------------------------------------------------------------------*/
 107
 108 FRESULT play_file (
 109     char *fn        /* Pointer to the audio file name to be played */
 110 )
 111 {
 112     FRESULT rc;
 113     FIL fil;
 114     UINT dmy;
 115
 116     /* Open the audio file in read only mode */
 117     rc = f_open(&amp;fil, fn, FA_READ);
 118
 119     /* Repeat until the file pointer reaches end of the file */
 120     while (rc == FR_OK &amp;&amp; fil.fptr &lt; fil.fsize) {
 121
 122         /* any other processes... */
 123
 124         /* Fill output stream periodicaly or on-demand */
 125         rc = f_forward(&amp;fil, out_stream, 1000, &amp;dmy);
 126     }
 127
 128     /* The read-only file object may be discarded without close */
 129     return rc;
 130 }
 131 </pre>
 132 </div>
 133
 134
 135 <div class="para">
 136 <h4>See Also</h4>
 137 <p><tt><a href="open.html">f_open</a>, <a href="gets.html">fgets</a>, <a href="write.html">f_write</a>, <a href="close.html">f_close</a>, <a href="sfile.html">FIL</a></tt></p>
 138 </div>
 139
 140 <p class="foot"><a href="../00index_e.html">Return</a></p>
 141 </body>
 142 </html>