version 2.8
gfile_options.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_options.h
10  * @brief GFILE - File IO options header file.
11  *
12  * @addtogroup GFILE
13  * @{
14  */
15 
16 #ifndef _GFILE_OPTIONS_H
17 #define _GFILE_OPTIONS_H
18 
19 /**
20  * @name GFILE Functionality to be included
21  * @{
22  */
23  /**
24  * @brief Should the filesystem not be mounted automatically
25  * @details The filesystem is normally mounted automatically if the
26  * user does not do it manually. This option turns that off
27  * so the user must manually mount the file-system first.
28  * @details Defaults to FALSE
29  */
30  #ifndef GFILE_NEED_NOAUTOMOUNT
31  #define GFILE_NEED_NOAUTOMOUNT FALSE
32  #endif
33  /**
34  * @brief Should the filesystem be synced automatically
35  * @details The filesystem will automatically be synced after an open() or
36  * write() call unless this feature is disabled.
37  * @details If this feature is disabled, the user should sync the filesystem
38  * himself using @p gfileSync()
39  * @details Not all filesystems implement the syncing feature. This feature will
40  * have no effect in such a case.
41  * @details Defaults to FALSE
42  */
43  #ifndef GFILE_NEED_NOAUTOSYNC
44  #define GFILE_NEED_NOAUTOSYNC FALSE
45  #endif
46  /**
47  * @brief Include printg, fprintg etc functions
48  * @details Defaults to FALSE
49  * @pre To get the string sprintg functions you also need to define @p GFILE_NEED_STRINGS
50  */
51  #ifndef GFILE_NEED_PRINTG
52  #define GFILE_NEED_PRINTG FALSE
53  #endif
54  /**
55  * @brief Include scang, fscang etc functions
56  * @details Defaults to FALSE
57  * @pre To get the string sscang functions you also need to define @p GFILE_NEED_STRINGS
58  */
59  #ifndef GFILE_NEED_SCANG
60  #define GFILE_NEED_SCANG FALSE
61  #endif
62  /**
63  * @brief Include the string based file functions
64  * @details Defaults to FALSE
65  */
66  #ifndef GFILE_NEED_STRINGS
67  #define GFILE_NEED_STRINGS FALSE
68  #endif
69  /**
70  * @brief Map many stdio functions to their GFILE equivalent
71  * @details Defaults to FALSE
72  * @note This replaces the functions in stdio.h with equivalents
73  * - Do not include stdio.h as it has different conflicting definitions.
74  */
75  #ifndef GFILE_NEED_STDIO
76  #define GFILE_NEED_STDIO FALSE
77  #endif
78  /**
79  * @brief Include the USER file system
80  * @details Defaults to FALSE
81  * @note The User FS vmt strcture 'FsUSERVMT' must be defined and implemented in the user's project.
82  * @note If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are
83  * opening a file on the USER file system by prefixing
84  * its name with "U|" (the letter 'U', followed by a vertical bar).
85  * The letter 'U' as described above should be replaced by the actual
86  * device specifier letter in the user's FsUSERVMT structure. It is suggested
87  * that it is actually the letter 'U' that is used and it is important that the letter
88  * used is not one used by the other file systems.
89  */
90  #ifndef GFILE_NEED_USERFS
91  #define GFILE_NEED_USERFS FALSE
92  #endif
93  /**
94  * @brief Include the ROM file system
95  * @details Defaults to FALSE
96  * @note If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are
97  * opening a file on the ROM file system by prefixing
98  * its name with "S|" (the letter 'S', followed by a vertical bar).
99  * @note This requires a file called romfs_files.h to be in the
100  * users project include path. This file should include all the files
101  * converted to .h files using the file2c utility (using flags "-dbcs").
102  */
103  #ifndef GFILE_NEED_ROMFS
104  #define GFILE_NEED_ROMFS FALSE
105  #endif
106  /**
107  * @brief Include the RAM file system
108  * @details Defaults to FALSE
109  * @note If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are
110  * opening a file on the RAM file system by prefixing
111  * its name with "R|" (the letter 'R', followed by a vertical bar).
112  * @note You must also define GFILE_RAMFS_SIZE with the size of the file system
113  * to be allocated in RAM.
114  */
115  #ifndef GFILE_NEED_RAMFS
116  #define GFILE_NEED_RAMFS FALSE
117  #endif
118  /**
119  * @brief Include the FAT file system driver based on the FATFS library
120  * @details Defaults to FALSE
121  * @note If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are
122  * opening a file on the FAT file system by prefixing
123  * its name with "F|" (the letter 'F', followed by a vertical bar).
124  * @note FATFS and PETITFS offer the same FAT file system support. They just use
125  * different constraints. PETITFS is smaller but has less features. Only
126  * one can be used at a time. The block interfaces are also different.
127  */
128  #ifndef GFILE_NEED_FATFS
129  #define GFILE_NEED_FATFS FALSE
130  #endif
131  /**
132  * @brief Include the FAT file system driver based on the PETITFS library
133  * @details Defaults to FALSE
134  * @note If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are
135  * opening a file on the FAT file system by prefixing
136  * its name with "F|" (the letter 'F', followed by a vertical bar).
137  * @note FATFS and PETITFS offer the same FAT file system support. They just use
138  * different constraints. PETITFS is smaller but has less features. Only
139  * one can be used at a time. The block interfaces are also different.
140  * @note Due to the restrictions on the PETITFS library on writing, we do not implement
141  * writing.
142  * @note PETITFS can only have one file open at a time.
143  */
144  #ifndef GFILE_NEED_PETITFS
145  #define GFILE_NEED_PETITFS FALSE
146  #endif
147  /**
148  * @brief Include the operating system's native file system
149  * @details Defaults to FALSE
150  * @note If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are
151  * opening a file on the native file system by prefixing
152  * its name with "N|" (the letter 'N', followed by a vertical bar).
153  * @note If defined then the gfileStdOut and gfileStdErr handles
154  * use the operating system equivalent stdio and stderr.
155  * If it is not defined the gfileStdOut and gfileStdErr io is discarded.
156  */
157  #ifndef GFILE_NEED_NATIVEFS
158  #define GFILE_NEED_NATIVEFS FALSE
159  #endif
160  /**
161  * @brief Include ChibiOS BaseFileStream support
162  * @details Defaults to FALSE
163  * @pre This is only relevant on the ChibiOS operating system.
164  * @note Use the @p gfileOpenBaseFileStream() call to open a GFILE based on a
165  * BaseFileStream. The BaseFileStream must already be open.
166  * @note A GFile of this type cannot be opened by filename. The BaseFileStream
167  * must be pre-opened using the operating system.
168  */
169  #ifndef GFILE_NEED_CHIBIOSFS
170  #define GFILE_NEED_CHIBIOSFS FALSE
171  #endif
172  /**
173  * @brief Include raw memory pointer support
174  * @details Defaults to FALSE
175  * @note Use the @p gfileOpenMemory() call to open a GFILE based on a
176  * memory pointer. The GFILE opened appears to be of unlimited size.
177  * @note A GFile of this type cannot be opened by filename.
178  */
179  #ifndef GFILE_NEED_MEMFS
180  #define GFILE_NEED_MEMFS FALSE
181  #endif
182  /**
183  * @brief Include support for file list functions
184  * @details Defaults to FALSE
185  * @note Adds support for @p gfileOpenFileList(), @p gfileReadFileList() and @p gfileCloseFileList().
186  */
187  #ifndef GFILE_NEED_FILELISTS
188  #define GFILE_NEED_FILELISTS FALSE
189  #endif
190 /**
191  * @}
192  *
193  * @name GFILE Optional Parameters
194  * @{
195  */
196  /**
197  * @brief Add floating point support to printg/scang etc.
198  */
199  #ifndef GFILE_ALLOW_FLOATS
200  #define GFILE_ALLOW_FLOATS FALSE
201  #endif
202  /**
203  * @brief Can the device be specified as part of the file name.
204  * @note If this is on then a device letter and a vertical bar can be
205  * prefixed on a file name to specify that it must be on a
206  * specific device.
207  */
208  #ifndef GFILE_ALLOW_DEVICESPECIFIC
209  #define GFILE_ALLOW_DEVICESPECIFIC FALSE
210  #endif
211  /**
212  * @brief The maximum number of open files
213  * @note This count excludes gfileStdIn, gfileStdOut and gfileStdErr
214  * (if open by default).
215  */
216  #ifndef GFILE_MAX_GFILES
217  #define GFILE_MAX_GFILES 3
218  #endif
219  /**
220  * @brief TUse an external FATFS library instead of the uGFX inbuilt one
221  * @note This is applicable when GFILE_NEED_FATFS is specified. It allows
222  * the programmer to use their own FATFS implementation provided the
223  * api matches the fatfs-0.10b API.
224  * @note The users ffconf.h file still needs to be reachable when compiling uGFX.
225  * @note If ffconf.h contains _FS_REENTRANT as true then the user provided simpleton
226  * routines must be compatible with uGFX threading.
227  * @note If ffconf.h contains _USE_LFN == 3 then the user provided simpleton routines must
228  * be compatible with uGFX memory management.
229  */
230  #ifndef GFILE_FATFS_EXTERNAL_LIB
231  #define GFILE_FATFS_EXTERNAL_LIB FALSE
232  #endif
233  /**
234  * @brief TUse an external PETITFS library instead of the uGFX inbuilt one
235  * @note This is applicable when GFILE_NEED_PETITFS is specified. It allows
236  * the programmer to use their own FATFS implementation provided the
237  * api matches the petitfs-0.03 API.
238  * @note The users pffconf.h file still needs to be reachable when compiling uGFX.
239  */
240  #ifndef GFILE_PETITFS_EXTERNAL_LIB
241  #define GFILE_PETITFS_EXTERNAL_LIB FALSE
242  #endif
243 
244 /** @} */
245 
246 #endif /* _GFILE_OPTIONS_H */
247 /** @} */