[z180-stamp.git] / fatfs / documents / doc / forward.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\r
<html lang="en">\r
<head>\r
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">\r
<meta http-equiv="Content-Style-Type" content="text/css">\r
<link rel="up" title="FatFs" href="../00index_e.html">\r
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/forward.html">\r
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">\r
<title>FatFs - f_forward</title>\r
</head>\r
\r
<body>\r
\r
<div class="para func">\r
<h2>f_forward</h2>\r
<p>The f_forward function reads the file data and forward it to the data streaming device.</p>\r
<pre>\r
FRESULT f_forward (\r
  FIL* <span class="arg">fp</span>,                        <span class="c">/* [IN] File object */</span>\r
  UINT (*<span class="arg">func</span>)(const BYTE*,UINT), <span class="c">/* [IN] Data streaming function */</span>\r
  UINT <span class="arg">btf</span>,                       <span class="c">/* [IN] Number of bytes to forward */</span>\r
  UINT* <span class="arg">bf</span>                        <span class="c">/* [OUT] Number of bytes forwarded */</span>\r
);\r
</pre>\r
</div>\r
\r
<div class="para arg">\r
<h4>Parameters</h4>\r
<dl class="par">\r
<dt>fp</dt>\r
<dd>Pointer to the open file object.</dd>\r
<dt>func</dt>\r
<dd>Pointer to the user-defined data streaming function. For details, refer to the sample code.</dd>\r
<dt>btf</dt>\r
<dd>Number of bytes to forward in range of <tt>UINT</tt>.</dd>\r
<dt>bf</dt>\r
<dd>Pointer to the <tt>UINT</tt> variable to return number of bytes forwarded.</dd>\r
</dl>\r
</div>\r
\r
\r
<div class="para ret">\r
<h4>Return Values</h4>\r
<p>\r
<a href="rc.html#ok">FR_OK</a>,\r
<a href="rc.html#de">FR_DISK_ERR</a>,\r
<a href="rc.html#ie">FR_INT_ERR</a>,\r
<a href="rc.html#io">FR_INVALID_OBJECT</a>,\r
<a href="rc.html#dn">FR_DENIED</a>,\r
<a href="rc.html#tm">FR_TIMEOUT</a>\r
</p>\r
</div>\r
\r
\r
<div class="para desc">\r
<h4>Description</h4>\r
<p>The <tt>f_forward</tt> 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 class="arg">*bf</tt> is less than <tt class="arg">btf</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>\r
</div>\r
\r
\r
<div class="para comp">\r
<h4>QuickInfo</h4>\r
<p>Available when <tt><a href="config.html#use_forward">FF_USE_FORWARD</a> == 1</tt>.</p>\r
</div>\r
\r
\r
<div class="para use">\r
<h4>Example (Audio playback)</h4>\r
<pre>\r
<span class="c">/*------------------------------------------------------------------------*/</span>\r
<span class="c">/* Sample code of data transfer function to be called back from f_forward */</span>\r
<span class="c">/*------------------------------------------------------------------------*/</span>\r
\r
UINT out_stream (   <span class="c">/* Returns number of bytes sent or stream status */</span>\r
    const BYTE *p,  <span class="c">/* Pointer to the data block to be sent */</span>\r
    UINT btf        <span class="c">/* &gt;0: Transfer call (Number of bytes to be sent). 0: Sense call */</span>\r
)\r
{\r
    UINT cnt = 0;\r
\r
\r
    if (btf == 0) {     <span class="c">/* Sense call */</span>\r
        <span class="c">/* Return stream status (0: Busy, 1: Ready) */</span>\r
        <span class="c">/* When once it returned ready to sense call, it must accept a byte at least */</span>\r
        <span class="c">/* at subsequent transfer call, or f_forward will fail with FR_INT_ERR. */</span>\r
        if (FIFO_READY) cnt = 1;\r
    }\r
    else {              <span class="c">/* Transfer call */</span>\r
        do {    <span class="c">/* Repeat while there is any data to be sent and the stream is ready */</span>\r
            FIFO_PORT = *p++;\r
            cnt++;\r
        } while (cnt &lt; btf &amp;&amp; FIFO_READY);\r
    }\r
\r
    return cnt;\r
}\r
\r
\r
<span class="c">/*------------------------------------------------------------------------*/</span>\r
<span class="c">/* Sample code using f_forward function                                   */</span>\r
<span class="c">/*------------------------------------------------------------------------*/</span>\r
\r
FRESULT play_file (\r
    char *fn        <span class="c">/* Pointer to the audio file name to be played */</span>\r
)\r
{\r
    FRESULT rc;\r
    FIL fil;\r
    UINT dmy;\r
\r
    <span class="c">/* Open the audio file in read only mode */</span>\r
    rc = f_open(&amp;fil, fn, FA_READ);\r
    if (rc) return rc;\r
\r
    <span class="c">/* Repeat until the file pointer reaches end of the file */</span>\r
    while (rc == FR_OK &amp;&amp; !f_eof(&amp;fil)) {\r
\r
        <span class="c">/* some processes... */</span>\r
\r
        <span class="c">/* Fill output stream periodicaly or on-demand */</span>\r
        rc = <em>f_forward</em>(&amp;fil, out_stream, 1000, &amp;dmy);\r
    }\r
\r
    <span class="c">/* Close the file and return */</span>\r
    f_close(&amp;fil);\r
    return rc;\r
}\r
</pre>\r
</div>\r
\r
\r
<div class="para ref">\r
<h4>See Also</h4>\r
<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>\r
</div>\r
\r
<p class="foot"><a href="../00index_e.html">Return</a></p>\r
</body>\r
</html>\r
Commit	Line	Data
53668523 L	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\r
	2	<html lang="en">\r
	3	<head>\r
289f6a14	4	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">\r
53668523 L	5	<meta http-equiv="Content-Style-Type" content="text/css">\r
	6	<link rel="up" title="FatFs" href="../00index_e.html">\r
	7	<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/forward.html">\r
	8	<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">\r
	9	<title>FatFs - f_forward</title>\r
	10	</head>\r
	11	\r
	12	<body>\r
	13	\r
	14	<div class="para func">\r
	15	<h2>f_forward</h2>\r
	16	<p>The f_forward function reads the file data and forward it to the data streaming device.</p>\r
	17	<pre>\r
	18	FRESULT f_forward (\r
	19	FIL* <span class="arg">fp</span>, <span class="c">/* [IN] File object */</span>\r
	20	UINT (<span class="arg">func</span>)(const BYTE,UINT), <span class="c">/* [IN] Data streaming function */</span>\r
	21	UINT <span class="arg">btf</span>, <span class="c">/* [IN] Number of bytes to forward */</span>\r
	22	UINT* <span class="arg">bf</span> <span class="c">/* [OUT] Number of bytes forwarded */</span>\r
	23	);\r
	24	</pre>\r
	25	</div>\r
	26	\r
	27	<div class="para arg">\r
	28	<h4>Parameters</h4>\r
	29	<dl class="par">\r
	30	<dt>fp</dt>\r
	31	<dd>Pointer to the open file object.</dd>\r
	32	<dt>func</dt>\r
	33	<dd>Pointer to the user-defined data streaming function. For details, refer to the sample code.</dd>\r
	34	<dt>btf</dt>\r
	35	<dd>Number of bytes to forward in range of <tt>UINT</tt>.</dd>\r
	36	<dt>bf</dt>\r
	37	<dd>Pointer to the <tt>UINT</tt> variable to return number of bytes forwarded.</dd>\r
	38	</dl>\r
	39	</div>\r
	40	\r
	41	\r
	42	<div class="para ret">\r
	43	<h4>Return Values</h4>\r
	44	<p>\r
	45	<a href="rc.html#ok">FR_OK</a>,\r
	46	<a href="rc.html#de">FR_DISK_ERR</a>,\r
	47	<a href="rc.html#ie">FR_INT_ERR</a>,\r
53668523	48	<a href="rc.html#io">FR_INVALID_OBJECT</a>,\r
289f6a14	49	<a href="rc.html#dn">FR_DENIED</a>,\r
53668523 L	50	<a href="rc.html#tm">FR_TIMEOUT</a>\r
	51	</p>\r
	52	</div>\r
	53	\r
	54	\r
	55	<div class="para desc">\r
	56	<h4>Description</h4>\r
70702af1	57	<p>The <tt>f_forward</tt> 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 class="arg">*bf</tt> is less than <tt class="arg">btf</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>\r
53668523 L	58	</div>\r
	59	\r
	60	\r
	61	<div class="para comp">\r
	62	<h4>QuickInfo</h4>\r
289f6a14	63	<p>Available when <tt><a href="config.html#use_forward">FF_USE_FORWARD</a> == 1</tt>.</p>\r
53668523 L	64	</div>\r
	65	\r
	66	\r
	67	<div class="para use">\r
	68	<h4>Example (Audio playback)</h4>\r
	69	<pre>\r
	70	<span class="c">/------------------------------------------------------------------------/</span>\r
	71	<span class="c">/* Sample code of data transfer function to be called back from f_forward */</span>\r
	72	<span class="c">/------------------------------------------------------------------------/</span>\r
	73	\r
	74	UINT out_stream ( <span class="c">/* Returns number of bytes sent or stream status */</span>\r
	75	const BYTE p, <span class="c">/ Pointer to the data block to be sent */</span>\r
	76	UINT btf <span class="c">/* >0: Transfer call (Number of bytes to be sent). 0: Sense call */</span>\r
	77	)\r
	78	{\r
	79	UINT cnt = 0;\r
	80	\r
	81	\r
	82	if (btf == 0) { <span class="c">/* Sense call */</span>\r
	83	<span class="c">/* Return stream status (0: Busy, 1: Ready) */</span>\r
	84	<span class="c">/* When once it returned ready to sense call, it must accept a byte at least */</span>\r
	85	<span class="c">/* at subsequent transfer call, or f_forward will fail with FR_INT_ERR. */</span>\r
	86	if (FIFO_READY) cnt = 1;\r
	87	}\r
	88	else { <span class="c">/* Transfer call */</span>\r
	89	do { <span class="c">/* Repeat while there is any data to be sent and the stream is ready */</span>\r
	90	FIFO_PORT = *p++;\r
	91	cnt++;\r
	92	} while (cnt < btf && FIFO_READY);\r
	93	}\r
	94	\r
	95	return cnt;\r
	96	}\r
	97	\r
	98	\r
	99	<span class="c">/------------------------------------------------------------------------/</span>\r
	100	<span class="c">/* Sample code using f_forward function */</span>\r
	101	<span class="c">/------------------------------------------------------------------------/</span>\r
	102	\r
	103	FRESULT play_file (\r
	104	char fn <span class="c">/ Pointer to the audio file name to be played */</span>\r
	105	)\r
	106	{\r
	107	FRESULT rc;\r
	108	FIL fil;\r
	109	UINT dmy;\r
	110	\r
	111	<span class="c">/* Open the audio file in read only mode */</span>\r
	112	rc = f_open(&fil, fn, FA_READ);\r
	113	if (rc) return rc;\r
	114	\r
	115	<span class="c">/* Repeat until the file pointer reaches end of the file */</span>\r
70702af1	116	while (rc == FR_OK && !f_eof(&fil)) {\r
53668523	117	\r
289f6a14	118	<span class="c">/* some processes... */</span>\r
53668523 L	119	\r
53668523 L	120	<span class="c">/* Fill output stream periodicaly or on-demand */</span>\r
289f6a14	121	rc = <em>f_forward</em>(&fil, out_stream, 1000, &dmy);\r
53668523 L	122	}\r
	123	\r
	124	<span class="c">/* Close the file and return */</span>\r
	125	f_close(&fil);\r
	126	return rc;\r
	127	}\r
	128	</pre>\r
	129	</div>\r
	130	\r
	131	\r
	132	<div class="para ref">\r
	133	<h4>See Also</h4>\r
	134	<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>\r
	135	</div>\r
	136	\r
	137	<p class="foot"><a href="../00index_e.html">Return</a></p>\r
	138	</body>\r
	139	</html>\r