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