version 2.8
gfile.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /**
9  * @file src/gfile/gfile.h
10  * @brief GFILE - File IO Routines header file.
11  *
12  * @addtogroup GFILE
13  *
14  * @brief Module which contains operating system independent file I/O.
15  *
16  * @{
17  */
18 
19 #ifndef _GFILE_H
20 #define _GFILE_H
21 
22 #include "../../gfx.h"
23 
24 #if GFX_USE_GFILE || defined(__DOXYGEN__)
25 
26 /*===========================================================================*/
27 /* Type definitions */
28 /*===========================================================================*/
29 
30 /**
31  * @brief A file pointer
32  */
33 
34 typedef struct GFILE GFILE;
35 typedef struct gfileList gfileList;
36 
37 extern GFILE *gfileStdIn;
38 extern GFILE *gfileStdErr;
39 extern GFILE *gfileStdOut;
40 
41 /*===========================================================================*/
42 /* External declarations. */
43 /*===========================================================================*/
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 
49  /**
50  * @brief Check if file exists
51  *
52  * @param[in] fname The file name
53  *
54  * @return TRUE if file exists, FALSE otherwise
55  *
56  * @api
57  */
58  bool_t gfileExists(const char *fname);
59 
60  /**
61  * @brief Delete file
62  *
63  * @param[in] fname The file name
64  *
65  * @return TRUE on success, FALSE otherwise
66  *
67  * @api
68  */
69  bool_t gfileDelete(const char *fname);
70 
71  /**
72  * @brief Get the size of a file
73  * @note Please use @p gfileGetSize() if the file is opened
74  *
75  * @param[in] fname The file name
76  *
77  * @return File size on success, -1 on error
78  *
79  * @api
80  */
81  long int gfileGetFilesize(const char *fname);
82 
83  /**
84  * @brief Rename file
85  *
86  * @param[in] oldname The current file name
87  * @param[in] newname The new name of the file
88  *
89  * @return TRUE on success, FALSE otherwise
90  *
91  * @api
92  */
93  bool_t gfileRename(const char *oldname, const char *newname);
94 
95  /**
96  * @brief Open file
97  * @details A file must be opened before it can be accessed
98  * @details The resulting GFILE will be used for all functions that access the file.
99  *
100  * @param[in] fname The file name
101  * @param[in] mode The mode.
102  *
103  * @return Valid GFILE on success, 0 otherwise
104  *
105  * @note The modes follow the c library fopen() standard.
106  * The valid modes are:
107  * <ul><li>r - Open for read, the file must exist</li>
108  * <li>w - Open for write, the file is truncated if it exists</li>
109  * <li>wx - Open for write, the file must not exist</li>
110  * <li>a - Open for append, the file is truncated if it exists</li>
111  * <li>ax - Open for append, the file must not exists</li>
112  * </ul>
113  * The following flags can also be added to the above modes:<br/>
114  * <ul><li>+ - Open for both read and write</li>
115  * <li>b - Open as a binary file rather than a text file</li>
116  * </ul>
117  * @note Not all file-systems support all modes. For example, write
118  * is not available with the ROM file-system. Similarly few platforms
119  * distinguish between binary and text files.
120  * @note Even though binary vs. text is relevant only for a small number of platforms
121  * the "b" flag should always be specified for binary files such as images.
122  * This ensures portability to other platforms. The extra flag will be ignored
123  * on platforms where it is not relevant.
124  *
125  * @api
126  */
127  GFILE * gfileOpen(const char *fname, const char *mode);
128 
129  /**
130  * @brief Close file
131  * @details Closes a file after is has been opened using @p gfileOpen()
132  *
133  * @param[in] f The file
134  *
135  * @api
136  */
137  void gfileClose(GFILE *f);
138 
139  /**
140  * @brief Read from file
141  * @details Reads a given amount of bytes from the file
142  * @details The read/write cursor will not be reset when calling this function
143  *
144  * @param[in] f The file
145  * @param[out] buf The buffer in which to save the content that has been read from the file
146  * @param[in] len Amount of bytes to read
147  *
148  * @return Amount of bytes read
149  *
150  * @api
151  */
152  size_t gfileRead(GFILE *f, void *buf, size_t len);
153 
154  /**
155  * @brief Write to file
156  * @details Write a given amount of bytes to the file
157  * @details The read/write cursor will not be reset when calling this function
158  *
159  * @param[in] f The file
160  * @param[in] buf The buffer which contains the content that will be written to the file
161  * @param[in] len Amount of bytes to write
162  *
163  * @return Amount of bytes written
164  *
165  * @api
166  */
167  size_t gfileWrite(GFILE *f, const void *buf, size_t len);
168 
169  /**
170  * @brief Get the current position of the read/write cursor
171  *
172  * @param[in] f The file
173  *
174  * @return The current position in the file
175  *
176  * @api
177  */
178  long int gfileGetPos(GFILE *f);
179 
180  /**
181  * @brief Set the position of the read/write cursor
182  *
183  * @param[in] f The file
184  * @param[in] pos The position to which the cursor will be set
185  *
186  * @return TRUE on success, FALSE otherwise
187  *
188  * @api
189  */
190  bool_t gfileSetPos(GFILE *f, long int pos);
191 
192  /**
193  * @brief Get the size of file
194  * @note Please use @p gfileGetFilesize() if the file is not opened
195  *
196  * @param[in] f The file
197  *
198  * @return The size of the file
199  *
200  * @api
201  */
202  long int gfileGetSize(GFILE *f);
203 
204  /**
205  * @brief Check for EOF
206  * @details Checks if the cursor is at the end of the file
207  *
208  * @param[in] f The file
209  *
210  * @return TRUE if EOF, FALSE otherwise
211  *
212  * @api
213  */
214  bool_t gfileEOF(GFILE *f);
215 
216  /**
217  * @brief Mount a logical drive (aka partition)
218  *
219  * @details Not supported by every file system
220  * @details Currently just one drive at one is supported.
221  *
222  * @param[in] fs The file system (F for FatFS)
223  * @param[in] drive The logical drive prefix
224  *
225  * @return TRUE on success, FALSE otherwise
226  *
227  * @api
228  */
229  bool_t gfileMount(char fs, const char *drive);
230 
231  /**
232  * @brief Unmount a logical drive (aka partition)
233  *
234  * @details Does have no effect if @p gfileMount() as been called before hand
235  *
236  * @param[in] fs The file system (F for FatFS)
237  * @param[in] drive The logical drive prefix
238  *
239  * @return TRUE on success, FALSE otherwise
240  *
241  * @api
242  */
243  bool_t gfileUnmount(char fs, const char *drive);
244 
245  /**
246  * @brief Syncs the file object (flushes the buffer)
247  *
248  * @details Not supported by every file system
249  *
250  * @param[in] f The file
251  *
252  * @return TRUE on success, FALSE otherwise
253  *
254  * @api
255  */
256  bool_t gfileSync(GFILE *f);
257 
258  #if GFILE_NEED_FILELISTS || defined(__DOXYGEN__)
259  /**
260  * @brief Open a file list
261  *
262  * @param[in] fs The file system (F for FatFS)
263  * @param[in] path Path information to pass to the file system
264  * @param[in] dirs Pass TRUE to get directories only, FALSE to get files only
265  *
266  * @return A pointer to a file list on success, NULL otherwise
267  *
268  * @note The path parameter is handled in a file-system specific way. It could be
269  * treated as a directory name, it may be treated as a file pattern, or it
270  * may be ignored. Passing NULL will always return the full list of files
271  * in at least the top level directory.
272  * @note For file systems that do not support directories, passing TRUE for dirs
273  * will return an error.
274  * @note You must call @p gfileCloseFileList() when you have finished with the
275  * file list in order to free resources.
276  *
277  * @api
278  */
279  gfileList *gfileOpenFileList(char fs, const char *path, bool_t dirs);
280 
281  /**
282  * @brief Get the next file in a file list.
283  *
284  * @param[in] pfl Pointer to a file list returned by @p gfileOpenFileList()
285  *
286  * @return A pointer to a file (or directory) name. Returns NULL if there are no more.
287  *
288  * @note The file name may contain the full directory path or may not depending
289  * on how the file system treats directories.
290  * @note The returned buffer may be destroyed by the next call to any of
291  * @p gfileOpenFileList(), @p gfileReadFileList() or @p gfileCloseFileList().
292  * Do not use this pointer after one of those calls.
293  *
294  * @api
295  */
296  const char *gfileReadFileList(gfileList *pfl);
297 
298  /**
299  * @brief Close a file list.
300  *
301  * @param[in] pfl Pointer to a file list returned by @p gfileOpenFileList()
302  *
303  * @api
304  */
305  void gfileCloseFileList(gfileList *pfl);
306  #endif
307 
308  #if (GFILE_NEED_CHIBIOSFS && GFX_USE_OS_CHIBIOS) || defined(__DOXYGEN__)
309  /**
310  * @brief Open file from a ChibiOS FileStream
311  *
312  * @param[in] FileStreamPtr The BaseFileStream (ChibiOS V2) or FileStream (ChibiOS V3) to open as a GFILE
313  * @param[in] mode The mode.
314  *
315  * @return Valid GFILE on success, 0 otherwise
316  *
317  * @note The modes are the same modes as in @p gfileOpen(). The
318  * open mode is NOT compared against the FileStream capabilities.
319  * @note Supported operations are: read, write, getpos, setpos, eof and getsize
320  *
321  * @api
322  */
323  GFILE * gfileOpenChibiOSFileStream(void *FileStreamPtr, const char *mode);
324  #define gfileOpenBaseFileStream(f,m) gfileOpenChibiOSFileStream(f,m)
325  #endif
326 
327  #if GFILE_NEED_MEMFS || defined(__DOXYGEN__)
328  /**
329  * @brief Open file from a memory pointer
330  *
331  * @param[in] memptr The pointer to the memory
332  * @param[in] mode The mode.
333  *
334  * @return Valid GFILE on success, 0 otherwise
335  *
336  * @note The modes are the same modes as in @p gfileOpen(). Note there is
337  * no concept of file-size. Be careful not to overwrite other memory or
338  * to read from inaccessible sections of memory.
339  * @note Supported operations are: read, write, getpos, setpos
340  *
341  * @api
342  */
343  GFILE * gfileOpenMemory(void *memptr, const char *mode);
344  #endif
345 
346  #if GFILE_NEED_STRINGS || defined(__DOXYGEN__)
347  /**
348  * @brief Open file from a null terminated C string
349  *
350  * @param[in] str The pointer to the string or string buffer
351  * @param[in] mode The mode
352  *
353  * @return Valid GFILE on success, 0 otherwise
354  *
355  * @note The modes are the same modes as in @p gfileOpen(). Note there is
356  * no concept of file-size. Be careful not to overwrite other memory or
357  * to read from inaccessible sections of memory.
358  * @note Reading will return EOF when the NULL character is reached.
359  * @note Writing will always place a NULL in the next character effectively terminating the
360  * string at the character just written.
361  * @note Supported operations are: read, write, append, getpos, setpos
362  * @note Be careful with setpos and getpos. They do not check for the end of the string.
363  * @note Reading and Writing will read/write a maximum of one character at a time.
364  *
365  * @api
366  */
367  GFILE * gfileOpenString(char *str, const char *mode);
368  #endif
369 
370  #if GFILE_NEED_PRINTG || defined(__DOXYGEN__)
371  #include <stdarg.h>
372 
373  int vfnprintg(GFILE *f, int maxlen, const char *fmt, va_list arg);
374  int fnprintg(GFILE *f, int maxlen, const char *fmt, ...);
375  #define vfprintg(f,m,a) vfnprintg(f,0,m,a)
376  #define fprintg(f,m,...) fnprintg(f,0,m,__VA_ARGS__)
377  #define vprintg(m,a) vfnprintg(gfileStdOut,0,m,a)
378  #define printg(m,...) fnprintg(gfileStdOut,0,m,__VA_ARGS__)
379 
380  #if GFILE_NEED_STRINGS
381  int vsnprintg(char *buf, int maxlen, const char *fmt, va_list arg);
382  int snprintg(char *buf, int maxlen, const char *fmt, ...);
383  #define vsprintg(s,m,a) vsnprintg(s,0,m,a)
384  #define sprintg(s,m,...) snprintg(s,0,m,__VA_ARGS__)
385  #endif
386  #endif
387 
388  #if GFILE_NEED_SCANG || defined(__DOXYGEN__)
389  #include <stdarg.h>
390 
391  int vfscang(GFILE *f, const char *fmt, va_list arg);
392  int fscang(GFILE *f, const char *fmt, ...);
393  #define vscang(f,a) vfscang(gfileStdIn,f,a)
394  #define scang(f,...) fscang(gfileStdIn,f,__VA_ARGS__)
395 
396  #if GFILE_NEED_STRINGS
397  int vsscang(const char *buf, const char *fmt, va_list arg);
398  int sscang(const char *buf, const char *fmt, ...);
399  #endif
400  #endif
401 
402  #if GFILE_NEED_STDIO && !defined(GFILE_NEED_STDIO_MUST_BE_OFF)
403  // Needed routines and definitions
404  size_t gstdioRead(void * ptr, size_t size, size_t count, GFILE *f);
405  size_t gstdioWrite(const void * ptr, size_t size, size_t count, GFILE *f);
406  int gstdioGetpos(GFILE *f, long int *pos);
407  int gstdioSeek(GFILE *f, size_t offset, int origin);
408  #define SEEK_SET 0
409  #define SEEK_CUR 1
410  #define SEEK_END 2
411 
412  // Stdio emulation
413  #define stdin gfileStdIn
414  #define stdout gfileStdOut
415  #define stderr gfileStdErr
416  #define FOPEN_MAX GFILE_MAX_GFILES
417  #define TMP_MAX GFILE_MAX_GFILES
418  #define FILENAME_MAX 256 // Use a relatively small number for an embedded platform
419  #define L_tmpnam FILENAME_MAX
420  #define P_tmpdir "/tmp/"
421  #define FILE GFILE
422  #define fopen(n,m) gfileOpen(n,m)
423  #define fclose(f) gfileClose(f)
424  #define fread(p,sz,cnt,f) gstdioRead(p,sz,cnt,f)
425  #define fwrite(p,sz,cnt,f) gstdioWrite(p,sz,cnt,f)
426  #define fseek(f,ofs,org) gstdioSeek(f,ofs,org)
427  #define remove(n) (!gfileDelete(n))
428  #define rename(o,n) (!gfileRename(o,n))
429  #define fflush(f) (0)
430  #define ftell(f) gfileGetPos(f)
431  #define fpos_t long int
432  #define fgetpos(f,pos) gstdioGetpos(f,pos)
433  #define fsetpos(f, pos) (!gfileSetPos(f, *pos))
434  #define rewind(f) gfileSetPos(f, 0);
435  #define feof(f) gfileEOF(f)
436  #define vfprintf(f,m,a) vfnprintg(f,0,m,a)
437  #define fprintf(f,m,...) fnprintg(f,0,m,__VA_ARGS__)
438  #define vprintf(m,a) vfnprintg(gfileStdOut,0,m,a)
439  #define printf(m,...) fnprintg(gfileStdOut,0,m,__VA_ARGS__)
440  #define vsnprintf(s,n,m,a) vsnprintg(s,n,m,a)
441  #define snprintf(s,n,m,...) snprintg(s,n,m,__VA_ARGS__)
442  #define vsprintf(s,m,a) vsnprintg(s,0,m,a)
443  #define sprintf(s,m,...) snprintg(s,0,m,__VA_ARGS__)
444 
445  //TODO
446  //void clearerr ( FILE * stream );
447  //int ferror ( FILE * stream );
448  //FILE * tmpfile ( void ); // Auto-deleting
449  //char * tmpnam ( char * str );
450  //char * mktemp (char *template);
451  //FILE * freopen ( const char * filename, const char * mode, FILE * stream );
452  //setbuf
453  //setvbuf
454  //fflush
455  //fgetc
456  //fgets
457  //fputc
458  //fputs
459  //getc
460  //getchar
461  //puts
462  //ungetc
463  //void perror (const char * str);
464  #endif
465 
466 #ifdef __cplusplus
467 }
468 #endif
469 
470 #endif /* GFX_USE_GFILE */
471 
472 #endif /* _GFILE_H */
473 /** @} */
474 
bool_t gfileUnmount(char fs, const char *drive)
Unmount a logical drive (aka partition)
long int gfileGetPos(GFILE *f)
Get the current position of the read/write cursor.
bool_t gfileRename(const char *oldname, const char *newname)
Rename file.
size_t gfileWrite(GFILE *f, const void *buf, size_t len)
Write to file.
bool_t gfileDelete(const char *fname)
Delete file.
GFILE * gfileOpenChibiOSFileStream(void *FileStreamPtr, const char *mode)
Open file from a ChibiOS FileStream.
struct GFILE GFILE
A file pointer.
Definition: gfile.h:34
bool_t gfileEOF(GFILE *f)
Check for EOF.
long int gfileGetSize(GFILE *f)
Get the size of file.
gfileList * gfileOpenFileList(char fs, const char *path, bool_t dirs)
Open a file list.
GFILE * gfileOpenMemory(void *memptr, const char *mode)
Open file from a memory pointer.
const char * gfileReadFileList(gfileList *pfl)
Get the next file in a file list.
size_t gfileRead(GFILE *f, void *buf, size_t len)
Read from file.
bool_t gfileSync(GFILE *f)
Syncs the file object (flushes the buffer)
bool_t gfileSetPos(GFILE *f, long int pos)
Set the position of the read/write cursor.
void gfileCloseFileList(gfileList *pfl)
Close a file list.
long int gfileGetFilesize(const char *fname)
Get the size of a file.
void gfileClose(GFILE *f)
Close file.
GFILE * gfileOpen(const char *fname, const char *mode)
Open file.
GFILE * gfileOpenString(char *str, const char *mode)
Open file from a null terminated C string.
bool_t gfileMount(char fs, const char *drive)
Mount a logical drive (aka partition)
bool_t gfileExists(const char *fname)
Check if file exists.